Comment configurer le rechargement automatique du solde d'un panneau SMM via API

Ce qu'il faut préparer avant de configurer le rechargement automatique

Le rechargement automatique relie le solde du panneau SMM à un service de paiement ou à une facturation interne. Le service vérifie le solde restant, crée un paiement lorsque le seuil défini est atteint et crédite les fonds uniquement après confirmation du paiement. Pour fonctionner, il faut la documentation de l'API du panneau, l'accès à l'API de paiement, des clés distinctes pour l'environnement de test et l'environnement de production, ainsi qu'un journal de toutes les opérations.

Avant le développement, vérifiez si l'API du panneau permet de renvoyer le solde, d'accepter une demande de crédit, d'afficher l'historique des rechargements et de recevoir un identifiant externe d'opération. Si le panneau ne prend pas en charge le crédit via API, l'automatisation pourra seulement créer une demande ou envoyer une notification à l'opérateur. L'inconvénient de cette option : l'argent devra tout de même être déposé manuellement.

Séparez la vérification du solde et la décision de paiement

Il est préférable de lancer la vérification du solde via une tâche distincte planifiée. Elle récupère le solde, le compare au seuil et transmet le résultat au gestionnaire de rechargement. Ne créez pas de paiement directement au moment de la réponse de l'API sans vérifier les opérations en cours : des tâches parallèles pourraient voir le même solde bas et créer plusieurs paiements.

Avant un nouveau paiement, le gestionnaire doit vérifier qu'il n'existe pas d'opération au statut « créée », « en attente de paiement » ou « en cours de confirmation ». Si une telle entrée existe, une nouvelle tentative n'est pas lancée avant la fin de la réconciliation. L'inconvénient du traitement séquentiel : en cas de réponse longue de l'API externe, le rechargement peut démarrer plus tard qu'avec plusieurs requêtes parallèles.

Choisissez le seuil et la logique du montant de rechargement

Le seuil de solde est choisi avec une marge pour les commandes actives, la file d'attente chez les fournisseurs et les délais de paiement. Pour un canal à activité irrégulière, se fier uniquement à la dépense moyenne est risqué : après un stream, le lancement d'une publicité ou une commande massive, les débits peuvent augmenter brusquement. On définit séparément un niveau critique, auquel une notification est envoyée, mais où le paiement n'est pas nécessairement créé automatiquement.

Le montant du rechargement peut être fixe ou calculé à partir de la dépense sur une période donnée. Un montant fixe est plus simple à contrôler et à réconcilier. Son inconvénient : en période calme, des fonds excédentaires peuvent rester sur le solde, et en cas de forte hausse des commandes, un seul rechargement peut ne pas suffire. Le montant calculé est plus flexible, mais nécessite de nettoyer les statistiques des débits anormaux et des remboursements.

Configurez les limites financières séparément du seuil

Le seuil répond uniquement à la question de savoir quand le système est autorisé à lancer le processus de rechargement. Les limites répondent à une autre question : combien de fonds il est en droit de débiter. Définissez le montant maximal d'une opération, la limite totale sur une période et le solde admissible après crédit. Ces règles sont vérifiées avant la création du paiement, et non après son paiement.

Le rechargement automatique ne doit pas débiter de fonds sans limite par opération et par période. Si le montant calculé dépasse le montant autorisé, il est préférable de transférer l'opération en vérification manuelle et d'envoyer une notification. L'inconvénient des limites strictes : en cas de croissance rapide des dépenses, le solde peut s'épuiser avant que l'employé responsable ne confirme l'augmentation de la limite.

Créez des clés distinctes et protégez l'accès

Pour le script de rechargement automatique, utilisez des clés API distinctes avec des droits minimaux : lecture du solde, création du paiement, vérification du statut et crédit d'une opération confirmée. L'accès aux utilisateurs, aux paramètres des services, aux commandes et au retrait de fonds n'est pas nécessaire pour une telle clé. Si le service prend en charge la restriction par adresses IP, autorisez les requêtes uniquement depuis le serveur d'intégration.

Les clés sont stockées dans des variables d'environnement ou dans un stockage sécurisé de secrets. Ne les transmettez pas dans le code navigateur, les logs, les dépôts publics et les messages d'erreur. Chaque clé doit avoir un propriétaire et une procédure de remplacement claire. L'inconvénient d'une rotation fréquente des clés : le rechargement s'arrêtera si le nouveau secret n'est pas mis à jour dans tous les processus de production.

Créez un paiement avec un identifiant unique

Chaque rechargement se voit attribuer un identifiant interne avant l'appel à l'API de paiement. Il est enregistré dans le journal et transmis comme clé d'idempotence ou numéro externe d'opération. En cas de délai d'attente réseau, la même requête peut être répétée avec le même identifiant : le service de paiement doit renvoyer l'opération déjà créée, et non débiter l'argent une seconde fois.

Ci-dessous — un exemple générique de requête. Remplacez les noms des champs et les adresses par les valeurs de la documentation du fournisseur concerné. La variable PAYMENT_ID contient un ID unique créé à l'avance, et CALLBACK_URL pointe vers le gestionnaire de webhooks.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Ne déterminez pas l'unicité d'un paiement uniquement par le montant et l'heure de création. Deux rechargements identiques peuvent être légitimes, alors qu'une requête répétée après un incident ne l'est pas. L'inconvénient d'un ID externe dans votre propre base : il faut le stocker de manière fiable et ne pas le réutiliser après l'annulation d'une opération.

Vérifiez le solde et conservez l'état de l'opération

La requête de solde doit être exécutée avant la décision d'un nouveau rechargement et après un crédit réussi. La requête générique peut ressembler à ceci : curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Dans la réponse, conservez non seulement le montant, mais aussi l'heure de la vérification, afin de ne pas prendre de décision sur des données obsolètes.

Pour chaque opération, tenez un enregistrement avec l'ID interne, l'ID du paiement chez le fournisseur, le montant, la devise, l'heure de création, le statut, les réponses de l'API et la cause de l'erreur. Une chaîne d'états appropriée : « créée », « en attente de paiement », « payée », « en cours de crédit », « créditée », « annulée », « nécessite une vérification ».

Le crédit dans le panneau n'est autorisé que pour un paiement confirmé et pas encore traité. Ne réécrivez pas les statuts sans historique : en cas de litige, il doit être visible quelle requête a été envoyée et pourquoi l'opération a été modifiée. L'inconvénient d'un journal détaillé : il peut contenir des données sensibles, c'est pourquoi l'accès doit être restreint.

Recevez le webhook et vérifiez le statut du paiement

La page de paiement réussi et la redirection de l'utilisateur ne confirment pas la réception des fonds. La confirmation est le webhook du service de paiement ou une nouvelle vérification du statut via son API. À la réception du webhook, vérifiez la signature, l'heure d'envoi, l'ID du paiement, l'ID externe, le montant et la devise. Ce n'est qu'après cela que vous transférez l'opération à l'état de paiement confirmé.

Après la vérification du webhook, il est utile de demander le statut actuel du paiement au fournisseur. Par exemple : curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Comparez le statut avec les données du journal, puis envoyez une requête de crédit au panneau SMM avec le même ID interne.

Un webhook répété ne doit pas créer un second crédit. Le gestionnaire retrouve l'opération par l'ID externe, voit le statut « créditée » et renvoie une réponse réussie sans nouvelles actions. L'inconvénient des webhooks : ils peuvent être retardés ou ne pas arriver si le gestionnaire était indisponible.

Gérez les délais d'attente, les tentatives et les paiements bloqués

En cas de délai d'attente après la création d'un paiement, n'envoyez pas de nouvelle requête avec un autre ID. Recherchez d'abord l'opération par l'identifiant interne ou répétez la requête avec la même clé d'idempotence. Si le fournisseur a accepté la requête initiale, il renverra le paiement existant. Cela protège contre un double débit en cas de coupure de connexion.

Si le webhook n'est pas arrivé dans le délai défini, une tâche en arrière-plan demande le statut du paiement via l'API. Les vérifications répétées sont effectuées avec une pause croissante et un nombre limité de tentatives, afin de ne pas surcharger l'API et le journal. Une opération qui reste longtemps en attente est transférée en vérification manuelle, et non considérée comme annulée sans réconciliation.

En cas de réponses indiquant une erreur réseau temporaire ou une indisponibilité de l'API, les tentatives sont admissibles. En cas de refus de paiement, de montant incorrect, de signature de webhook invalide ou de dépassement de limite, il ne faut pas répéter la requête automatiquement. L'inconvénient des tentatives : elles compliquent la logique des états et peuvent créer une charge supplémentaire en cas de panne massive chez le fournisseur.

Créditez le paiement confirmé dans le panneau SMM

Avant le crédit, le gestionnaire vérifie encore une fois : le montant ne dépasse pas la limite, la devise correspond, l'opération n'a pas été annulée et son statut n'est pas encore « créditée ». La requête transmet le montant et l'identifiant externe du paiement. Si l'API du panneau prend en charge la clé d'idempotence, utilisez le même ID interne d'opération.

Vue générique de la requête : curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Après la réponse du panneau, demandez à nouveau le solde et enregistrez le résultat dans le journal. Si l'argent a été débité chez le service de paiement, mais que l'API du panneau a renvoyé une erreur, ne créez pas de nouveau paiement. L'opération reste au statut « nécessite une vérification » jusqu'à une nouvelle tentative de crédit ou une réconciliation manuelle. L'inconvénient de ce schéma prudent : le solde peut temporairement ne pas être rechargé automatiquement.

Ajoutez des notifications, un interrupteur et une vérification au démarrage

Les notifications sont nécessaires en cas d'anomalies : le solde est descendu sous le niveau critique, le paiement a été refusé, le webhook n'a pas été reçu, la limite a été dépassée, l'API est indisponible ou l'opération nécessite une vérification manuelle. Dans le message, il suffit d'indiquer l'ID interne, le statut et la cause. N'y incluez pas les clés API, les signatures de webhooks et les coordonnées de paiement.

Prévoyez un interrupteur séparé pour le rechargement automatique sans supprimer l'intégration. Il est nécessaire lors d'un changement de fournisseur, de travaux techniques, en cas de suspicion d'erreur ou de variation brusque des dépenses. L'inconvénient de l'interrupteur est évident : s'il n'est pas réactivé après les travaux, le solde peut s'épuiser pendant des commandes actives.

Liste de contrôle avant d'activer le rechargement automatique

• La vérification du solde ne crée pas de paiement tant qu'une opération est inachevée.
• Pour chaque paiement, un ID interne unique et une clé d'idempotence sont créés.
• Les limites sont configurées pour une opération et pour la période choisie.
• Les webhooks sont vérifiés par signature, montant, devise et identifiant.
• En l'absence de webhook, une nouvelle réconciliation du statut via l'API est lancée.
• Un délai d'attente n'entraîne pas la création d'un second paiement avant la vérification du premier.
• Le crédit dans le panneau est effectué une seule fois et consigné dans le journal.
• Le mode test a été vérifié sur le succès, le refus, le doublon de webhook et l'indisponibilité de l'API.