Être prévenu quand les crédits sont bas, et recharger automatiquement

Oui : GET /v1/balance donne low_balance, une alerte WhatsApp part au contact du compte quand le solde passe sous le seuil (au plus une fois par 12 h), et la recharge automatique par carte se configure dans la console, pas par l'API.

Être prévenu quand les crédits sont bas, et recharger automatiquement

Astuce
Oui : GET /v1/balance donne low_balance, une alerte WhatsApp part au contact du compte quand le solde passe sous le seuil (au plus une fois par 12 h), et la recharge automatique par carte se configure dans la console, pas par l'API.

Scénario

Votre application envoie des rappels toute la semaine. Un jour le solde tombe à zéro et les envois de templates sont refusés en 402. Oui, vous pouvez être prévenu avant, et vous pouvez faire recharger automatiquement. Mais il faut savoir exactement ce qui part, et ce qui ne part pas.

Savoir où en est le solde

curl

curl -X GET "https://wa-api.geskap.com/v1/balance" \
  -H "Authorization: Bearer $GESKAP_API_KEY"

Node.js

const res = await fetch("https://wa-api.geskap.com/v1/balance", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.GESKAP_API_KEY}`,
  },
});
console.log(res.status, await res.json());

PHP

$ch = curl_init("https://wa-api.geskap.com/v1/balance");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("GESKAP_API_KEY"),
  ],
]);
$res = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $res;

Python

import os, requests

res = requests.request(
    "GET",
    "https://wa-api.geskap.com/v1/balance",
    headers={"Authorization": f"Bearer {os.environ['GESKAP_API_KEY']}"},
    timeout=15,
)
print(res.status_code, res.json())

La réponse donne credit_balance, low_balance_threshold et low_balance (vrai quand le solde est inférieur ou égal au seuil). Chaque POST /v1/messages renvoie aussi l'en-tête X-Credits-Remaining. Surveillez-le dans votre code : c'est le signal le plus rapide.

L'alerte automatique

Quand un envoi de template laisse un solde inférieur ou égal au seuil, un message WhatsApp d'alerte est envoyé, depuis votre propre numéro, au numéro de contact du compte. Il part au plus une fois toutes les 12 heures.

Le seuil d'alerte (low_balance_threshold) est un réglage du compte, modifié par l'administrateur : vous ne le changez pas vous-même.
L'alerte est évaluée après un envoi de template (POST /v1/messages), pas après une réponse libre.
Elle ne part que si le compte a un numéro de contact et un numéro WhatsApp connecté. Sinon, rien.
L'horodatage est posé avant l'envoi : si WhatsApp refuse l'alerte, la suivante n'est pas retentée avant 12 h.
Ce n'est pas un événement de webhook : votre serveur ne reçoit rien. Vos événements webhook sont message.status, message.inbound et message.echo.
Le code contient aussi des e-mails de rappel de solde bas ou épuisé, mais leur envoi dépend d'un réglage de la plateforme : ne bâtissez pas votre surveillance dessus.

Recharger à la main, par l'API

curl

curl -X GET "https://wa-api.geskap.com/v1/credits/packs" \
  -H "Authorization: Bearer $GESKAP_API_KEY"

Node.js

const res = await fetch("https://wa-api.geskap.com/v1/credits/packs", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.GESKAP_API_KEY}`,
  },
});
console.log(res.status, await res.json());

PHP

$ch = curl_init("https://wa-api.geskap.com/v1/credits/packs");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("GESKAP_API_KEY"),
  ],
]);
$res = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $res;

Python

import os, requests

res = requests.request(
    "GET",
    "https://wa-api.geskap.com/v1/credits/packs",
    headers={"Authorization": f"Bearer {os.environ['GESKAP_API_KEY']}"},
    timeout=15,
)
print(res.status_code, res.json())

Choisissez un pack (pack_code) puis payez par carte. Avec use_saved_card et une carte déjà enregistrée, la carte est débitée sans redirection et les crédits arrivent tout de suite. Sinon, la réponse contient checkout_url : ouvrez-la pour payer. Le premier paiement enregistre la carte.

curl

curl -X POST "https://wa-api.geskap.com/v1/credits/checkout" \
  -H "Authorization: Bearer $GESKAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "pack_code": "standard", "use_saved_card": true }'

Node.js

const res = await fetch("https://wa-api.geskap.com/v1/credits/checkout", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GESKAP_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ "pack_code": "standard", "use_saved_card": true }),
});
console.log(res.status, await res.json());

PHP

$ch = curl_init("https://wa-api.geskap.com/v1/credits/checkout");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("GESKAP_API_KEY"),
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode(["pack_code" => "standard", "use_saved_card" => true]),
]);
$res = curl_exec($ch);
echo curl_getinfo($ch, CURLINFO_HTTP_CODE), " ", $res;

Python

import os, requests

res = requests.request(
    "POST",
    "https://wa-api.geskap.com/v1/credits/checkout",
    headers={"Authorization": f"Bearer {os.environ['GESKAP_API_KEY']}"},
    json={"pack_code": "standard", "use_saved_card": True},
    timeout=15,
)
print(res.status_code, res.json())

La recharge automatique

Elle se configure dans la console (PUT /v1/console/autorecharge, avec votre session de console) : activer, seuil, et pack à acheter. Il n'existe pas de route pour la régler avec une clé API.

Règle	Valeur
Condition	une carte est enregistrée, et le solde est strictement inférieur au seuil
Seuil par défaut	50 crédits (réglable par vous)
Délai minimal entre deux recharges	1 heure
Plafond	3 recharges par mois calendaire
Quand elle se déclenche	après un envoi POST /v1/messages, et lors d'un balayage quotidien à 04:00 UTC
Si la carte est refusée ou demande une authentification	la recharge automatique est désactivée

Quand elle se désactive, une ligne « Recharge automatique désactivée » apparaît dans GET /v1/logs?category=rejects avec la raison. Rechargez une fois manuellement, puis réactivez-la dans la console.

Attention
Piège : deux seuils différents existent. low_balance_threshold déclenche l'alerte et le drapeau low_balance (solde inférieur ou égal). Le seuil de la recharge automatique est le vôtre, et la recharge ne part que si le solde est strictement inférieur. Réglez le seuil de recharge au-dessus de ce que votre trafic consomme entre deux balayages.

Attention
Piège : à solde nul, un template répond 402 « Solde de crédits insuffisant » et rien ne part. Une réponse libre dans les 24 h, elle, part quand même (son débit ne bloque jamais). Voir Coût d'un message.

Attention
Piège : la recharge est tentée juste après l'envoi qui a fait passer le solde sous le seuil. Si elle échoue, l'envoi reste réussi et rien ne vous est signalé dans la réponse ; le balayage de 04:00 UTC retentera. Gardez une marge de crédits plutôt que de compter sur elle au dernier moment.

Preuve — vérifié dans le code de l'API : public_api.py, api_alerts.py, api_send.py, autorecharge.py, broadcast_scheduler.py, console_api.py.