Fehlerbehebung bei API und Webhooks

Die meisten Probleme mit der QrX API und Webhooks lassen sich auf Authentifizierung, Kennungen, Rate Limits oder die Art zurückführen, wie Ihr Empfänger Webhooks verarbeitet. Prüfen Sie zuerst die folgenden Punkte. Die vollständige API-Referenz finden Sie unter qrx.eu/api.

Authentifizierungsfehler (401 oder 403)

Geschützte Endpoints benötigen Authorization: Bearer <token>, nicht den API-Schlüssel. Verwenden Sie den API-Schlüssel (Header QrX-MerchantChannel-API-Key) nur, um POST /api/v1/auth/token aufzurufen.
Access Tokens sind eine Stunde gültig. Fordern Sie ein neues Token an, wenn es abläuft.
Jeder API-Schlüssel gehört zu genau einem Merchant Channel. Ein Token kann keine Daten eines anderen Kanals lesen oder ändern.
Prüfen Sie, ob der Schlüssel in PortalX unter Settings, Merchant channels nicht gelöscht oder ersetzt wurde.
403 mit dem Code STOCK_SCOPE_MISSING (oder dem entsprechenden Code für Retouren oder Wareneingang): Der API-Schlüssel ist eingeschränkt, und der aufgerufene Teil ist nicht angehakt. Haken Sie ihn im Block API-Zugriff des Vertriebskanals an und warten Sie 30 Sekunden. Siehe "Einen API-Schlüssel einschränken (API-Zugriff)".
403 mit dem Code ACCESS_DENIED an einem Bestands-Endpunkt: Der QrX-Lagerbestand ist für das Konto nicht eingeschaltet.

Zu viele Anfragen (429)

Rate Limits gelten pro API-Schlüssel oder Kanal des Händlers. Zum Beispiel erlaubt der Token-Endpoint 60 Anfragen pro Minute und das Erstellen von Transaktionen 300 Anfragen pro Minute pro Kanal. Eine 429-Antwort enthält die Header Retry-After und RateLimit-Reason sowie den Code RATE_LIMIT_EXCEEDED. Warten Sie mindestens die in Retry-After angegebene Anzahl Sekunden, bevor Sie es erneut versuchen, und verwenden Sie Ihr Access Token wieder, statt für jeden Aufruf ein neues anzufordern.

Transaktion erstellt, aber noch nicht bezahlt

Ein HTTP 201 beim Erstellen bedeutet, dass QrX die Transaktion angenommen hat. Es ist kein Zahlungsnachweis. Die Zahlungssitzung beim PSP kann im Hintergrund erstellt werden, und die Zahlung erfolgt später an der Tür. Verfolgen Sie die Transaktion über Webhooks oder den Status-Endpoint und liefern Sie Ware erst aus oder geben Sie sie erst frei, wenn die Transaktion bezahlt ist. Wenn die Erstellung eines Versandetiketts angefordert wird und fehlschlägt, gibt die Erstellungsanfrage selbst einen Fehler zurück.

Weitere häufige Probleme

Ungültiger Betrag, ungültige Währung, ungültiges Land, ungültige Locale oder Versandart. Verwenden Sie die Referenz-Endpoints, um gültige Werte abzurufen.
Fehlende E-Mail-Adresse oder Telefonnummer des Kunden, die für Zahlungslinks, PIN-Zustellung und Support benötigt werden.
Test und Live verwechselt. Transaktionen, die mit testMode: true erstellt wurden, erzeugen niemals echte Zahlungen oder Auszahlungen und dürfen nicht als echte Bestellungen behandelt werden.
Einen Retourenbefehl mit einem neuen Idempotency-Key wiederholen. Verwenden Sie denselben Schlüssel, wenn Sie denselben Befehl wiederholen; verwenden Sie einen neuen Schlüssel nur für einen neuen Befehl.
Bestandskorrekturen: POST /api/v1/stock/adjust ohne Idempotency-Key-Header antwortet mit 400 IDEMPOTENCY_KEY_REQUIRED; derselbe Schlüssel mit einem anderen Body antwortet mit 409 DUPLICATE_IDEMPOTENCY_KEY; 409 STOCK_CONFLICT bedeutet nicht genug Bestand, zugeteilter Bestand oder eine SKU, die zu mehreren Artikeln passt. Siehe "Bestands- und Lager-API".

Webhook-Prüfungen

Erreichbar und schnell: Ihr Endpoint muss öffentlich über HTTPS erreichbar sein und schnell einen 2xx-Status zurückgeben. Erledigen Sie langsame Arbeit erst nach der Antwort.
Signatur: Verifizieren Sie den Header X-QrX-Signature. Er hat die Form sha256=<hex>, ein HMAC-SHA256 des rohen Request-Bodys mit Ihrem Webhook Signing Secret. Berechnen Sie ihn über genau die Bytes, die Sie empfangen haben, bevor Sie das JSON parsen.
Rotiertes Secret: Aktualisieren Sie nach dem Rotieren des Signing Secrets Ihren Empfänger, sonst schlagen die Signaturprüfungen fehl.
Duplikate: Wiederholungen und erneute Zustellungen können dasselbe Ereignis mehr als einmal senden. Verwenden Sie den Header X-QrX-Delivery-Id und die Ereignisdaten, um jedes Ereignis nur einmal zu verarbeiten.
Ereignistypen: Der Header X-QrX-Event nennt Ihnen das Ereignis. Abonnieren Sie nur die Ereignisse, die Sie verarbeiten.
Bestandsereignisse: Erkennen Sie Duplikate an eventId und ignorieren Sie bei stock/adjusted ein Ereignis, dessen sequence niedriger ist als die letzte, die Sie für diesen Artikel und dieses Lager gespeichert haben. Siehe "Bestands- und Lager-Webhooks".

Webhook-Status und Zustellprotokolle

Jedes Webhook-Abonnement in PortalX zeigt einen Gesundheitsstatus. Wenn ein Endpoint dauerhaft fehlschlägt, sendet QrX Warn-E-Mails an die konfigurierten Empfänger und deaktiviert das Abonnement nach etwa 24 Stunden mit Fehlern automatisch; es kann wieder aktiviert werden, nachdem der Endpoint repariert wurde. Verwenden Sie das Zustellprotokoll (in PortalX oder über die API), um jeden Versuch einschließlich Anfrage, Antwort und Wiederholungen zu prüfen und eine fehlgeschlagene Zustellung erneut zu senden. Sie können auch einen Test-Webhook senden, um Ihren Empfänger zu prüfen.

Was Sie an den Support senden sollten

Senden Sie die Umgebung (Test oder Live), den Merchant Channel, die Bestellreferenz, die QrX-Transaktions-ID, den Zeitstempel, den Endpoint, den Antwortstatus, die Webhook-Delivery-ID und einen bereinigten Request- oder Response-Body. Entfernen Sie API-Schlüssel, Access Tokens, Signaturen, Secrets, Passwörter und personenbezogene Daten, die nicht benötigt werden.

Wann Sie sich an unser Support-Team wenden sollten

Wenden Sie sich direkt an den QrX Support bei API-Problemen mit offengelegten Zugangsdaten, Sicherheit, Produktionsvorfällen, Unstimmigkeiten bei Zahlungen, unerklärlichen Fehlern bei Webhook-Signaturen oder wiederholten Integrationsfehlern. Diese werden immer von einem Mitarbeiter bearbeitet. Den aktuellen Plattformstatus finden Sie unter status.qr-x.app.

Verwandte Artikel