Open API endpoints en limieten

Voordat je begint

Je hebt toegang tot de Open API nodig voordat een call werkt: een client die e-tailize heeft goedgekeurd, en de key en secret die daarbij horen.

Versie 1 van de API staat onder https://app.e-tailize.eu/public/api/v1 en telt 17 endpoints in drie gebieden: Auth, Connections en Products. De volledige lijst, met de velden van elke call, staat in Swagger op https://app.e-tailize.eu/swagger/index.html.

De API praat alleen JSON en geeft een fout terug als application/problem+json.

Stappen

1. Kies het gebied waar je call bij hoort. Auth vraagt toegang aan en maakt, controleert en trekt een key in. Connections bevat de catalogus van wat je kunt koppelen, je koppelingen, orders, zendingen en doorstuurregels. Products bevat je producten en hun voorraad.
2. Zet de headers van dat gebied: X-Api-ClientId bij Auth, en X-Api-Key plus X-Api-Secret bij Connections en Products, waar ze allebei verplicht zijn. De eerste aanvraag om toegang is de uitzondering, die gaat zonder header.
3. Stuur Accept: */* bij elke call mee. Een client die alleen application/json accepteert krijgt een 406 terug in plaats van de fout die hij nodig heeft.
4. Roep GET /Connections/definitions aan voordat je een koppeling aanmaakt. Je krijgt de velden terug die elke marketplace vraagt, en de namen in connectionFields zijn hoofdlettergevoelig, dus neem ze precies over.
5. Koppel je eigen SKU's aan de ids die je producten in e-tailize hebben met GET /Products. Je krijgt een pagina met resultaten terug, dus je bladert erdoorheen.
6. Werk één voorraadstand bij met PUT /Products/{id}/stock en een body met de nieuwe voorraad, bijvoorbeeld 25 stuks. Lees succeeded in het antwoord, want data is altijd false, ook bij een geslaagde call.
7. Houd elke route binnen zijn eigen budget: Auth en Connections 10 requests per 60 seconden, GET /Products 30 per 60 seconden, PUT /Products/{id}/stock 25 per 10 seconden. De teller loopt per route, per IP en per key, en hij loopt niet geleidelijk leeg: elke call herstart de klok van die periode. De header Retry-After zegt hoelang die periode nog loopt.
8. Wacht de hele periode af als een call 429 teruggeeft met de titel "Too many requests." en, onder errors.general, de melding "Rate limit exceeded. Try again in 60 seconds.", waarbij het getal gelijk is aan de periode van die route. Wacht het aantal seconden dat de header Retry-After noemt, een kaal aantal seconden en de enige header die de limiter toevoegt. Eerder opnieuw proberen herstart de klok alleen maar.

Wat er daarna gebeurt

Wat je instuurt is gewone data van het platform. Een koppeling die je post staat gewoon op de pagina "API connections", net als elke andere, en een voorraadupdate volgt de doorstuurregels van die koppeling, de regels die je teruglest met GET /Connections/mutation-propagation-targets.

Die regels bepalen de richting: voorraad gaat van jou naar de marketplace, orders komen van de marketplace naar jou, en track en trace gaat per koppeling naar buiten, of per zending met POST /Connections/{id}/shipment.

Veelvoorkomende problemen

Een call zonder de header met je key geeft 400 terug, geen 401. De titel is "One or more validation errors occurred." en onder errors.general staat wat er mis is: "X-Api-Key header is missing." bij een ontbrekende key, "X-Api-Secret header is missing." bij een lege secret en "Invalid X-Api-Key header value." bij een key die geen GUID is. De melding staat altijd onder errors.general, nooit in een veld detail.

Een 401 betekent dat de header er wel is en goed is opgebouwd, maar niet wordt geaccepteerd: de client is nog niet goedgekeurd, de key of de secret klopt niet, of de key is verlopen.

Een connection id dat niet van jou is geeft 404, hetzelfde als een id dat niet bestaat, dus het antwoord verraadt nooit welke ids er zijn.

Een POST /Connections die de validatie niet haalt, bijvoorbeeld een dubbele naam, kan als 500 terugkomen. Lees de melding in die body, daar staat de echte oorzaak.

Veelgestelde vragen

Waar vind ik elk endpoint en zijn velden?

In Swagger, op https://app.e-tailize.eu/swagger/index.html, met de parameters en de antwoorden van alle 17 endpoints. Controleer een echt antwoord voordat je op de vorm van een foutbody vertrouwt, zodat je client het echte gedrag volgt.

Kan ik twee API-sleutels tegelijk hebben?

Nee. Genereren weigert een tweede actieve key voor dezelfde gebruiker. Roteren betekent dus eerst de key intrekken die je hebt, en daarna een nieuwe maken.

Is een order id uniek?

Alleen binnen één marketplace. Twee marketplaces kunnen je hetzelfde order id geven, dus sleutel je eigen administratie op de definitie van de koppeling samen met het order id, nooit op het id alleen.

Gerelateerd

• Open API toegang en sleutels
• Stuur orders door en houd track en trace op gang
• Synchroniseer je voorraad naar je marketplaces
• Een koppeling aanpassen, opnieuw opslaan of verwijderen