Vérifier le solde

GET /balance retourne le crédit SMS restant, le prix unitaire par segment, et le nombre projeté de SMS que votre solde actuel peut acheter.

Requête

cURL

curl $BASE_URL/api/v1/lisoloo/sms-api/balance \
  -H "app-key: $LISOLOO_API_KEY"

Python

r = requests.get(
    "$BASE_URL/api/v1/lisoloo/sms-api/balance",
    headers={"app-key": os.environ["LISOLOO_API_KEY"]},
    timeout=10,
)
print(r.json())

JavaScript

const r = await fetch(
  "$BASE_URL/api/v1/lisoloo/sms-api/balance",
  { headers: { "app-key": process.env.LISOLOO_API_KEY } },
);
console.log(await r.json());

PHP

$ch = curl_init('$BASE_URL/api/v1/lisoloo/sms-api/balance');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ["app-key: $apiKey"],
]);
echo curl_exec($ch);

Réponse

{
  "status_code": 200,
  "data": {
    "balance":                 100.50,
    "sms_wallet_balance":       80.00,
    "postpaid_wallet_balance":  20.50,
    "currency":                "USD",
    "unit_price":               0.02,
    "available_sms":            5025
  }
}

Champ	Description
balance	Crédit combiné sur les deux portefeuilles (sms_wallet_balance + postpaid_wallet_balance), dans currency. Décimal.
sms_wallet_balance	Crédit du portefeuille SMS prépayé. Débité en premier à chaque /send. Renvoie 0 si aucun portefeuille prépayé n’existe.
postpaid_wallet_balance	Crédit du portefeuille postpayé. Utilisé en relais quand le portefeuille prépayé est épuisé (sous réserve de votre contrat postpayé). Renvoie 0 si aucun portefeuille postpayé n’existe.
currency	Code ISO 4217 à trois lettres — devise de règlement de votre marchand. Tirée de la référence devise du portefeuille primaire.
unit_price	Coût d’un segment SMS dans currency. Lu depuis votre ligne de tarification client. Fallback à 0.01 si aucune tarification n’est configurée.
available_sms	floor(balance / unit_price) — nombre de segments supplémentaires que votre solde combiné peut acheter maintenant.

Modèle à deux portefeuilles

Lisoloo débite chaque envoi contre deux portefeuilles dans l’ordre :

1. LISOLOO_SMS — le portefeuille SMS prépayé que vous rechargez depuis le tableau de bord. Consommé en premier.
2. LISOLOO_POST_PAID — le portefeuille postpayé, présent uniquement si votre compte a un accord postpayé. Consommé quand le prépayé est épuisé.

L’endpoint renvoie 400 si aucun des deux portefeuilles n’existe sur votre organisation. Si un seul existe, l’autre renvoie 0 et balance reflète seulement celui présent.

Estimation de coût pré-vol

Combinez GET /balance avec le compteur de segments de Limites de caractères pour refuser un envoi avant soumission :

def can_afford(message: str, recipients: int) -> bool:
    bal      = requests.get(BALANCE_URL, headers=HEADERS).json()["data"]
    segments = count_segments(message)
    cost     = segments * recipients * bal["unit_price"]
    return cost <= bal["balance"]

if not can_afford(MESSAGE, len(RECIPIENTS)):
    raise BalanceExhausted("Rechargez avant d'envoyer.")

La passerelle applique aussi cela côté serveur et renvoie 1202 INSUFFICIENT_BALANCE si vous soumettez au-delà de votre solde — mais vérifier côté client évite un aller-retour gaspillé.

Mise en cache

L’endpoint de solde est limité à 30/min par clé. Mettez la réponse en cache pour ≥ 30 secondes dans votre application — les soldes ne changent pas plus vite que votre propre cadence de POST /send, plus les rechargements administratifs.

Voir aussi

• Calculer montant ↔ SMS — calculateur de tarification bidirectionnel côté serveur
• Limites de caractères — comptage de segments
• Erreurs — gestion de 1202 INSUFFICIENT_BALANCE