Schnellstart für Entwickler: QrX Public API und Webhooks

Mit der QrX Public API können Händler und Entwickler Payment on Delivery Transaktionen, Versandetiketten, Produkte, Rücksendungen und Webhooks erstellen und verwalten. Es handelt sich um eine REST API mit JSON, Bearer-Authentifizierung und signierten Webhooks. Die vollständige Referenz, live aus der API generiert, finden Sie unter qrx.eu/api.

Die Grundlagen

Basis-URL: https://api.qr-x.net
Format: JSON-Anfragen und -Antworten. Fehler verwenden application/problem+json mit einem maschinenlesbaren Code und einer lesbaren Meldung.
Spezifikation: OpenAPI, mit Codebeispielen in cURL, Node.js, C#, PHP und Python, einer "try it"-Konsole und einer fertigen Postman-Collection.
Zugang: Sie benötigen ein freigegebenes QrX-Händlerkonto. Registrieren Sie sich unter portal.qr-x.app oder beantragen Sie Zugang über qrx.eu/api.

Schritt 1: API-Schlüssel und Zugriffstoken erhalten

Öffnen Sie in PortalX Settings, Merchant channels (Einstellungen, Händlerkanäle) und erstellen Sie einen API-Schlüssel für den Vertriebskanal, den Sie anbinden möchten. Jeder Kanal hat einen eigenen Schlüssel.
Tauschen Sie den Schlüssel gegen ein Zugriffstoken: POST /api/v1/auth/token mit dem Header QrX-MerchantChannel-API-Key: YOUR_KEY. Die Antwort enthält accessToken und expiresIn (3600 Sekunden).
Senden Sie Authorization: Bearer <accessToken> bei jedem weiteren Aufruf mit. Fordern Sie ein neues Token an, wenn es abläuft.

Bewahren Sie den API-Schlüssel auf Ihrem Server auf. Legen Sie ihn niemals in einem Browser, einer mobilen App oder einem öffentlichen Repository ab.

Schritt 2: Eine Transaktion erstellen

POST /api/v1/transactions erstellt eine Payment on Delivery Transaktion. Der Body enthält Betrag, Währung, Locale, orderDetails (Bestell-ID, Kundenname, E-Mail, Telefon, Adresse und Bestellpositionen) und optional einen parcel-Block, um eine Versandart und einen Absender zu wählen und das Etikett des Versanddienstleisters im selben Aufruf zu erstellen. Verwenden Sie die Referenz-Endpunkte (/api/v1/reference/carriers, countries, locales, shipping-methods, senders), um gültige Werte abzurufen.

Die Antwort liefert die transactionId, den Wert des QR-Codes (ein Link auf go.qr-x.app) und das Bild sowie, wenn Sie ein Etikett angefordert haben, die Versandetiketten mit Sendungsnummer. Bei UPS Payment on Delivery enthält der Etikettensatz das QrX-Zahlungsetikett.

Wichtig: HTTP 201 bedeutet, dass QrX die Transaktion angenommen hat. Es ist kein Zahlungsnachweis. Die Zahlungssitzung beim PSP kann im Hintergrund erstellt werden, und der Kunde bezahlt später an der Tür.

Schritt 3: Das Ergebnis verfolgen

GET /api/v1/transactions/{id}/status gibt zurück, ob die Transaktion bezahlt oder offen ist.
POST /api/v1/transactions/{id}/ship speichert Sendungsdaten aus Ihrem eigenen System.
POST /api/v1/transactions/{id}/cancel storniert eine berechtigte offene Transaktion mit Angabe eines Grundes. Eine stornierte Transaktion kann nicht mehr bezahlt, etikettiert oder erfüllt werden.

Schritt 4: Webhooks abonnieren

Webhooks sind der zuverlässige Weg, Ihr System synchron zu halten, da die Zahlungsverarbeitung abgeschlossen werden oder fehlschlagen kann, nachdem Ihre Anfrage bereits zurückgekehrt ist.

Erstellen Sie einen Webhook mit POST /api/v1/webhooks: einen Namen, Ihre HTTPS-targetUrl, die gewünschten eventTypes (zum Beispiel transaction/created und transaction/paid) und eine API-Version.
Rufen Sie die aktuelle Liste der Ereignistypen und API-Versionen mit GET /api/v1/webhooks/event-types ab.
transaction/edited wird gesendet, wenn sich die Produkte einer unbezahlten Bestellung mit Zahlung an der Tür ändern (eine Position entfernt, eine neue Menge oder eine Position hinzugefügt), auch wenn der Betrag gleich bleibt. Es enthält eventId (zum Deduplizieren), transactionId, orderId, shopOrderId, editId, oldAmount, newAmount, currency, paymentLinkChanged sowie removedLines, changedLines und addedLines mit SKU, Name, alter und neuer Menge und Summen.
Jede Zustellung enthält die Header X-QrX-Event, X-QrX-Delivery-Id und X-QrX-Signature. Die Signatur hat die Form sha256=<hex>: ein HMAC-SHA256 des Roh-Bodys mit Ihrem Webhook-Signaturgeheimnis. Prüfen Sie sie, bevor Sie dem Ereignis vertrauen.
Antworten Sie schnell mit einem 2xx-Status und verarbeiten Sie das Ereignis danach. Behandeln Sie Duplikate sicher, da Wiederholungen und erneute Zustellungen vorkommen können.
Nutzen Sie die Endpunkte, um einen Test-Webhook zu senden, Zustellungen aufzulisten, eine Zustellung erneut auszuführen oder abzubrechen, einen deaktivierten Webhook wieder zu aktivieren und das Signaturgeheimnis zu rotieren.

Lagerbestand

Mit dem QrX-Lagerbestand lesen Sie Bestände, Bestandsartikel und Lagerplätze mit GET /api/v1/stock/levels, /items und /locations und buchen eine Korrektur mit POST /api/v1/stock/adjust. Die Webhook-Ereignisse stock/adjusted und stock/low melden, wenn sich Bestand ändert oder knapp wird. Siehe "Bestands- und Lager-API" und "Bestands- und Lager-Webhooks".

Testmodus

Setzen Sie testMode: true beim Erstellen einer Transaktion, um den vollständigen Ablauf zu testen. Testtransaktionen verwenden, wo verfügbar, eine Sandbox- oder Testkonfiguration, erzeugen niemals eine echte Zahlung oder Auszahlung und dürfen nicht als echte Bestellungen behandelt werden. Etiketten für Testkonten werden in der Sandbox des Versanddienstleisters erstellt.

Idempotenz

Befehle für Rücksendungen (etwa genehmigen, ablehnen, eine Lösung erfassen oder eine Nachricht posten) erfordern einen Idempotency-Key-Header mit höchstens 200 Zeichen. Verwenden Sie denselben Schlüssel erneut, wenn Sie denselben Befehl wiederholen, um dessen gespeichertes Ergebnis zu erhalten; verwenden Sie für einen neuen Befehl einen neuen Schlüssel. Nutzen Sie bei Transaktionen Ihre eigene Bestell-ID und Webhooks, um zu vermeiden, dass dieselbe Bestellung zweimal erstellt wird. POST /api/v1/stock/adjust erfordert ebenfalls einen Idempotency-Key-Header.

Rate Limits

Limits gelten pro Händler-API-Schlüssel oder Kanal, zum Beispiel 60 Token-Anfragen pro Minute und 300 Transaktionsbefehle pro Minute. Eine 429-Antwort enthält Retry-After und RateLimit-Reason. Warten Sie mindestens Retry-After Sekunden, bevor Sie es erneut versuchen, und verwenden Sie Ihr Zugriffstoken wieder.

Sie entwickeln für andere Händler?

Wenn Sie eine App, ein WMS oder eine Plattform entwickeln, die von vielen Händlern genutzt wird, verwenden Sie QrX Connect, damit Händler ihren QrX-Kanal verbinden können, ohne einen API-Schlüssel einzufügen. Siehe "QrX Connect: connecting your platform with OAuth".

Wann Sie unser Support-Team kontaktieren sollten

Kontaktieren Sie den QrX-Support unter [email protected] bei Fragen zum API-Zugang, bei Produktionsvorfällen, geleakten Zugangsdaten oder Signaturproblemen, die Sie sich nicht erklären können. Geben Sie die Umgebung, den Kanal, die Transaktions-ID, die ID der Webhook-Zustellung und eine bereinigte Anfrage an, niemals den Schlüssel, das Token oder das Geheimnis. Siehe auch "API and Webhook Troubleshooting".

Verwandte Artikel