Webhooks und API-Schlüssel in PortalX
Webhooks senden Echtzeitbenachrichtigungen an Ihr eigenes System, wenn in QrX etwas passiert, etwa eine Zahlung oder eine Zustellung. Mit API-Schlüsseln kann Ihr System Transaktionen über die QrX API erstellen. Die API-Dokumentation finden Sie unter qrx.eu/api.
API-Schlüssel
Jeder Vertriebskanal hat einen eigenen API-Schlüssel: Settings > Business > Merchant Channels (Einstellungen > Unternehmen > Händlerkanäle), Kanal öffnen, Registerkarte Settings, API Key (API-Schlüssel) (Berechtigung Manage Channels). Der Schlüssel wird sicher gespeichert und nur einmal vollständig angezeigt, wenn Sie auf Regenerate API Key (API-Schlüssel neu erzeugen) klicken. Kopieren Sie ihn sofort. Durch das Neuerzeugen funktioniert keine Integration mehr, die noch den alten Schlüssel verwendet.
Unter dem API-Schlüssel finden Sie den Block API-Zugriff. Ein Schlüssel beginnt mit Vollzugriff. Schalten Sie Diesen Schlüssel einschränken ein, um den Schlüssel auf die Teile der API zu beschränken, die Sie anhaken, zum Beispiel nur Bestand lesen. Siehe "Einen API-Schlüssel einschränken (API-Zugriff)".
Einen Webhook erstellen
Gehen Sie zu Settings > Advanced > Webhooks (Einstellungen > Erweitert > Webhooks).
Geben Sie einen Namen und Ihre Endpunkt-URL (https) ein.
Wählen Sie die API-Version und optional einen Kanal (oder All Channels).
Klicken Sie die Ereignisse an, die Sie erhalten möchten. Mit Customize payload (Payload anpassen) wählen Sie die Felder, die für ein Ereignis gesendet werden.
Lassen Sie Active (Aktiv) eingeschaltet. Solange ein Webhook pausiert ist, werden Ereignisse übersprungen und nicht in die Warteschlange gestellt.
Ereignisse
Transaktion: erstellt, bezahlt, abgelaufen, erstattet, storniert und Status geändert.
Sendung: erstellt, versendet, zugestellt und Etikett erstellt.
Bestellung: storniert. Zahlung: Auszahlung verarbeitet. Zustellung: bestätigt.
Rücksendeereignisse: beantragt, Informationen erforderlich, genehmigt, abgelehnt, Etikett ausgestellt, unterwegs, empfangen, geprüft, abgeschlossen, erstattet, storniert und weitere.
Fulfilment (QrX WMS):
picklist/created,picklist/completed,fulfilment/picked,fulfilment/packedundfulfilment/exception. Siehe "Packstation und Picklisten".Bestand (QrX WMS Lagerbestand):
stock/adjusted(der Bestand eines Artikels hat sich in einem Lager geändert) undstock/low(ein Artikel ist auf seinen Warnbestand gesunken). Sie gehen an jeden aktiven Webhook, der sie angehakt hat, auch an einen Webhook für einen Kanal. Siehe "Bestands- und Lager-Webhooks".
Sicherheit
Jede Zustellung ist signiert. Prüfen Sie den Header X-QrX-Signature mit dem Signaturgeheimnis Ihres Webhooks; X-QrX-Event und X-QrX-Delivery-Id kennzeichnen das Ereignis und die Zustellung. Mit Rotate (Rotieren) ändern Sie das Geheimnis: Das gilt sofort für alle folgenden Zustellungen, aktualisieren Sie also zuerst Ihren Endpunkt.
Fehler und Tests
Failure Notifications (Fehlerbenachrichtigungen): Wählen Sie Teammitglieder aus, die per E-Mail benachrichtigt werden. Nach 6 Stunden ununterbrochener Fehler wird eine Warnung gesendet, und nach 24 Stunden wird der Webhook automatisch deaktiviert. Beheben Sie das Problem an Ihrem Endpunkt und schalten Sie den Webhook im Editor wieder ein.
Send Test (Test senden) sendet ein Beispielereignis, auch wenn der Webhook deaktiviert ist.
Delivery Logs (Zustellprotokolle): Suchen Sie nach Transaktions-ID, Bestell-ID oder Ereignis. Status: Queued, Delivering, Delivered, Retrying, Failed und Cancelled. Öffnen Sie eine Zustellung, um Anfrage und Antwort zu sehen, sie mit Redeliver (Erneut zustellen) erneut zu senden oder sie abzubrechen.
Der Editor zeigt die Anzahl zugestellter und fehlgeschlagener Zustellungen der letzten 24 Stunden. Im Gefahrenbereich können Sie den Verlauf leeren oder den Webhook löschen.
Apps verbinden (OAuth)
Manche Apps, etwa die QrX Shopify App, verbinden sich über einen Zustimmungsbildschirm ("Connect QrX"). Sie wählen einen Kanal und klicken auf Allow. Die App kann dann Transaktionen mit Zahlung bei Zustellung und Versandetiketten erstellen und den Zahlungs- und Sendungsstatus lesen, ausschließlich für diesen Kanal. Sie kann weder Abrechnung, Benutzer noch andere Kanäle ändern.
Wann Sie unser Support-Team kontaktieren sollten
Kontaktieren Sie QrX, wenn Zustellungen fehlschlagen, obwohl Ihr Endpunkt 2xx zurückgibt, wenn Signaturen mit dem aktuellen Geheimnis nicht verifiziert werden können oder wenn Sie ein Ereignis benötigen, das nicht in der Liste steht. Geben Sie den Namen des Webhooks und eine Zustell-ID an.