Démarrage rapide pour les développeurs : API publique QrX et webhooks

L'API publique QrX permet aux marchands et aux développeurs de créer et de gérer des transactions Payment on Delivery, des étiquettes d'expédition, des produits, des retours et des webhooks. Il s'agit d'une API REST en JSON, avec une authentification Bearer et des webhooks signés. La référence complète, générée en direct à partir de l'API, est disponible sur qrx.eu/api.

Les bases

URL de base : https://api.qr-x.net
Format : requêtes et réponses en JSON. Les erreurs utilisent application/problem+json avec un code lisible par une machine et un message lisible.
Spécification : OpenAPI, avec des exemples de code en cURL, Node.js, C#, PHP et Python, une console « try it » et une collection Postman prête à l'emploi.
Accès : vous avez besoin d'un compte marchand QrX approuvé. Inscrivez-vous sur portal.qr-x.app ou demandez un accès via qrx.eu/api.

Étape 1 : obtenir une clé API et un jeton d'accès

Dans PortalX, ouvrez Settings, Merchant channels, et créez une clé API pour le canal de vente que vous souhaitez connecter. Chaque canal possède sa propre clé.
Échangez la clé contre un jeton d'accès : POST /api/v1/auth/token avec l'en-tête QrX-MerchantChannel-API-Key: YOUR_KEY. La réponse contient accessToken et expiresIn (3600 secondes).
Envoyez Authorization: Bearer <accessToken> à chaque autre appel. Demandez un nouveau jeton lorsqu'il expire.

Conservez la clé API sur votre serveur. Ne la placez jamais dans un navigateur, une application mobile ou un dépôt public.

Étape 2 : créer une transaction

POST /api/v1/transactions crée une transaction Payment on Delivery. Le corps contient le montant, la devise, la langue (locale), orderDetails (identifiant de commande, nom du client, email, téléphone, adresse et lignes de commande) et, en option, un bloc parcel pour choisir un mode d'expédition et un expéditeur et créer l'étiquette du transporteur dans le même appel. Utilisez les endpoints de référence (/api/v1/reference/carriers, countries, locales, shipping-methods, senders) pour obtenir des valeurs valides.

La réponse renvoie le transactionId, la valeur du QR code (un lien sur go.qr-x.app) et son image, ainsi que, si vous avez demandé une étiquette, les étiquettes d'expédition avec le numéro de suivi. Pour UPS Payment on Delivery, le jeu d'étiquettes inclut l'étiquette de paiement QrX.

Important : HTTP 201 signifie que QrX a accepté la transaction. Ce n'est pas une preuve de paiement. La session de paiement auprès du PSP peut être créée en arrière-plan, et le client paie plus tard, à la porte.

Étape 3 : suivre le résultat

GET /api/v1/transactions/{id}/status indique si la transaction est payée ou ouverte.
POST /api/v1/transactions/{id}/ship enregistre les informations de suivi provenant de votre propre système.
POST /api/v1/transactions/{id}/cancel annule une transaction ouverte éligible, avec un motif. Une transaction annulée ne peut plus être payée, étiquetée ni traitée.

Étape 4 : s'abonner aux webhooks

Les webhooks sont le moyen fiable de garder votre système synchronisé, car le traitement du paiement peut aboutir ou échouer après le retour de votre requête.

Créez un webhook avec POST /api/v1/webhooks : un nom, votre targetUrl HTTPS, les eventTypes souhaités (par exemple transaction/created et transaction/paid) et une version d'API.
Obtenez la liste actuelle des types d'événements et des versions d'API avec GET /api/v1/webhooks/event-types.
transaction/edited est envoyé quand les produits d'une commande impayée avec paiement à la porte changent (une ligne supprimée, une nouvelle quantité ou une ligne ajoutée), même quand le montant reste le même. Il contient eventId (utilisez-le pour dédupliquer), transactionId, orderId, shopOrderId, editId, oldAmount, newAmount, currency, paymentLinkChanged et les removedLines, changedLines et addedLines avec le SKU, le nom, l'ancienne et la nouvelle quantité et les totaux.
Chaque envoi comporte les en-têtes X-QrX-Event, X-QrX-Delivery-Id et X-QrX-Signature. La signature a la forme sha256=<hex> : un HMAC-SHA256 du corps brut calculé avec le secret de signature de votre webhook. Vérifiez-la avant de faire confiance à l'événement.
Répondez rapidement avec un statut 2xx et traitez l'événement ensuite. Gérez les doublons en toute sécurité, car des nouvelles tentatives et des renvois peuvent se produire.
Utilisez les endpoints pour envoyer un webhook de test, lister les envois, renvoyer ou annuler un envoi, réactiver un webhook désactivé et renouveler le secret de signature.

Stock en entrepôt

Avec le stock en entrepôt de QrX, vous lisez les niveaux de stock, les articles de stock et les emplacements avec GET /api/v1/stock/levels, /items et /locations, et vous enregistrez une correction avec POST /api/v1/stock/adjust. Les événements webhook stock/adjusted et stock/low vous préviennent lorsque le stock change ou devient faible. Voir "API de stock et d'entrepôt" et "Webhooks de stock et d'entrepôt".

Mode test

Définissez testMode: true lors de la création d'une transaction pour tester le flux complet. Les transactions de test utilisent une configuration sandbox ou de test lorsqu'elle est disponible, ne créent jamais de paiement ni de versement réel et ne doivent pas être traitées comme de vraies commandes. Les étiquettes des comptes de test sont créées dans la sandbox du transporteur.

Idempotence

Les commandes sur les retours (comme approuver, refuser, enregistrer une résolution ou publier un message) exigent un en-tête Idempotency-Key de 200 caractères maximum. Réutilisez la même clé lorsque vous relancez la même commande pour recevoir son résultat enregistré ; utilisez une nouvelle clé pour une nouvelle commande. Pour les transactions, utilisez votre propre identifiant de commande et les webhooks afin d'éviter de créer deux fois la même commande. POST /api/v1/stock/adjust demande aussi un en-tête Idempotency-Key.

Limites de débit

Les limites s'appliquent par clé API marchand ou par canal, par exemple 60 demandes de jeton par minute et 300 commandes de transaction par minute. Une réponse 429 inclut Retry-After et RateLimit-Reason. Attendez au moins Retry-After secondes avant de réessayer, et réutilisez votre jeton d'accès.

Vous développez pour d'autres marchands ?

Si vous développez une application, un WMS ou une plateforme utilisée par de nombreux marchands, utilisez QrX Connect afin que les marchands puissent relier leur canal QrX sans coller de clé API. Consultez « QrX Connect : connecter votre plateforme avec OAuth ».

Quand contacter notre équipe support

Contactez le support QrX à [email protected] pour un accès à l'API, des incidents en production, des identifiants divulgués ou des problèmes de signature que vous ne parvenez pas à expliquer. Indiquez l'environnement, le canal, l'identifiant de transaction, l'identifiant d'envoi du webhook et une requête nettoyée, jamais la clé, le jeton ou le secret. Consultez aussi « Dépannage API et webhooks ».