Dépannage de l'API et des webhooks

La plupart des problèmes d'API et de webhooks QrX relèvent de l'authentification, des identifiants, des limites de débit ou de la façon dont votre récepteur traite les webhooks. Vérifiez d'abord les points ci-dessous. La référence complète de l'API se trouve sur qrx.eu/api.

Erreurs d'authentification (401 ou 403)

Les endpoints protégés nécessitent Authorization: Bearer <token>, et non la clé API. Utilisez la clé API (en-tête QrX-MerchantChannel-API-Key) uniquement pour appeler POST /api/v1/auth/token.
Les jetons d'accès sont valables une heure. Demandez un nouveau jeton lorsqu'il expire.
Chaque clé API appartient à un seul canal marchand. Un jeton ne peut ni lire ni modifier les données d'un autre canal.
Vérifiez que la clé n'a pas été supprimée ou remplacée dans PortalX sous Settings, Merchant channels.
403 avec le code STOCK_SCOPE_MISSING (ou le code correspondant pour les retours ou les arrivages) : la clé API est restreinte et la partie que vous appelez n'est pas cochée. Cochez-la dans le bloc Accès API du canal de vente et attendez 30 secondes. Voir "Restreindre une clé API (Accès API)".
403 avec le code ACCESS_DENIED sur un endpoint de stock : le stock en entrepôt de QrX n'est pas activé pour le compte.

Trop de requêtes (429)

Les limites de débit s'appliquent par clé API marchand ou par canal. Par exemple, l'endpoint de jeton autorise 60 requêtes par minute et la création de transactions autorise 300 requêtes par minute et par canal. Une réponse 429 contient les en-têtes Retry-After et RateLimit-Reason ainsi que le code RATE_LIMIT_EXCEEDED. Attendez au moins le nombre de secondes indiqué dans Retry-After avant de réessayer, et réutilisez votre jeton d'accès au lieu d'en demander un nouveau à chaque appel.

Transaction créée mais pas encore payée

Un HTTP 201 lors de la création 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 paiement a lieu plus tard, à la porte. Suivez la transaction avec les webhooks ou l'endpoint de statut, et n'expédiez ou ne remettez les produits qu'une fois la transaction payée. Si la création d'une étiquette transporteur est demandée et échoue, la requête de création elle-même renvoie une erreur.

Autres problèmes fréquents

Montant, devise, pays, langue ou mode d'expédition invalide. Utilisez les endpoints de référence pour obtenir des valeurs valides.
Email ou téléphone du client manquant, alors qu'ils sont nécessaires pour les liens de paiement, l'envoi du PIN et le support.
Confusion entre test et production. Les transactions créées avec testMode: true ne créent jamais de paiements ni de versements réels et ne doivent pas être traitées comme de vraies commandes.
Réessai d'une commande de retour avec une nouvelle Idempotency-Key. Réutilisez la même clé lorsque vous réessayez la même commande ; utilisez une nouvelle clé uniquement pour une nouvelle commande.
Corrections de stock : POST /api/v1/stock/adjust sans en-tête Idempotency-Key répond 400 IDEMPOTENCY_KEY_REQUIRED ; la même clé avec un autre corps répond 409 DUPLICATE_IDEMPOTENCY_KEY ; 409 STOCK_CONFLICT signifie pas assez de stock, du stock affecté ou un SKU qui correspond à plusieurs articles. Voir "API de stock et d'entrepôt".

Vérifications des webhooks

Accessible et rapide : votre endpoint doit être accessible publiquement en HTTPS et renvoyer rapidement un statut 2xx. Effectuez les traitements lents après avoir répondu.
Signature : vérifiez l'en-tête X-QrX-Signature. Il a la forme sha256=<hex>, un HMAC-SHA256 du corps brut de la requête calculé avec votre secret de signature de webhook. Calculez-le sur les octets exacts que vous avez reçus, avant d'analyser le JSON.
Secret renouvelé : après le renouvellement du secret de signature, mettez à jour votre récepteur, sinon les vérifications de signature échoueront.
Doublons : les nouvelles tentatives et les renvois peuvent envoyer le même événement plusieurs fois. Utilisez l'en-tête X-QrX-Delivery-Id et les données de l'événement pour ne traiter chaque événement qu'une seule fois.
Types d'événements : l'en-tête X-QrX-Event vous indique l'événement. Abonnez-vous uniquement aux événements que vous traitez.
Événements de stock : repérez les doublons avec eventId et, pour stock/adjusted, ignorez un événement dont la sequence est inférieure à la dernière que vous avez conservée pour cet article et cet entrepôt. Voir "Webhooks de stock et d'entrepôt".

État des webhooks et journaux de livraison

Chaque abonnement webhook dans PortalX affiche un état de santé. Si un endpoint échoue en continu, QrX envoie des emails d'avertissement aux destinataires configurés et désactive automatiquement l'abonnement après environ 24 heures d'échec ; il peut être réactivé une fois l'endpoint corrigé. Utilisez le journal de livraison (dans PortalX ou via l'API) pour examiner chaque tentative, y compris la requête, la réponse et les nouvelles tentatives, et pour renvoyer une livraison échouée. Vous pouvez aussi envoyer un webhook de test pour vérifier votre récepteur.

Ce qu'il faut envoyer au support

Envoyez l'environnement (test ou production), le canal marchand, la référence de commande, l'identifiant de transaction QrX, l'horodatage, l'endpoint, le statut de la réponse, l'identifiant de livraison du webhook et un corps de requête ou de réponse nettoyé. Retirez les clés API, jetons d'accès, signatures, secrets, mots de passe et données personnelles non nécessaires.

Quand contacter notre équipe support

Contactez directement le support QrX pour les problèmes d'API impliquant des identifiants divulgués, la sécurité, des incidents en production, des incohérences de paiement, des échecs de signature de webhook que vous ne pouvez pas expliquer, ou des erreurs d'intégration répétées. Ces cas sont toujours traités par une personne. Consultez status.qr-x.app pour connaître l'état actuel de la plateforme.