Webhooks et clés API dans PortalX
Les webhooks envoient des notifications en temps réel à votre propre système lorsqu'un événement se produit dans QrX, comme un paiement ou une livraison. Les clés API permettent à votre système de créer des transactions via l'API QrX. La documentation de l'API se trouve sur qrx.eu/api.
Clés API
Chaque canal de vente a sa propre clé API : Settings > Business > Merchant Channels, ouvrez le canal, onglet Settings, API Key (permission Manage Channels). La clé est stockée de manière sécurisée et affichée en entier une seule fois, lorsque vous cliquez sur Regenerate API Key (régénérer la clé API). Copiez-la immédiatement. La régénération interrompt toutes les intégrations qui utilisent encore l'ancienne clé.
Sous la clé API se trouve le bloc Accès API. Une clé commence avec Accès complet. Activez Restreindre cette clé pour limiter la clé aux parties de l'API que vous cochez, par exemple seulement la lecture du stock. Voir "Restreindre une clé API (Accès API)".
Créer un webhook
Allez dans Settings > Advanced > Webhooks.
Saisissez un nom et l'URL de votre endpoint (https).
Choisissez la version de l'API et éventuellement un canal (ou All Channels).
Cliquez sur les événements que vous souhaitez recevoir. Utilisez Customize payload (personnaliser le payload) pour choisir les champs envoyés pour un événement.
Laissez Active activé. Tant qu'un webhook est en pause, les événements sont ignorés, et non mis en file d'attente.
Événements
Transaction : créée, payée, expirée, remboursée, annulée et changement de statut.
Expédition : créée, expédiée, livrée et étiquette créée.
Commande : annulée. Paiement : versement traité. Livraison : confirmée.
Événements de retour : demandé, informations requises, approuvé, refusé, étiquette émise, en transit, reçu, inspecté, résolu, remboursé, annulé et plus encore.
Fulfilment (QrX WMS) :
picklist/created,picklist/completed,fulfilment/picked,fulfilment/packedetfulfilment/exception. Voir "Poste d'emballage et listes de prélèvement".Stock (stock en entrepôt de QrX WMS) :
stock/adjusted(le stock d'un article a changé dans un entrepôt) etstock/low(un article est descendu à son seuil d'alerte de stock faible). Ils vont à chaque webhook actif qui les a cochés, y compris un webhook pour un seul canal. Voir "Webhooks de stock et d'entrepôt".
Sécurité
Chaque envoi est signé. Vérifiez l'en-tête X-QrX-Signature avec le secret de signature de votre webhook ; X-QrX-Event et X-QrX-Delivery-Id identifient l'événement et l'envoi. Utilisez Rotate (renouveler) pour changer le secret : le changement s'applique immédiatement à tous les envois suivants, alors mettez d'abord votre endpoint à jour.
Échecs et tests
Failure Notifications (notifications d'échec) : choisissez les membres de l'équipe à prévenir par e-mail. Un avertissement est envoyé après 6 heures d'échecs continus, et le webhook est désactivé automatiquement après 24 heures. Corrigez votre endpoint et réactivez le webhook dans l'éditeur.
Send Test (envoyer un test) envoie un événement d'exemple, même lorsque le webhook est désactivé.
Delivery Logs (journaux d'envoi) : recherchez par identifiant de transaction, identifiant de commande ou événement. Statuts : Queued, Delivering, Delivered, Retrying, Failed et Cancelled. Ouvrez un envoi pour voir la requête et la réponse, le renvoyer avec Redeliver (renvoyer) ou l'annuler.
L'éditeur affiche le nombre d'envois réussis et échoués des dernières 24 heures. Dans la zone de danger, vous pouvez purger l'historique ou supprimer le webhook.
Connecter des applications (OAuth)
Certaines applications, comme l'application QrX pour Shopify, se connectent via un écran de consentement (« Connect QrX »). Vous choisissez un canal et cliquez sur Allow (autoriser). L'application peut alors créer des transactions de paiement à la livraison et des étiquettes d'expédition, et lire le statut des paiements et des expéditions pour ce canal uniquement. Elle ne peut pas modifier la facturation, les utilisateurs ou les autres canaux.
Quand contacter notre équipe support
Contactez QrX lorsque des envois échouent alors que votre endpoint renvoie un code 2xx, lorsque les signatures ne se vérifient pas avec le secret actuel, ou lorsque vous avez besoin d'un événement qui ne figure pas dans la liste. Indiquez le nom du webhook et un identifiant d'envoi.