🛒 Hoe gebruik ik de BoozOrder API om bestellingen door te sturen?
🛒

Hoe gebruik ik de API om bestellingen door te sturen?

BoozOrder – Integraties / API

Tags: api, integratie, bestellingen, bearer token, swagger

 

📌 Samenvatting

Via de BoozOrder Customer API kan u vanuit uw eigen systeem bestellingen doorsturen en prijzen, producten en bestelhistoriek raadplegen voor de klanten aan wie uw account gekoppeld is. Elke aanroep vereist een geldig bearer token.

 

📝 Beschrijving

De BoozOrder Customer API is een REST API waarmee externe systemen bestellingen kunnen plaatsen en prijzen, producten en bestelhistoriek kunnen raadplegen in het BoozOrder-platform. 

Uw token geeft enkel toegang tot de klanten waaraan uw account gekoppeld is, en enkel tot wat voor elke klant afzonderlijk is toegestaan (bestellen, prijzen zien, bestelhistoriek zien). Alle beschikbare API calls vindt u terug op de Swagger-pagina:

BoozeOrder Customer API – Swagger

ℹī¸ Deze pagina beschrijft enkel hoe u toegang krijgt en een bearer token aanmaakt. De technische documentatie van de individuele API calls (endpoints, parameters, responses) vindt u zelf terug op de Swagger-pagina.

 

🛠ī¸ Stappen

1. Vraag uw API-toegang aan

U heeft drie zaken nodig:

  • Het e-mailadres van uw webshopaccount
  • Een API key, een geheime sleutel gekoppeld aan dat account
  • Bevestiging dat dat account geactiveerd is voor API-toegang

Vraag deze gegevens op bij uw BoozOrder-beheerder.

 

2. Vraag een bearer token aan

Roep POST /api/auth aan met uw e-mailadres en API key. De response bevat:

  • een token
  • de vervaldatum van dat token (expiresAt)

⚠ī¸ Het token is 24 uur geldig. Vraag ruim voor het verstrijken van expiresAt een nieuw token aan zodat uw integratie niet onderbroken wordt.

 

3. Gebruik het token in uw aanroepen

Stuur het token mee in de Authorization-header van elke volgende aanroep, in dit formaat:

Authorization: Bearer <uw-token>

ℹī¸ Test u de API rechtstreeks vanuit de Swagger-pagina via de knop Authorize? Plak daar dan enkel het token zelf, zonder het woord "Bearer" — de pagina voegt dit automatisch toe. In uw eigen integratiecode moet u "Bearer" wÊl zelf toevoegen.

Is het token verlopen, dan krijgt u een 401-foutcode. Vraag in dat geval opnieuw een token aan via stap 2 — uw e-mailadres en API key blijven ongewijzigd, dit kan dus volledig automatisch verlopen.

 

4. Zoek op voor welke klanten u mag handelen

Roep GET /api/me aan. Dit geeft een lijst van alle klanten waaraan uw account gekoppeld is, met per klant:

  • de customerCode
  • wat u voor die klant mag doen (bv. bestellen, prijzen zien, bestelhistoriek zien)

⚠ī¸ Deze rechten worden per klant ingesteld door uw drankenhandel en bij elke aanroep gecontroleerd — een wijziging door de beheerder is dus onmiddellijk van toepassing, ook al is uw token nog geldig.

Gebruik enkel customerCode-waarden uit deze lijst in de volgende stappen. Stuurt u een customerCode waaraan u niet gekoppeld bent, dan krijgt u 403 POC_NOT_LINKED. Bent u wel gekoppeld maar niet gemachtigd voor de gevraagde actie, dan krijgt u 403 met een code die aangeeft wat ontbreekt, bv. POC_ORDER_NOT_ALLOWED. In beide gevallen wordt er niets aangemaakt of gewijzigd.

 

5. Vraag de productcodes op

Om een bestelling te kunnen plaatsen, heeft u eerst de juiste productcodes nodig. Roep hiervoor GET /api/products aan.

  • Parameters (optioneel): customerCode (toont enkel producten met een actieve prijs voor die klant), page (standaard 1), pageSize (standaard 100, max. 500)
  • Response: een lijst (items) met o.a. code, name, uom, subunitCount, vatPct, plus paginagegevens (totalCount, hasMore, nextUrl)
  • 404: de opgegeven customerCode bestaat niet

💡 Gebruik het veld code uit deze response als productcode in de volgende stap.

⚠ī¸ Eenzelfde code kan meerdere keren voorkomen, ÊÊn keer per eenheid (uom), bv. per bak (B) en per pallet (P). Noteer daarom ook het veld uom: u heeft het nodig in de volgende stap.

 

6. Plaats de bestelling

Roep POST /api/orders aan om de effectieve bestelling te plaatsen.

  • Body: customerCode, lines (array van code + quantity, optioneel uom), optioneel requestedDeliveryDate en notes
  • uom: dezelfde waarde als in GET /api/products (bv. B = bak, P = pallet). Verplicht wanneer een code voor die klant in meer dan ÊÊn eenheid bestaat; anders mag u het weglaten.
  • 200 (succes): response met orderId, orderNumber en eventueel een niet-blokkerende warning
  • 400 (fout): er wordt niets aangemaakt; response met errorCode en message (bv. onbekend product, geen prijsafspraak voor deze klant, kredietlimiet bereikt, of AMBIGUOUS_PRODUCT_CODE als een code in meerdere eenheden bestaat en er geen uom is meegestuurd)
  • 403 (niet toegelaten): POC_NOT_LINKED als u niet gekoppeld bent aan de klant, of POC_ORDER_NOT_ALLOWED als bestellen niet toegestaan is voor die klant

Voorbeeld van een orderlijn met eenheid:

{
  "customerCode": "...",
  "lines": [
    { "code": "1171", "uom": "B", "quantity": 3 }
  ]
}

ℹī¸ Via GET /api/orders/{id} ziet u per orderlijn ook de uom, zodat u kan nagaan in welke eenheid er besteld werd.

💡 Wilt u eerst controleren of een bestelling aanvaard zou worden zonder ze effectief aan te maken? Gebruik dan eerst POST /api/sandbox/orders.

 

🏁 Conclusie

Met een geldig bearer token kan u via de BoozOrder Customer API opzoeken voor welke klanten en welke acties u gemachtigd bent, productcodes opvragen en op basis daarvan bestellingen doorsturen. De technische details van elke individuele API call vindt u op de Swagger-pagina.

 

🔗 Gerelateerde Artikels