Traitement du statut « en cours » lors de la vérification d'une commande via l'API

Ce que signifie processing dans la réponse de l'API

Le statut processing, in_progress ou tout autre état équivalent signifie que le fournisseur a pris la commande en charge, mais n'a pas encore enregistré le résultat final. Pour des services de promotion, cela peut correspondre à la vérification d'un lien, à l'attente dans une file, au lancement d'une tâche ou à la livraison progressive du volume commandé.

Processing ne confirme pas une exécution réussie et ne signifie pas non plus une erreur. Après ce statut, la commande peut passer à completed, partial, canceled ou failed. Tant que le fournisseur renvoie un statut intermédiaire, ne créez pas de nouvelle demande pour le même lien et le même volume.

Un HTTP 200 avec le statut processing signifie une réponse API réussie, et non l'achèvement réussi de la commande. Ces événements doivent être stockés et traités séparément.

Quelles données sont nécessaires pour vérifier une commande

Pour le polling, il faut l'ID externe de la commande renvoyé par le fournisseur lors de la création. Conservez-le avec l'ID interne, le volume initial, les paramètres du service, le lien, l'heure de création et la réponse API d'origine. Rechercher une commande par le nom de la chaîne, le lien ou le volume n'est pas fiable : ces valeurs peuvent coïncider pour plusieurs demandes.

Si un délai d'attente survient après la création, ne renvoyez pas la demande automatiquement. Le fournisseur a pu accepter la requête, et la réponse a pu se perdre en route. Utilisez d'abord la méthode de recherche de commande si elle existe dans la documentation, ou transmettez le cas pour vérification.

L'inconvénient de ne stocker que le statut actuel est qu'en cas de litige, il est impossible de reconstituer le moment où la commande est passée à processing, s'il y a eu une progression et quelles réponses étaient arrivées auparavant.

Exemple de requête de statut via curl

Récupérez l'adresse exacte, la méthode d'autorisation et les noms des champs dans la documentation du fournisseur. Ci-dessous, un modèle : les valeurs entre chevrons doivent être remplacées par les données de l'API concernée.

Requête GET pour une seule commande

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Exemple de réponse :

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

Les champs completed_quantity et remains ne sont donnés qu'à titre d'exemple de structure. Le fournisseur peut utiliser progress, start_count, balance ou d'autres noms. L'inconvénient de l'approche GET est que certaines API n'acceptent la vérification du statut que via POST.

Exemple de requête POST et de vérification par lot

Requête POST du statut d'une seule commande

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Ne transmettez pas la clé API dans la chaîne URL. Les adresses des requêtes se retrouvent dans les journaux des proxys, les systèmes d'analyse, l'historique du navigateur et les logs techniques. L'inconvénient du POST est qu'il est plus difficile à vérifier manuellement via la barre d'adresse, mais ce n'est pas une raison pour déplacer le secret dans l'URL.

Requête par lot des commandes actives

Si l'API prend en charge la vérification par lot, envoyez plusieurs ID dans une seule requête :

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Associez la réponse à la commande interne par l'ID externe, et non par la position de l'élément dans le tableau. Inconvénient de la vérification par lot : le fournisseur peut ne pas renvoyer toutes les commandes, limiter la taille de la liste ou signaler une erreur pour un seul ID.

Comment définir le polling pour processing

Après la première réponse processing, placez la vérification suivante dans la file. Choisissez l'intervalle selon la documentation de l'API, les limites de fréquence et la nature du service. Pour les tâches dont le statut change rapidement, une vérification plus fréquente au début est acceptable. Pour une promotion progressive, des requêtes courtes constantes n'apportent généralement pas de nouvelle information.

Un schéma pratique consiste à augmenter la pause après des réponses processing identiques. La première vérification a lieu après un délai initial, puis l'intervalle augmente jusqu'à un maximum défini. Si l'API renvoie une progression ou une nouvelle heure de mise à jour, le décompte peut repartir de ce changement.

• Après la création d'une commande, ne vérifiez pas le statut immédiatement plusieurs fois de suite : le service peut avoir besoin de temps pour la mise en file.
• En cas de processing répété, augmentez l'intervalle entre les requêtes au lieu de maintenir une fréquence constante.
• Ajoutez une légère variation aléatoire à l'heure de lancement des tâches pour que les commandes n'interrogent pas l'API simultanément.
• Si le fournisseur transmet Retry-After ou une recommandation équivalente, utilisez-la en priorité.
• Pour les commandes avec webhooks, conservez un polling de contrôle : une notification peut ne pas arriver.

L'inconvénient d'un polling rare est que l'interface peut afficher un statut obsolète après l'achèvement réel. L'inconvénient d'un polling trop fréquent est le risque de heurter les limites de l'API, de recevoir un 429 et de créer une charge inutile.

Quels horodatages conserver pour contrôler processing

Pour distinguer une exécution normale d'un blocage, un seul statut actuel ne suffit pas. Pour chaque commande active, conservez l'heure de création, la première réception de processing, la dernière réponse API réussie, le dernier changement de statut externe et le dernier changement de progression.

Il est également utile de conserver le volume initial, le volume exécuté confirmé, le reste et le statut d'origine du fournisseur. Si l'API ne fournit pas de progression, ce n'est pas une raison pour considérer la commande comme bloquée : fiez-vous à l'heure de la dernière réponse et à la période de traitement attendue, si elle est indiquée dans les conditions du service.

Le temps d'attente maximal ne peut pas être défini par un seul chiffre pour tous les services. Utilisez le délai que le fournisseur indique pour le service concerné, avec une marge interne pour la file et la mise à jour des données. Si le délai n'est pas indiqué, définissez une règle distincte pour chaque catégorie de services et révisez-la à partir de l'historique du traitement réel.

Que faire si processing ne change pas

Un processing prolongé ne prouve pas une erreur. Vérifiez d'abord si des réponses API réussies sont arrivées, si completed_quantity ou remains ont changé, s'il y a eu des webhooks et si les règles du service ont changé. L'absence de croissance visible peut être liée à un retard des statistiques de la plateforme ou au fait que le fournisseur ne met à jour la progression qu'à la fin.

Lorsque le délai d'attente interne est dépassé, n'annulez pas la commande automatiquement. Effectuez une vérification de statut hors tour, demandez les données via une méthode dédiée si elle est prévue, et consultez l'historique des notifications. Si le fournisseur confirme encore processing, faites passer la commande dans un état interne « vérification requise », mais conservez le statut externe sans le substituer.

• Enregistrez l'heure de la dernière réponse confirmée et l'intégralité de la réponse API.
• Vérifiez si la progression a changé depuis l'interrogation précédente.
• Réduisez la fréquence des requêtes automatiques après avoir atteint le seuil interne.
Transmettez au support l'ID externe, le lien, les paramètres du service, l'historique des statuts et les erreurs techniques.
• Ne relancez pas le reste avant la réponse du fournisseur ou un statut final explicite.

L'inconvénient de la vérification manuelle est que la commande mobilise le support. Mais une annulation automatique ou un doublon est plus dangereux : l'exécution peut se poursuivre chez le fournisseur.

Comment distinguer une défaillance de requête d'un statut de commande

Une erreur réseau, un délai d'attente, un HTTP 429 et une réponse 5xx n'indiquent pas l'état de la commande elle-même. Ils signifient seulement qu'un nouveau statut fiable n'a pas pu être obtenu. Dans ce cas, conservez le dernier statut confirmé, enregistrez l'erreur technique et planifiez une nouvelle vérification.

En cas de 429, tenez compte de Retry-After si l'en-tête est transmis. En cas d'erreurs réseau temporaires et de 5xx, augmentez la pause entre les tentatives. En cas d'erreur d'autorisation, de signature ou de droits d'accès, ne lancez pas de retries fréquents : il faut vérifier la clé, la durée de validité du token, les restrictions IP et les paramètres d'accès.

Si l'API renvoie un HTTP 200, mais que le JSON ne se parse pas ou que la réponse ne contient pas order_id et status, conservez le corps de la réponse en entier et marquez la vérification comme incorrecte. Ne remplacez pas l'absence de statut par completed, canceled ou processing.

Quand arrêter les requêtes automatiques répétées

Le polling ne doit pas être infini. Limitez le nombre de nouvelles tentatives techniques pour les erreurs temporaires et contrôlez séparément la durée totale pendant laquelle la commande reste en processing. Une fois la limite de retries épuisée, faites passer la tâche de vérification dans la file d'analyse, au lieu de créer de nouvelles requêtes chaque minute sans résultat.

Répéter une requête de statut est généralement sans danger si la méthode ne fait que lire des données. Les méthodes de création, d'annulation, de rechargement, de redémarrage et de remboursement ne doivent pas être répétées mécaniquement après un délai d'attente. Sans clé d'idempotence ou confirmation explicite du fournisseur, une telle répétition peut modifier la commande deux fois.

L'inconvénient de limiter les retries est qu'une partie des mises à jour devient une tâche manuelle. Des retries infinis sont pires : ils masquent la défaillance, consomment les limites et compliquent l'analyse des journaux.

Comment accepter le statut final après processing

Empêchez toute transition inverse de completed vers processing due à une réponse de polling tardive ou à un webhook ancien. À chaque mise à jour, comparez l'heure de l'événement du fournisseur, le numéro de version s'il existe, et l'état interne actuel.

• new et pending peuvent passer à processing, canceled ou failed.
• processing peut passer à completed, partial, canceled ou failed.
• partial ne doit pas être automatiquement considéré comme completed.
• completed, canceled et failed sont généralement considérés comme finaux et bloquent le retour automatique en arrière.
• Un statut inconnu ou une transition non autorisée nécessitent une vérification distincte.

Une table de transitions rigide a aussi son inconvénient : le fournisseur peut ajouter un nouvel état valide. C'est pourquoi conservez le statut d'origine et ne l'écrasez pas avec votre classification interne.

Comment traiter partial et le reste de la commande

Partial signifie que seule une partie du volume initial est confirmée. La réponse API peut contenir la quantité réellement exécutée, le reste, la raison et les données de compensation. Conservez ces valeurs séparément : le volume initial de la commande ne doit pas être remplacé par la quantité exécutée.

Un exemple de réponse finale peut ressembler à ceci :

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

Déterminez d'abord ce que l'API confirme exactement : le remboursement est déjà effectué, le remboursement est seulement planifié, le reste est annulé ou une demande au support est nécessaire. Si aucun champ de remboursement n'est présent, ne considérez pas le reste comme automatiquement compensé.

Ne relancez pas la partie non exécutée sans décision distincte. Le fournisseur peut encore finaliser le calcul, les statistiques de la plateforme peuvent se mettre à jour avec du retard, et une nouvelle demande peut créer une promotion en doublon. L'inconvénient d'attendre la confirmation est que le reste ne sera pas clôturé immédiatement, mais cela évite une commande supplémentaire.

Les webhooks ne remplacent pas la vérification de contrôle

Un webhook permet de mettre à jour la fiche de commande immédiatement après l'événement, sans attendre le polling suivant. Dans le gestionnaire, retrouvez la commande par l'ID externe, vérifiez la signature ou le secret, enregistrez l'ID de l'événement et n'appliquez la transition qu'après avoir vérifié qu'elle est autorisée.

Une livraison répétée de webhook doit être sans danger : un même événement ne doit pas être considéré comme un nouveau changement. Les événements peuvent aussi arriver dans le désordre, donc ne faites pas repasser une commande finale en arrière uniquement sur la base d'un processing tardif.

Un polling de contrôle est nécessaire même avec des webhooks stables. L'inconvénient des webhooks est une configuration plus complexe : il faut un gestionnaire accessible, une protection contre les requêtes falsifiées, une déduplication et un journal des événements.

Que montrer au client pendant processing et en cas de blocage

Dans l'interface, il n'est pas nécessaire d'afficher tout le JSON technique. Pour processing, l'état « commande en cours » suffit. Si l'API a transmis une progression fiable, affichez le volume confirmé séparément du volume initial et ne le présentez pas comme le résultat définitif.

Pour une commande qui a dépassé le délai de contrôle interne, utilisez un état compréhensible comme « nous vérifions l'exécution ». N'annoncez pas d'annulation, de remboursement ou d'achèvement complet tant que cela n'est pas confirmé par la réponse du fournisseur.

Les notifications sont utiles lors de l'acceptation de la commande, de l'exécution finale, du partial, de l'annulation, d'une erreur et lorsqu'une vérification est nécessaire. Des messages après chaque polling créent du bruit et n'aident pas le client à comprendre l'état réel de la demande.

Quelles entrées sont nécessaires dans le journal de traitement

L'historique des réponses aide à analyser un processing bloqué, un webhook perdu, un litige sur une exécution partielle et un écart entre l'interface et l'API. Pour chaque appel, conservez l'ID externe, la source de la mise à jour, l'heure de la requête et de la réponse, le code HTTP, le statut d'origine, le statut normalisé, la progression, le reste et le texte de l'erreur technique.

N'écrivez pas les clés API, tokens, signatures et autres secrets dans les logs ordinaires. Limitez l'accès aux réponses brutes : elles peuvent contenir des données qui ne doivent pas apparaître dans l'interface du support.

Avant le lancement, testez les scénarios avec processing répété, absence de progression, délai d'attente, 429, erreur 5xx, JSON incorrect, webhook tardif, webhook en doublon, partial, canceled et statut inconnu. Le mode test est utile pour la structure de l'intégration, mais son inconvénient est qu'il peut ne pas reproduire les files et les délais réels de l'API de production.