API-overzicht

Basis-URL en contract

De klant- en winkel-API staat op https://<jouw-winkel>/api/v1. Deze documentatiepagina is /development/api en werkt niet als API-proxy. Gebruik HTTPS en stuur Accept: application/json. Voeg voor JSON-schrijfverzoeken ook Content-Type: application/json toe.

De routes staan in routes/api.php. Core registreert ook GET /api/v1/openapi.json. Dat retourneert OpenAPI 3.0.3 uit OpenApiDocument. Het document beschrijft handelingen, beveiliging en een deel van de requestvelden. Het bevat geen volledige resourceschema's en bewijst niet dat een Module op een installatie ingeschakeld is. v1 is nadrukkelijk een vroege interface, geen onveranderlijk publiek contract.

curl 'https://shop.example.test/api/v1/openapi.json' \
  --header 'Accept: application/json'

Alle domeinen, namen, ID's, tokens en productslugs in de voorbeelden zijn fictief. Vervang ze door waarden uit je eigen installatie. De JSON-voorbeelden tonen de structuur, geen opgenomen productieresponses.

Endpointcollectie

De paden hieronder zijn relatief aan /api/v1. Elke methode staat gegroepeerd zodat je de pagina kunt scannen als een API-clientcollectie. “Openbaar” betekent dat de route geen auth:sanctum vereist. Installatiecontroles en andere globale middleware blijven van toepassing. De bevoegdheden gelden voor bearer-tokens. Zie authenticatie voor sessies en tokenaanmaak.

GET · Lezen

POST · Aanmaken of starten

PATCH · Bijwerken

DELETE · Intrekken of verwijderen

De collectie hierboven volgt de actuele Core-routes. Core biedt via v1 geen publieke routes voor productaanmaak, factuurstatuswijzigingen, terugbetalingen, nieuwe supporttickets, packagebeheer of een PUT-handeling. De requests voor winkelwagen, checkout en betalingen staan in Winkelwagen- en checkout-API. Financiële resources, tickets en optionele Modulereponses staan in Commerce-API-resources.

Catalogus doorzoeken

GET /products selecteert actieve producten, sorteert op naam en gebruikt pagina's van 24 producten. De q-filter zoekt in naam of beschrijving als de getrimde zoekterm minstens twee tekens telt. category accepteert een categorieslug of ID. De controller biedt geen instelbare paginagrootte of willekeurige sortering.

GET /products/{slug} zoekt een actief product op slug, niet op numeriek ID. Ontbrekende of inactieve producten geven 404.

GET /search?q=... retourneert maximaal acht producten zonder paginator. Bij minder dan twee tekens na trimmen is de collectie leeg. De suggestieservice beperkt producten ook tot beschikbare capabilities. Ga er niet van uit dat alle catalogushandelingen intern exact dezelfde selectie gebruiken.

curl --get 'https://shop.example.test/api/v1/products' \
  --header 'Accept: application/json' \
  --data-urlencode 'q=lamp' \
  --data-urlencode 'category=verlichting' \
  --data-urlencode 'page=1'

curl 'https://shop.example.test/api/v1/products/leeslamp' \
  --header 'Accept: application/json'

curl --get 'https://shop.example.test/api/v1/search' \
  --header 'Accept: application/json' --data-urlencode 'q=lamp'

Productschema

Een enkel product staat onder data. De lijst gebruikt een data-array met daarnaast Laravel-pagineringsvelden links en meta.

Bedragen zijn gehele getallen in de kleinste munteenheid. Reken met het bedrag en de valuta, niet met de opgemaakte tekst. options beschrijft de beschikbare selectie, geen door de client vast te stellen eindprijs.

Categorieschema

GET /categories retourneert data: Category[]. Een categorie bevat id, name, slug, nullable image, integer products_count en children. Een geladen kind bevat id, name, slug en products_count. De serializer bouwt geen onbeperkt diepe Category-boom.

GET /categories/{slug}?page=1 gebruikt een andere omhulling:

{
  "data": {
    "category": {
      "id": 7,
      "name": "Verlichting",
      "slug": "verlichting",
      "image": null,
      "products_count": 0,
      "children": []
    },
    "products": []
  },
  "meta": {"current_page": 1, "last_page": 1, "total": 0}
}

Deze actie zoekt een actieve categorie en pagineert de actieve producten met 24 items per pagina. Alleen de getoonde metadata wordt toegevoegd, niet de volledige links-structuur van een Laravel-resourcecollectie.

Bronnen: CatalogController, ProductResource, CategoryResource en SuggestStorefrontProducts.

Huidig account

GET /me en PATCH /me retourneren:

{
  "data": {
    "id": 12,
    "name": "Alex Voorbeeld",
    "email": "[email protected]",
    "email_verified": true
  }
}

PATCH accepteert uitsluitend de verplichte string name, maximaal 255 tekens. Het endpoint wijzigt geen e-mailadres, wachtwoord, rollen of willekeurige klanteigenschappen.

curl --request PATCH 'https://shop.example.test/api/v1/me' \
  --header "Authorization: Bearer $AGOVENA_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Alex Voorbeeld"}'

Adressen lezen en opslaan

POST en PATCH gebruiken dezelfde validatie. PATCH is geen gedeeltelijke adreswijziging: name, line1, city, postal_code en country blijven verplicht.

De ondersteunde properties-sleutels zijn phone, company_name, address, address2, city, state, zip en country. De lengtes volgen de equivalente bovenliggende velden. properties.country wordt bovendien gecontroleerd tegen CheckoutCountries::codes(). Meegegeven aliassen krijgen voorrang bij het samenstellen van het opgeslagen adres, maar vervangen de verplichte top-level invoervelden niet.

curl --request POST 'https://shop.example.test/api/v1/addresses' \
  --header "Authorization: Bearer $AGOVENA_TOKEN" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"label":"Kantoor","name":"Alex Voorbeeld","line1":"Voorbeeldstraat 1","city":"Brussel","postal_code":"1000","country":"BE","is_default_billing":true}'

Een adresresource bevat id, label, de bovenstaande adresvelden, beide standaardvlaggen en een properties-object met de aliassen. GET /addresses sorteert opgeslagen adressen op aflopend ID. Als er geen adressen zijn, kan het endpoint een adres uit klanteigenschappen reconstrueren. Dat heeft id: null, standaardfacturatie aan en standaardverzending uit. Dit is geen opgeslagen adres dat je met dat ID kunt wijzigen of verwijderen.

Een adres-ID van een andere klant geeft 404. Als je een opgeslagen adres als standaard instelt, wordt dezelfde standaardvlag op de andere adressen van deze klant uitgezet. POST retourneert momenteel een opnieuw geladen resource zonder expliciet een aanmaakstatus in te stellen. Gebruik de beschrijvende 201 uit OpenAPI daarom niet als enige runtimeverwachting.

Bronnen: AccountController, AddressResource en SaveCustomerAddress.

Foutstructuur

Verwachte API-fouten gebruiken message en code op het hoogste niveau, met optionele veldfouten:

{
  "message": "<vertaalde validatiemelding>",
  "code": "validation_error",
  "errors": {"name": ["<vertaalde veldfout>"]}
}

Een leeg errors-veld wordt weggelaten. Gebruik vertaalde meldingsteksten niet als vaste identifiers. Het type exception bepaalt de code: validatie-exceptions worden validation_error, terwijl een algemene HTTP 422 invalid_state wordt. Onverwachte serverfouten hebben geen gegarandeerd domeinfoutenschema.

Bronnen: ApiError, exceptionafhandeling en StorefrontApiTest.