Problemen met API en webhooks oplossen

De meeste problemen met de QrX API en webhooks komen neer op authenticatie, identificatoren, rate limits of de manier waarop uw ontvanger webhooks verwerkt. Controleer eerst de onderstaande punten. De volledige API-referentie staat op qrx.eu/api.

Authenticatiefouten (401 of 403)

Beveiligde endpoints vereisen Authorization: Bearer <token>, niet de API-sleutel. Gebruik de API-sleutel (header QrX-MerchantChannel-API-Key) alleen om POST /api/v1/auth/token aan te roepen.
Access tokens zijn één uur geldig. Vraag een nieuw token aan wanneer het verloopt.
Elke API-sleutel hoort bij één merchant channel. Een token kan geen gegevens van een ander kanaal lezen of wijzigen.
Controleer of de sleutel niet is verwijderd of vervangen in PortalX onder Settings, Merchant channels.
403 met de code STOCK_SCOPE_MISSING (of de overeenkomstige code voor retouren of inbound): de API-sleutel is beperkt en het onderdeel dat u aanroept is niet aangevinkt. Vink het aan in het blok API-toegang van het verkoopkanaal en wacht 30 seconden. Zie "Een API-sleutel beperken (API-toegang)".
403 met de code ACCESS_DENIED op een voorraad-endpoint: de QrX-magazijnvoorraad staat niet aan voor het account.

Te veel verzoeken (429)

Rate limits gelden per API-sleutel of kanaal van de webwinkel. Het token-endpoint staat bijvoorbeeld 60 verzoeken per minuut toe en het aanmaken van transacties 300 verzoeken per minuut per kanaal. Een 429-antwoord bevat de headers Retry-After en RateLimit-Reason en de code RATE_LIMIT_EXCEEDED. Wacht minstens het aantal seconden in Retry-After voordat u het opnieuw probeert, en hergebruik uw access token in plaats van voor elke aanroep een nieuw token aan te vragen.

Transactie aangemaakt maar nog niet betaald

Een HTTP 201 bij het aanmaken 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 betaling vindt later aan de deur plaats. Volg de transactie met webhooks of het status-endpoint, en lever of geef goederen pas vrij zodra de transactie is betaald. Als het aanmaken van een vervoerderslabel wordt gevraagd en mislukt, geeft het aanmaakverzoek zelf een fout terug.

Andere veelvoorkomende problemen

Ongeldig bedrag, valuta, land, locale of verzendmethode. Gebruik de referentie-endpoints om geldige waarden op te halen.
Ontbrekend e-mailadres of telefoonnummer van de klant, die nodig zijn voor betaallinks, PIN-bezorging en support.
Test en live door elkaar gehaald. Transacties die zijn aangemaakt met testMode: true maken nooit echte betalingen of uitbetalingen aan en mogen niet als echte bestellingen worden behandeld.
Een retouropdracht opnieuw proberen met een nieuwe Idempotency-Key. Hergebruik dezelfde sleutel wanneer u dezelfde opdracht opnieuw probeert; gebruik alleen een nieuwe sleutel voor een nieuwe opdracht.
Voorraadcorrecties: POST /api/v1/stock/adjust zonder Idempotency-Key-header geeft 400 IDEMPOTENCY_KEY_REQUIRED; dezelfde sleutel met een andere body geeft 409 DUPLICATE_IDEMPOTENCY_KEY; 409 STOCK_CONFLICT betekent niet genoeg voorraad, toegewezen voorraad of een SKU die bij meerdere artikelen past. Zie "Voorraad- en magazijn-API".

Webhookcontroles

Bereikbaar en snel: uw endpoint moet publiek bereikbaar zijn via HTTPS en snel een 2xx-status teruggeven. Voer traag werk uit nadat u hebt geantwoord.
Handtekening: verifieer de header X-QrX-Signature. Deze heeft de vorm sha256=<hex>, een HMAC-SHA256 van de ruwe request body met uw webhook signing secret. Bereken deze over exact de bytes die u hebt ontvangen, voordat u de JSON parseert.
Geroteerd secret: werk na het roteren van het signing secret uw ontvanger bij, anders mislukken de handtekeningcontroles.
Duplicaten: nieuwe pogingen en herbezorgingen kunnen dezelfde gebeurtenis meer dan eens versturen. Gebruik de header X-QrX-Delivery-Id en de gebeurtenisgegevens om elke gebeurtenis maar één keer te verwerken.
Gebeurtenistypen: de header X-QrX-Event vertelt u om welke gebeurtenis het gaat. Abonneer u alleen op de gebeurtenissen die u verwerkt.
Voorraadevents: herken dubbele events aan eventId en negeer bij stock/adjusted een event waarvan sequence lager is dan de laatste die u voor dat artikel en magazijn hebt bewaard. Zie "Voorraad- en magazijnwebhooks".

Webhookstatus en bezorglogs

Elk webhookabonnement in PortalX toont een gezondheidsstatus. Als een endpoint voortdurend faalt, stuurt QrX waarschuwingsmails naar de ingestelde ontvangers en schakelt het abonnement automatisch uit na ongeveer 24 uur aan fouten; het kan opnieuw worden ingeschakeld nadat het endpoint is hersteld. Gebruik de bezorglog (in PortalX of via de API) om elke poging te bekijken, inclusief het verzoek, het antwoord en de nieuwe pogingen, en om een mislukte bezorging opnieuw te versturen. U kunt ook een testwebhook versturen om uw ontvanger te controleren.

Wat u naar support stuurt

Stuur de omgeving (test of live), het merchant channel, de bestelreferentie, het QrX-transactie-id, het tijdstip, het endpoint, de antwoordstatus, het webhook delivery-id en een opgeschoonde request- of response-body. Verwijder API-sleutels, access tokens, handtekeningen, secrets, wachtwoorden en persoonsgegevens die niet nodig zijn.

Wanneer neemt u contact op met ons supportteam

Neem direct contact op met QrX support bij API-problemen met gelekte inloggegevens, beveiliging, productie-incidenten, inconsistenties in betalingen, webhook-handtekeningfouten die u niet kunt verklaren, of herhaalde integratiefouten. Deze worden altijd door een medewerker behandeld. Bekijk status.qr-x.app voor de actuele platformstatus.