Réessayez avec le request_id initial et les paramètres inchangés. Ne créez pas une autre clé simplement parce que la connexion a expiré. Sur NotPanel, la nouvelle tentative renvoie la commande d’origine avec replayed: true, ou la crée si la première tentative n’est jamais arrivée.
Votre client a effectué un achat. Si la réponse disparaît après l’envoi au panel, l’étape suivante doit retrouver cet achat sans transformer l’incertitude en nouvel achat.
Un timeout laisse trois possibilités
- La requête n’est jamais arrivée : aucune commande n’a été acceptée.
- La commande a été acceptée, mais sa réponse s’est perdue.
- La requête est arrivée pendant la coupure ; une nouvelle tentative avec le même request_id indique lequel des deux cas précédents s’est produit.
Le timeout ne permet pas de distinguer ces cas. HTTP ne rend pas, à lui seul, la répétition d’un POST d’achat sûre : cette protection dépend du contrat de l’API. Voir RFC 9110, §9.2.2.
Comment NotPanel reconnaît une nouvelle tentative
request_id est facultatif, ne peut pas être vide et accepte jusqu’à 128 caractères. idempotency_key est son alias ; request_id prévaut si les deux sont présents. Conservez le même compte, la même clé et tous les paramètres. Une commande acceptée renvoie son ID initial ; réutiliser la clé avec des paramètres différents est refusé.
Sans ces deux champs, NotPanel protège les add identiques du même compte pendant 60 secondes : une répétition dans ce délai renvoie la première commande au lieu d’en créer une autre. Ne comptez pas sur cette courte fenêtre pour une tentative tardive.
Deux achats volontairement identiques sont également regroupés pendant cette fenêtre. Attribuez un request_id distinct à chaque nouvel achat pour les séparer immédiatement. Ne changez jamais la clé pour contourner un résultat incertain.
Paramètres et réponses de création de commande
Conservez le request_id initial après un délai dépassé.
Réessayez avec la même clé et les détails de commande inchangés.
Enregistrez l’ID de la commande d’origine renvoyé par la nouvelle tentative.
Identifiez l’achat avant de l’envoyer
Pour la ligne d’achat 8427, enregistrez request_id et tous les paramètres avant le premier envoi. Ce schéma utilise des valeurs à remplacer et des sauts de ligne ; encodez normalement le formulaire réel. N’envoyez des valeurs réelles que pour une commande payante souhaitée.
POST https://notpanel.com/api/v3
Content-Type: application/x-www-form-urlencoded
key=YOUR_API_KEY
&action=add
&service=YOUR_SERVICE_ID
&link=YOUR_TARGET_URL
&quantity=YOUR_VALID_QUANTITY
&request_id=checkout-8427-line-1Après expiration, renvoyez checkout-8427-line-1 avec les mêmes service, cible, quantité et champs facultatifs, même après un redémarrage. Enregistrez l’ID reçu et utilisez-le dans status. request_id identifie la création ; il ne remplace pas l’ID de commande pour consulter son état. Pour retrouver une commande par request_id, utilisez order_details.
Lisez la réponse complète
- Timeout ou réponse incertaine
- Gardez clé et paramètres. Limitez les tentatives, espacez-les et respectez Retry-After. Conservez un dossier non résolu si la limite de tentatives est atteinte.
- INTERNAL_ERROR, API_DISABLED ou ORDER_PLACEMENT_PAUSED (retryable: true)
- Attendez, en respectant Retry-After s’il est présent, puis envoyez le même add avec le même request_id. Vous obtenez la commande d’origine ou une seule nouvelle commande. Ne créez pas de remplacement sous une autre clé.
- REQUEST_ID_CONFLICT
- Comparez les paramètres enregistrés. Rétablissez les paramètres initiaux pour retrouver la commande ; une nouvelle clé correspond à un achat volontairement distinct.
- Validation, authentification ou limitation
- Lisez error_code et retryable. Corrigez les champs ou les identifiants et respectez les délais. Réessayer toute erreur automatiquement crée des boucles inutiles.
Testez la récupération avant les achats des clients
Commencez par une API simulée dans votre environnement de test. Aucun achat réel ni clé de test spéciale NotPanel n’est nécessaire.
- Simulez une commande acceptée dont la réponse se perd ; vérifiez que la clé et les paramètres restent identiques.
- Redémarrez le client et retrouvez l’identité enregistrée.
- Renvoyez d’abord un 500 ou 503 réessayable, puis une répétition avec replayed: true ; vérifiez qu’un seul ID de commande est enregistré.
- Simulez un conflit ou une erreur non réessayable ; vérifiez l’arrêt des tentatives automatiques.
- Créez deux nouveaux achats identiques avec des clés distinctes. Pour un test réel ultérieur, choisissez une commande souhaitée et vérifiez commande et mouvements du portefeuille.
Questions fréquentes
Un timeout signifie-t-il un double débit ?
Non. Il signifie que votre application n’a pas reçu de réponse exploitable. Vérifiez la commande retrouvée et les mouvements du portefeuille avant de conclure à un doublon.
request_id est-il obligatoire ?
Non. request_id et idempotency_key sont facultatifs. Sans eux, les add identiques du même compte sont protégés pendant 60 secondes. Une clé explicite identifie chaque achat.
Dois-je créer une clé pour chaque tentative ?
Non. Enregistrez une clé avant le premier envoi et réutilisez-la sans modifier la commande. Un nouvel achat reçoit une nouvelle clé.
Puis-je retrouver une commande avec request_id ?
Oui, avec order_details : envoyez action=order_details avec le même request_id pour obtenir la commande et son numéro sans rejouer l’add. Si aucune commande n’a été créée, la réponse est ORDER_NOT_FOUND. L’action status demande toujours le numéro de commande.
À lire ensuite : le guide d’intégration · webhooks et suivi d’état · la référence des erreurs.
