Snelstart voor ontwikkelaars: QrX Public API en webhooks

Met de QrX Public API kunnen webwinkels en ontwikkelaars Payment on Delivery-transacties, verzendlabels, producten, retouren en webhooks aanmaken en beheren. Het is een REST API met JSON, Bearer-authenticatie en ondertekende webhooks. De volledige referentie, live gegenereerd vanuit de API, staat op qrx.eu/api.

De basis

Basis-URL: https://api.qr-x.net
Formaat: JSON-verzoeken en -antwoorden. Fouten gebruiken application/problem+json met een machineleesbare code en een leesbaar bericht.
Specificatie: OpenAPI, met codevoorbeelden in cURL, Node.js, C#, PHP en Python, een "try it"-console en een kant-en-klare Postman-collectie.
Toegang: u heeft een goedgekeurd QrX-webwinkelaccount nodig. Meld u aan op portal.qr-x.app of vraag toegang aan via qrx.eu/api.

Stap 1: een API-sleutel en een toegangstoken verkrijgen

Open in PortalX Settings, Merchant channels (Instellingen, Verkoopkanalen) en maak een API-sleutel aan voor het verkoopkanaal dat u wilt koppelen. Elk kanaal heeft een eigen sleutel.
Wissel de sleutel in voor een toegangstoken: POST /api/v1/auth/token met de header QrX-MerchantChannel-API-Key: YOUR_KEY. Het antwoord bevat accessToken en expiresIn (3600 seconden).
Stuur Authorization: Bearer <accessToken> mee bij elke andere aanroep. Vraag een nieuw token aan wanneer het verloopt.

Bewaar de API-sleutel op uw server. Plaats deze nooit in een browser, een mobiele app of een openbare repository.

Stap 2: een transactie aanmaken

POST /api/v1/transactions maakt een Payment on Delivery-transactie aan. De body bevat het bedrag, de valuta, de locale, orderDetails (order-id, naam van de klant, e-mail, telefoon, adres en orderregels) en optioneel een parcel-blok om een verzendmethode en afzender te kiezen en het label van de vervoerder in dezelfde aanroep aan te maken. Gebruik de referentie-endpoints (/api/v1/reference/carriers, countries, locales, shipping-methods, senders) om geldige waarden op te halen.

Het antwoord geeft de transactionId, de waarde van de QR-code (een link op go.qr-x.app) en de afbeelding terug, en, als u om een label heeft gevraagd, de verzendlabels met trackingnummer. Voor UPS Payment on Delivery bevat de labelset het QrX-betaallabel.

Belangrijk: HTTP 201 betekent dat QrX de transactie heeft geaccepteerd. Het is geen bewijs van betaling. De betaalsessie bij de PSP kan op de achtergrond worden aangemaakt, en de klant betaalt later aan de deur.

Stap 3: de uitkomst volgen

GET /api/v1/transactions/{id}/status geeft terug of de transactie betaald of open is.
POST /api/v1/transactions/{id}/ship slaat trackinggegevens uit uw eigen systeem op.
POST /api/v1/transactions/{id}/cancel annuleert een daarvoor in aanmerking komende open transactie met een reden. Een geannuleerde transactie kan niet meer worden betaald, van een label worden voorzien of worden afgehandeld.

Stap 4: abonneren op webhooks

Webhooks zijn de betrouwbare manier om uw systeem gesynchroniseerd te houden, omdat de betaalverwerking kan slagen of mislukken nadat uw verzoek al is teruggekeerd.

Maak een webhook aan met POST /api/v1/webhooks: een naam, uw HTTPS-targetUrl, de gewenste eventTypes (bijvoorbeeld transaction/created en transaction/paid) en een API-versie.
Haal de actuele lijst met eventtypes en API-versies op met GET /api/v1/webhooks/event-types.
transaction/edited wordt verstuurd als de producten van een onbetaalde order met betaling aan de deur veranderen (een regel verwijderd, een nieuw aantal of een regel toegevoegd), ook als het bedrag gelijk blijft. Het bevat eventId (gebruik dit om dubbele events te herkennen), transactionId, orderId, shopOrderId, editId, oldAmount, newAmount, currency, paymentLinkChanged en de removedLines, changedLines en addedLines met SKU, naam, oud en nieuw aantal en totalen.
Elke levering heeft de headers X-QrX-Event, X-QrX-Delivery-Id en X-QrX-Signature. De handtekening heeft de vorm sha256=<hex>: een HMAC-SHA256 van de ruwe body met uw ondertekeningsgeheim voor webhooks. Verifieer deze voordat u het event vertrouwt.
Antwoord snel met een 2xx-status en verwerk het event daarna. Ga veilig om met duplicaten, want nieuwe pogingen en herleveringen kunnen voorkomen.
Gebruik de endpoints om een testwebhook te versturen, leveringen op te vragen, een levering opnieuw te leveren of te annuleren, een uitgeschakelde webhook opnieuw in te schakelen en het ondertekeningsgeheim te roteren.

Magazijnvoorraad

Met QrX-magazijnvoorraad leest u voorraadstanden, voorraadartikelen en locaties met GET /api/v1/stock/levels, /items en /locations, en boekt u een correctie met POST /api/v1/stock/adjust. De webhook-events stock/adjusted en stock/low melden wanneer voorraad wijzigt of laag wordt. Zie "Voorraad- en magazijn-API" en "Voorraad- en magazijnwebhooks".

Testmodus

Stel testMode: true in bij het aanmaken van een transactie om de volledige flow te testen. Testtransacties gebruiken waar beschikbaar een sandbox- of testconfiguratie, maken nooit een echte betaling of uitbetaling aan en mogen niet als echte bestellingen worden behandeld. Labels voor testaccounts worden aangemaakt in de sandbox van de vervoerder.

Idempotentie

Commando's voor retouren (zoals goedkeuren, afwijzen, een oplossing vastleggen of een bericht plaatsen) vereisen een Idempotency-Key-header van maximaal 200 tekens. Gebruik dezelfde sleutel opnieuw wanneer u hetzelfde commando opnieuw probeert, om het opgeslagen resultaat te ontvangen; gebruik een nieuwe sleutel voor een nieuw commando. Gebruik voor transacties uw eigen order-id en webhooks om te voorkomen dat dezelfde bestelling twee keer wordt aangemaakt. POST /api/v1/stock/adjust vereist ook een Idempotency-Key-header.

Rate limits

Limieten gelden per API-sleutel of kanaal van de webwinkel, bijvoorbeeld 60 tokenverzoeken per minuut en 300 transactiecommando's per minuut. Een 429-antwoord bevat Retry-After en RateLimit-Reason. Wacht minimaal Retry-After seconden voordat u het opnieuw probeert, en hergebruik uw toegangstoken.

Bouwt u voor andere webwinkels?

Als u een app, WMS of platform bouwt dat door veel webwinkels wordt gebruikt, gebruik dan QrX Connect, zodat webwinkels hun QrX-kanaal kunnen koppelen zonder een API-sleutel te plakken. Zie "QrX Connect: connecting your platform with OAuth".

Wanneer u contact opneemt met ons supportteam

Neem contact op met QrX-support via [email protected] voor API-toegang, productie-incidenten, gelekte inloggegevens of handtekeningproblemen die u niet kunt verklaren. Vermeld de omgeving, het kanaal, de transactie-id, de id van de webhooklevering en een opgeschoond verzoek, nooit de sleutel, het token of het geheim. Zie ook "API and Webhook Troubleshooting".