Voor ontwikkelaars

Commerce-API-resources

Lees eigen bestellingen, facturen, creditnota's, supporttickets en resources van optionele Modules.

Op deze pagina

Eigendom en paginering

Commerce-leesverzoeken in Core vereisen Sanctum-authenticatie en de bijbehorende tokenbevoegdheid. Lijsten zijn beperkt tot authenticated_customer(), worden op aflopend ID gesorteerd en bevatten 20 regels per pagina. Detailroutes controleren eveneens eigendom en geven 404 voor objecten van een andere klant. Een meegegeven customer_id verandert de ingelogde klant niet.

Core-lijsten gebruiken Laravel-resourcepaginering: data is een array, met daarnaast links en meta. Een detailresponse bevat één object onder data. Gebruik ?page=2 voor een volgende pagina; de controllers accepteren geen vrije paginagrootte. Leesverzoeken hebben geen JSON-body.

bash

curl 'https://shop.example.test/api/v1/orders?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl "https://shop.example.test/api/v1/invoices/$INVOICE_ID" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl 'https://shop.example.test/api/v1/credit-notes?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

curl "https://shop.example.test/api/v1/support-tickets/$TICKET_ID" \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

Bron: CommerceController. Het volledige endpointoverzicht vermeldt alle lijst- en detailpaden.

Gedeelde veldstructuren

Deze namen zijn verkorte schemaomschrijvingen in de documentatie, geen afzonderlijke endpoints:

Structuur	Velden
Klantsnapshot	`id`, `name`, `email`; kan afwijken van een later gewijzigd klantprofiel
Adressnapshot	`name`, `company`, `line1`, `line2`, `city`, `region`, `postal_code`, `country`, `phone`; waarden kunnen null zijn
Documentregel	`label` als string, `quantity` als integer, `unit_amount` als integer, `line_total_amount` als integer
Documentsamenvatting	`id` als integer, `number` als string, `status` als enumstring
Creditnotasamenvatting	`id` als integer, `number` als string, `total_amount` als integer

Bedragen zijn gehele getallen in de kleinste eenheid van de documentvaluta. Opgemaakte bedragen zijn weergaveteksten en kunnen vertaald zijn. Financiële responses bevatten zowel custom_properties als custom_properties_snapshot, beide gevuld vanuit de opgeslagen snapshot of []. Leid daaruit niet het huidige bewerkbare schema voor klanteigenschappen af.

Statuswaarden

Statusstrings komen uit afzonderlijke enums. Gebruik een betaalstatus niet als bestel- of factuurstatus:

Veld	Huidige waarden
Bestelling `status`	`pending`, `paid`, `cancelled`
Betaling `status`	`pending`, `paid`, `cancelled`, `failed`, `expired`, `refunded`, `partially_refunded`
Factuur `status`	`issued`, `paid`, `void`
Creditnota `status`	`issued`
Supportticket `status`	`open`, `pending`, `answered`, `closed`
Supportticket `priority`	`low`, `normal`, `high`

Dit zijn teruggegeven toestanden, geen toezegging dat een client iedere overgang kan aanvragen. Bronnen: OrderStatus, PaymentStatus, InvoiceStatus, CreditNoteStatus, TicketStatus en TicketPriority.

Bestelresource

GET /orders en GET /orders/{order} vereisen orders.read. Checkout retourneert hetzelfde resourcetype.

Veld	Structuur
`id`, `number`, `status`, `currency`	Integer-ID en strings
`customer`	Klantsnapshot
`billing`, `shipping`	Adressnapshots
`custom_properties`, `custom_properties_snapshot`	Opgeslagen snapshot, standaard `[]`
`subtotal_amount`, `total_amount`	Integerbedragen
`total_formatted`	Weergavetekst
`payment`	Null of onderstaande betaalsamenvatting
`invoice`	Null of samenvatting van de eerste factuur
`invoices`	Array met documentsamenvattingen
`credit_notes`	Array met creditnotasamenvattingen
`items`	Array met documentregels
`created_at`	Nullable ISO 8601-tijdstip

De betaalsamenvatting bevat status, amount, amount_formatted, refunded_amount en net_amount. Gatewaygeheimen en het volledige betaalobject van een provider worden niet teruggegeven. invoice is een handige verwijzing naar de eerste geladen factuur. Gebruik invoices voor bestellingen met meerdere documenten. Een creditnota en een daadwerkelijke terugbetaling zijn afzonderlijke records.

Bron: OrderResource. Bestelresponses laten het privétoegangstoken voor de storefront bewust weg. StorefrontApiTest controleert dit en het blokkeren van toegang tussen klanten.

Factuur- en creditnotaresources

GET /invoices en GET /invoices/{invoice} vereisen invoices.read. Een factuur bevat:

id, number, status, nullable datumveld issued_at en currency.
customer, billing, custom_properties en custom_properties_snapshot.
Integers subtotal_amount, tax_amount, total_amount en credited_amount, plus total_formatted.
Nullable order met id, number en status.
Arrays items en credit_notes met de bovenstaande structuren.

GET /credit-notes en GET /credit-notes/{creditNote} vereisen credit_notes.read. Een creditnota bevat:

id, number, status, reason, datumveld issued_at, invoice_id en currency.
customer, billing, custom_properties en custom_properties_snapshot.
Integers subtotal_amount, tax_amount en total_amount, plus total_formatted.
items met samenvattingen van documentregels.

De datumvelden bevatten alleen een datum, geen tijdstip. Deze JSON-endpoints downloaden geen PDF. Geen van beide resources bevat een publieke mutatiemethode of vrije document-HTML. Raadpleeg InvoiceResource en CreditNoteResource voordat je optionele velden in je client veronderstelt.

Supporttickets

GET /support-tickets en GET /support-tickets/{ticket} vereisen tickets.read. Beide geven id, number, subject, status, priority, nullable ISO 8601 last_reply_at en nullable ISO 8601 created_at terug.

Ook het detailendpoint blijft een samenvatting. Het retourneert geen berichten, bijlagen, medewerkersnotities of antwoordformulier. Core heeft geen v1-schrijfroutes om supporttickets te openen of erop te antwoorden. Bron: SupportTicketResource.

Endpoints van optionele Modules

Ingeschakelde Modules registreren deze routes via ModuleContext::apiRoutes(). Ze staan niet permanent in Core. Ze gebruiken api, auth:sanctum, throttle:api en bevoegdheidsmiddleware. De bestandsdownload voegt throttle:api-sensitive toe.

Module	Methode en pad onder `/api/v1`	Bevoegdheid
`subscriptions`	GET `/subscriptions` en `/subscriptions/{subscription}`	`subscriptions.read`
`provisioning`	GET `/services` en `/services/{instance}`	`services.read`
`digital`	GET `/downloads` en `/downloads/{token}`	`downloads.read`
`digital-delivery`	GET `/digital-secrets`	`digital_secrets.read`
`events`	GET `/event-tickets` en `/event-tickets/{token}`	`event_tickets.read`

Modulelijsten bevatten data en een compacte meta met current_page, last_page en total. Ze gebruiken 20 regels per pagina, met het hoogste ID eerst, en voegen niet de uitgebreide Core-paginering met links toe. Alle queries zijn klantgebonden. Deze registratieblokken bieden geen publieke v1-route voor serviceacties, abonnementsopzeggingen, ticketcheck-in of beheer van de voorraad digitale geheimen.

Abonnementen en geleverde services

Een abonnement bevat id, number, status, nullable productnaam product, interval, integer interval_count, integer price_amount, currency, nullable ISO 8601 current_period_end en next_billing_at, en boolean cancel_at_period_end.

Een service bevat id, number, status, nullable productnaam product, external_ref, nullable ISO 8601 activated_at en nullable ISO 8601 suspended_at. Beheergegevens van de provider worden niet ontsloten.

Bronnen: SubscriptionApiController en ServiceApiController.

Bestanden en digitale geheimen

Een downloadregel bevat token, nullable label en filename, download_count, download_limit, boolean can_download en ISO 8601 granted_at. Ingetrokken toegangsrechten ontbreken in de lijst. GET /downloads/{token} retourneert een gestreamd bestand in plaats van JSON, na controle van eigendom en leveringsvoorwaarden. Een onbeschikbare download kan 409 invalid_state geven.

bash

curl "https://shop.example.test/api/v1/downloads/$DOWNLOAD_TOKEN" \
  --header "Authorization: Bearer $AGOVENA_TOKEN" \
  --fail --output purchased-file.bin

Bewaar het token privé en controleer de responsestatus voordat je de uitvoer als bestand behandelt.

Een digitale-geheimregel bevat id, nullable productnaam product, status, value_hint, value en nullable ISO 8601 granted_at. value kan de geleverde inhoud als leesbare tekst bevatten. Dat gebeurt uitsluitend als de eigenaar de regel mag lezen; anders is de waarde null. Stuur deze responses niet naar analytics, gedeelde caches of algemene requestlogs. Dit endpoint toont niet de beschikbare geheime voorraad van de winkelier.

Bronnen: DownloadApiController en SecretApiController.

Toegangsbewijzen voor evenementen

Een toegangsbewijs bevat number, token, status, nullable event, venue, starts_at, ticket_type en checked_in_at. Tijdstippen gebruiken ISO 8601. De locatie van de uitvoering gaat voor op die van het evenement. De lijst sluit tickets met status void uit; de detailactie gebruikt die statusfilter niet. Het detailpad zoekt op tickettoken, niet op numeriek ID.

bash

curl 'https://shop.example.test/api/v1/event-tickets?page=1' \
  --header 'Accept: application/json' \
  --header "Authorization: Bearer $AGOVENA_TOKEN"

Bron: EventTicketController. Bekijk ModuleContext voor de gedeelde middleware en ApiTokenAbilities voor de koppeling tussen routenamen en tokenbevoegdheden.