Vérification du solde via l'API avant un lancement massif de commandes

Pourquoi interroger le solde avant de lancer une file

Un lancement massif de commandes sans vérification récente du solde entraîne des refus partiels : les premières demandes sont créées, puis les suivantes reçoivent une erreur de fonds insuffisants. Le plus difficile à gérer est une telle situation lors d'un envoi parallèle, avec des services différents et plusieurs processus travaillant sur un même compte.

Pour le lancement, ce n'est ni le volume total des recharges ni le solde comptable du compte personnel qui importent. Il faut le montant que le service autorise à débiter au moment de la création d'une nouvelle commande. L'argent des demandes actives peut déjà être en réserve, même si le débit définitif n'apparaît pas encore dans l'historique des opérations.

Comparez le budget de la file avec le champ du solde disponible, et non avec la somme totale du compte.

À quoi ressemble la réponse de la méthode de solde

Les noms des champs sont définis par la documentation de chaque plateforme, mais un contrat pratique de la méthode de solde renvoie généralement total, available, reserved, currency et updated_at. Voici un exemple de structure à utiliser comme repère lors de l'intégration. Ce n'est pas une réponse universelle pour chaque service, mais un exemple de schéma de données clair.

La requête peut ressembler à ceci :

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

Réponse :

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

Dans cet exemple, total correspond à tous les fonds du compte, available à l'argent disponible pour de nouvelles commandes, reserved à la somme des opérations créées précédemment. La vérification est cohérente : 125.80 moins 41.30 égale 84.50. Le champ currency définit l'unité de calcul, et updated_at aide à comprendre la fraîcheur des données.

Comment interpréter available et reserved

Le champ available sert à décider du lancement. Si la file coûte 80.00 et que available vaut 84.50, les fonds suffisent uniquement à condition que l'API n'ajoute pas de commission distincte ou ne recalcule pas le prix au moment de la création de la demande. Le champ reserved ne s'ajoute pas au solde disponible : cette somme est déjà engagée.

reserved peut inclure le coût des commandes aux statuts processing, pending ou review — l'ensemble exact dépend des règles de la plateforme. Parfois la réserve est libérée après une annulation, une exécution partielle ou une vérification manuelle. Il ne faut donc la recalculer soi-même à partir de la liste des commandes qu'à titre de vérification complémentaire.

• total convient pour la vérification avec l'historique des recharges et des débits ;
• available convient pour autoriser une nouvelle file au lancement ;
• reserved indique combien de fonds sont déjà bloqués pour des opérations actives ;
• currency ne doit pas être ignoré, même en travaillant avec un seul compte ;
• updated_at est utile pour le journal et le diagnostic d'une réponse obsolète.

Une réponse contenant uniquement le champ balance est plus simple à traiter, mais elle a un inconvénient : impossible de savoir si cet argent est immédiatement disponible ou si une partie de la somme est déjà retenue pour d'autres commandes.

Vérifiez le format des montants dans la documentation de l'API

Dans l'exemple, les montants sont transmis sous forme de chaînes : "84.50", et non le nombre 84.5. Ce format conserve la valeur exacte renvoyée par le service. Si l'API utilise des chaînes avec un point décimal, il ne faut pas les convertir immédiatement en nombres à virgule flottante ni effectuer des comparaisons via float.

Par exemple, votre calcul peut donner 84.499999 au lieu des 84.50 attendus. À la limite du budget, cela peut faire passer la file par erreur ou, au contraire, l'arrêter. Pour les opérations sur des valeurs décimales sous forme de chaînes, utilisez un type de données décimal qui prend en charge la précision à virgule fixe.

Un autre contrat courant est celui des unités minimales entières. La réponse peut alors contenir "available_minor": 8450 et "currency": "USD", et le prix de la commande "price_minor": 1250. Dans une telle API, 8450 signifie 84.50 si les règles de la devise prévoient deux décimales. Diviser la valeur par 100 n'est possible que lorsque la documentation le précise explicitement.

Ne mélangez pas les devises et les formats de prix

Avant de calculer la file, comparez la currency du solde avec la devise de la méthode de prix ou de la réponse lors de la création de la commande. Si le solde renvoie une devise et le catalogue des services une autre, il ne faut pas insérer les chiffres directement. Il faut soit un calcul fourni par la plateforme elle-même, soit une méthode de conversion distincte et confirmée.

Une conversion préalable de votre côté est pratique pour la planification, mais elle a un inconvénient : le service peut appliquer un autre taux, une commission ou une règle d'arrondi au moment du débit. Il est plus fiable d'envoyer la commande avec des paramètres pour lesquels l'API renvoie le coût final dans la devise du solde, ou d'obtenir le calcul du prix juste avant la création.

Si la méthode de prix répond "price": "12.345" alors que le solde stocke des valeurs à deux décimales, vérifiez la règle d'arrondi. N'arrondissez pas automatiquement à la baisse : le débit réel peut être supérieur. Pour autoriser la file, utilisez précisément la somme que l'API appelle coût final de la commande.

Calculez le budget de la file avant la première requête

Avant le lancement, rassemblez toutes les demandes et calculez leur coût en tenant compte du volume, du service choisi, de la région, des options supplémentaires et de la commission si elle est transmise séparément. Ne comparez pas available avec le prix de base de l'interface : dans l'API, le total peut dépendre des paramètres de la commande concernée.

Supposons que la file contienne trois commandes. L'API de calcul de prix a renvoyé pour elles 18.40, 27.15 et 31.60 dans la même devise que celle indiquée dans balance.currency. Le budget est de 77.15. Si balance.available vaut 84.50, il reste 7.35 après le lancement prévu. Si available vaut 76.90, il ne faut pas lancer toute la file.

1. Obtenez les prix selon les paramètres réels de chaque commande.
2. Additionnez les coûts finaux sans changer leur format ni leur devise.
3. Comparez le budget avec available issu d'une réponse de solde récente.
4. Si le solde est suffisant, fixez la somme comme réserve locale de lancement.
5. Après la création de chaque demande, diminuez la réserve locale du coût confirmé.

Une marge réduit le risque de refus en cas de débit supplémentaire, mais elle a un inconvénient : une partie des fonds disponibles restera inutilisée, alors que la file aurait pu passer entièrement.

Effectuez une seconde vérification juste avant l'envoi

Le solde obtenu lors de la préparation de la campagne perd rapidement son actualité. Entre le calcul et le lancement, un autre opérateur, une automatisation ou une commande active peuvent modifier available et reserved. Une nouvelle requête est nécessaire après la formation de la file et juste avant la première demande.

Le schéma de travail comporte deux étapes : d'abord obtenir les prix et évaluer le budget, puis interroger balance une nouvelle fois. Si la valeur available a diminué et est passée sous la somme calculée, la file n'est pas envoyée en entier. Entre la vérification finale et le lancement, il ne faut pas effectuer d'autres débits sur le même compte.

Une seule requête pour tout le lancement réduit la charge sur l'API, mais son inconvénient est que le solde disponible peut changer pendant le traitement d'une longue file.

Comment lancer la file en cas de fonds insuffisants

Si available est inférieur au budget, n'envoyez pas toutes les requêtes en espérant qu'une partie passera. Divisez la file en lots dont le coût tient dans la limite disponible. Dans l'exemple avec un solde de 76.90, on peut envoyer les deux premières commandes pour 45.55, puis s'arrêter : la troisième à 31.60 nécessite une nouvelle vérification.

Définissez explicitement l'ordre des demandes lors du traitement par lots. Vous pouvez envoyer d'abord les commandes prioritaires, ou former des lots de coût proche. Chaque option a un inconvénient : l'ordre par priorité reportera les positions moins importantes, tandis que le tri par prix peut perturber le plan de campagne initial.

• Formez un lot dont la somme ne dépasse pas l'available actuel.
• Créez les commandes du lot et conservez leurs identifiants.
• Attendez les réponses ou vérifiez les statuts des opérations après des délais d'attente.
• Marquez une pause si les limites de l'API ou les règles du service l'exigent.
• Interrogez à nouveau balance avant le lot suivant.

Après chaque lot, fiez-vous à la nouvelle réponse de l'API, et pas seulement à la déduction locale à partir du solde précédent. Le calcul local est utile pour le contrôle, mais il ne voit ni les remboursements, ni les débits externes, ni le recalcul des réserves.

Protégez le budget lors d'un envoi parallèle

En traitement séquentiel, il suffit de réduire la limite locale après la confirmation d'une commande. En modèle parallèle, deux workers peuvent voir simultanément available à 84.50 et planifier chacun une dépense de 60.00. Les deux décisions semblent acceptables séparément, mais ensemble elles dépassent le solde disponible.

Pour se protéger, il faut un compteur commun de réserve locale ou une file dont l'accès s'effectue de manière atomique. Avant l'envoi, le worker tente de réserver le montant de la commande dans ce compteur. Si la limite libre est insuffisante, la demande reste en attente d'une nouvelle vérification du solde.

• Une file séquentielle est plus simple à contrôler, mais se lance plus lentement.
• L'envoi parallèle réduit le temps de lancement, mais exige le verrouillage du budget commun.
• La réservation locale réduit les conflits, mais peut rester bloquée après une panne d'un worker.
• La réservation côté API est plus fiable, mais n'est pas disponible sur toutes les plateformes.

Si le processus s'est terminé avant de recevoir la réponse, la réserve locale ne doit être considérée ni comme dépensée ni comme libre. Vérifiez d'abord si la commande a été créée, via son identifiant externe ou par une méthode de recherche des opérations.

Utilisez la réserve de l'API si elle est prévue

Certaines API permettent de créer une réserve pour un ensemble d'opérations ou de passer une commande en deux étapes : calcul, blocage de la somme, confirmation. Dans un tel schéma, la fenêtre entre la vérification et le débit est plus courte, ce qui réduit la possibilité qu'un autre processus dépense les fonds du compte.

Si une telle méthode existe, conservez l'identifiant de la réserve, son montant, sa devise, sa durée de validité et son statut. Transmettez ensuite cet identifiant lors de la création des commandes si le contrat de l'API l'exige. Après la fin de la file, vérifiez la partie non utilisée et la levée effective du blocage.

La réserve de l'API ne résout pas tous les problèmes : elle peut avoir une courte durée de validité, ne pas couvrir les commissions ou être libérée après une erreur de confirmation. La réserve locale est plus simple à mettre en place, mais son inconvénient est qu'elle ne protège pas contre les dépenses créées en dehors de votre application.

Distinguez une erreur de solde d'un solde nul

Une réponse avec un code d'erreur, un délai d'attente ou une limitation du débit des requêtes ne signifie pas que available est égal à zéro. Ne substituez pas automatiquement la dernière valeur connue si un lancement important en dépend. S'il est impossible d'obtenir un solde récent, la file doit être mise en pause.

Traitez séparément le refus lors de la création d'une commande. Il peut être lié à un manque de fonds, mais aussi à un identifiant de service incorrect, à un volume non autorisé, à une restriction sur le canal ou à la répétition d'une même opération. Conservez le code et le texte de l'erreur avec l'identifiant externe de la demande.

• En cas d'erreur d'autorisation, renouvelez l'accès et ne répétez la requête qu'ensuite.
• En cas de limite de requêtes, respectez une pause selon les règles de l'API.
• En cas de délai d'attente à la création, vérifiez d'abord si l'opération est réellement apparue.
• En cas d'erreur de fonds insuffisants, arrêtez le lot et interrogez balance à nouveau.

Ne créez pas de doublons après un délai d'attente

Un délai d'attente signifie que votre client n'a pas reçu de réponse, et non que le serveur n'a pas traité la requête. Un nouvel envoi sans vérification peut créer une seconde commande et engager à nouveau de l'argent. C'est particulièrement dangereux dans une file où la répétition automatique est configurée sur plusieurs tentatives.

Transmettez un identifiant externe unique de commande si l'API prend en charge le champ client_order_id, external_id ou idempotency_key. Conservez-le avant d'envoyer la requête. Après un délai d'attente, retrouvez l'opération via cette valeur ou demandez le statut via l'identifiant obtenu précédemment.

Une répétition sans vérification est plus rapide, mais son inconvénient est direct : doublons de commandes possibles, double réservation et écarts entre votre calcul de budget et les débits réels.

Que conserver dans le journal de lancement

Le journal aide à reconstituer le déroulement d'une opération massive et à expliquer pourquoi un lot précis s'est arrêté. Pour chaque lancement, conservez l'heure des deux vérifications, total, available, reserved, currency, le budget calculé, la taille de la réserve locale et la liste des identifiants externes des demandes.

Pour chaque tentative de création, enregistrez le coût, le code de réponse, l'identifiant technique de l'opération et le statut final. Les secrets ne doivent pas figurer dans le journal : les jetons d'autorisation, les clés API, les en-têtes complets des requêtes et les données personnelles doivent être masqués ou exclus avant l'enregistrement.

Une journalisation complète est pratique pour le débogage, mais elle a un inconvénient : sans filtrage, des données d'accès et des informations sur les clients peuvent se retrouver dans le stockage.

Testez le schéma sur une petite file

Avant un grand lancement, déroulez un scénario court : obtenez balance, demandez les prix finaux, créez un lot limité, interrogez à nouveau balance et comparez la variation attendue de available et reserved avec la réponse réelle. Cela permet de repérer quand le service réserve la somme et quand il la débite définitivement.

Un lot de test ne garantit pas un comportement identique sous forte charge : des limites, des processus parallèles ou des restrictions propres à un service peuvent intervenir. C'est pourquoi, dans une file massive, continuez à diviser le lancement en lots, à vérifier le solde disponible entre eux et à analyser chaque refus séparément.