Zum Hauptinhalt springen

QrX Connect: Ihre Plattform per OAuth verbinden

So erhalten Plattformen mit QrX Connect über OAuth und PKCE sicher den API-Schlüssel des QrX-Kanals eines Händlers, ohne dass der Schlüssel kopiert werden muss.

H
Verfasst von Hayko

QrX Connect: Ihre Plattform per OAuth verbinden

Mit QrX Connect kann ein Händler seinen QrX-Kanal mit Ihrem System verbinden (zum Beispiel einer Commerce-App, einem WMS oder einem individuellen Shop), ohne einen API-Schlüssel kopieren und einfügen zu müssen. Der Händler meldet sich bei QrX an, wählt einen Kanal und klickt auf Allow (Zulassen), und Ihr Server erhält den API-Schlüssel dieses Kanals. Danach rufen Sie dieselbe QrX Public API auf wie jede andere Händlerintegration. Die QrX Shopify-App nutzt QrX Connect.

Was Sie von QrX benötigen

  • Eine client id für Ihre Integration. Jede Integration erhält ihre eigene.

  • Ihre Callback-URL auf Ihrem eigenen System, nur HTTPS, registriert für diesen Client. Nachdem der Händler auf Allow geklickt hat, leitet QrX zu dieser URL weiter.

Fordern Sie eine client id über qrx.eu/api oder beim QrX-Support an.

So funktioniert es

  1. QrX-Login öffnen. Leiten Sie den Händler zu https://portal.qr-x.app/oauth/authorize weiter, mit Ihrer client id, Ihrer Callback-URL, einem zufälligen state-Wert und einer PKCE-Challenge (S256).

  2. Der Händler wählt einen Kanal und klickt auf Allow. QrX leitet mit einem code und demselben state zu Ihrer Callback-URL weiter. Prüfen Sie, ob der state übereinstimmt.

  3. Ihr Server tauscht den Code ein. Senden Sie POST https://api.qr-x.net/api/v1/oauth/token als Formulardaten mit grant_type=authorization_code, client_id, code, redirect_uri (derselbe Callback) und code_verifier. Die Antwort enthält den merchantChannelApiKey des Kanals.

  4. Die API aufrufen. Tauschen Sie diesen Schlüssel mit POST /api/v1/auth/token gegen ein Zugriffstoken ein, genau wie bei einer direkten Integration.

Der Autorisierungscode kann einmal verwendet werden. Ein ungültiger oder abgelaufener Code liefert HTTP 400 mit invalid_grant; starten Sie den Ablauf dann erneut.

Was die Verbindung kann

Nur das, was ein normaler Händler-API-Schlüssel für diesen einen Kanal kann: Payment on Delivery-Sendungen erstellen, Labels erstellen sowie Zahlungs- und Tracking-Status abrufen. Sie kann weder Abrechnung noch Benutzer ändern, keine anderen Kanäle sehen und die Freigabe des QrX-Kontos nicht umgehen. Die Zahlung des Verbrauchers an der Haustür bleibt immer auf go.qr-x.app.

Sicherheitstipps

  • Speichern Sie den erhaltenen API-Schlüssel nur auf Ihrem Server, verschlüsselt, und niemals in einem Browser oder einer App.

  • Nehmen Sie keine Geheimnisse in die Callback-URL auf und geben Sie den Code nicht an einen anderen Origin weiter.

  • Wenn Sie vermuten, dass ein Schlüssel offengelegt wurde, verwenden Sie ihn nicht mehr und kontaktieren Sie gemeinsam mit dem Händler den QrX-Support.

Wann Sie unser Support-Team kontaktieren sollten

Kontaktieren Sie den QrX-Support unter [email protected], um eine client id oder Callback-URL anzufordern oder zu ändern, oder wenn der Token-Austausch mit einem gültigen Code wiederholt fehlschlägt.

Verwandte Artikel
Hat dies deine Frage beantwortet?