Calculer montant ↔ nombre de SMS

POST /calculate est le calculateur de tarification bidirectionnel : passez un montant, recevez le nombre de SMS qu’il achète ; passez un nombre de SMS, recevez le montant nécessaire pour les envoyer. Il reflète le widget intégré au tableau de bord pour que les appelants externes n’aient pas à ré-implémenter l’agrégation du prix moyen côté client.

La conversion utilise le prix moyen sur l’ensemble des tuples (pays × réseau téléphonique × tarification) configurés sur votre marchand, dans la devise de votre portefeuille. Si le marchand n’a aucune tarification configurée, l’endpoint renvoie 400.

Montant → Nombre de SMS

Passez mode: "amount_to_sms" avec un amount positif. La réponse inclut la partie entière (floor) de amount / average_price — jamais plus de SMS que ce que le montant achète réellement.

curl $BASE_URL/api/v1/lisoloo/sms-api/calculate \
  -X POST \
  -H "app-key: $LISOLOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "amount_to_sms",
    "amount": 10
  }'

r = requests.post(
    f"{API_URL}/calculate",
    headers=HEADERS,
    json={"mode": "amount_to_sms", "amount": 10},
    timeout=10,
)
r.raise_for_status()
data = r.json()["data"]
print(f"10 $ achète {data['sms_count']} SMS à {data['average_price']} {data['currency']}/SMS")

const r = await fetch(`${API_URL}/calculate`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ mode: "amount_to_sms", amount: 10 }),
});
const { data } = await r.json();
console.log(`10 $ achète ${data.sms_count} SMS à ${data.average_price} ${data.currency}/SMS`);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "$apiUrl/calculate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "app-key: $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'mode'   => 'amount_to_sms',
        'amount' => 10,
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo "{$result['data']['sms_count']} SMS";

Nombre de SMS → Montant

Passez mode: "sms_to_amount" avec un sms_count positif. La réponse inclut sms_count × average_price arrondi à deux décimales.

curl $BASE_URL/api/v1/lisoloo/sms-api/calculate \
  -X POST \
  -H "app-key: $LISOLOO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "sms_to_amount",
    "sms_count": 2000
  }'

r = requests.post(
    f"{API_URL}/calculate",
    headers=HEADERS,
    json={"mode": "sms_to_amount", "sms_count": 2000},
    timeout=10,
)
data = r.json()["data"]
print(f"2000 SMS coûtent {data['amount']} {data['currency']}")

const r = await fetch(`${API_URL}/calculate`, {
  method: "POST",
  headers: HEADERS,
  body: JSON.stringify({ mode: "sms_to_amount", sms_count: 2000 }),
});
const { data } = await r.json();
console.log(`2000 SMS coûtent ${data.amount} ${data.currency}`);

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => "$apiUrl/calculate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        "app-key: $apiKey",
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'mode'      => 'sms_to_amount',
        'sms_count' => 2000,
    ]),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $result['data']['amount'] . ' ' . $result['data']['currency'];

Réponse

{
  "status_code": 200,
  "data": {
    "mode": "amount_to_sms",
    "amount": 10.00,
    "sms_count": 500,
    "average_price": 0.0200,
    "currency": "USD",
    "currency_symbol": "$"
  }
}

Champ	Description
`mode`	Renvoyé depuis la requête.
`amount`	Montant du portefeuille. Valeur d’entrée quand `mode='amount_to_sms'` ; calculé (arrondi à 2 décimales) quand `mode='sms_to_amount'`.
`sms_count`	Nombre de SMS. Calculé (floor, jamais au-dessus de ce que le montant achète) quand `mode='amount_to_sms'` ; valeur d’entrée quand `mode='sms_to_amount'`.
`average_price`	Prix par SMS utilisé pour la conversion, dans `currency`, arrondi à 4 décimales.
`currency`	Code ISO 4217 à trois lettres — votre devise de portefeuille.
`currency_symbol`	Symbole d’affichage pour `currency` (par exemple `$`, `€`, `FC`).

Champs de requête

Champ	Type	Requis	Description
`mode`	enum	Oui	`amount_to_sms` ou `sms_to_amount`.
`amount`	float	Quand `mode='amount_to_sms'`	`0 ≤ amount ≤ 10 000 000`.
`sms_count`	int	Quand `mode='sms_to_amount'`	`0 ≤ sms_count ≤ 10 000 000`.

0 est accepté en entrée — la réponse contiendra simplement 0 pour le champ calculé également, conformément à la façon dont le widget du tableau de bord efface son résultat.

Comment le prix moyen est calculé

La passerelle tire toutes les lignes de tarification configurées sur votre marchand — chaque ligne couvre un tuple (pays, réseau téléphonique) — et les moyenne arithmétiquement dans la devise du portefeuille. Il n’y a pas de pondération par volume de trafic ; chaque destination configurée contribue à parts égales.

Cela fait du calculateur un outil de planification, pas une garantie par message : un vrai POST /send débite le prix exact du réseau de chaque destination, qui peut différer de la moyenne reportée ici.

Ce qui peut mal tourner

HTTP	Cause	Correctif
`400` — `"'amount' is required when mode='amount_to_sms'"`	`mode='amount_to_sms'` mais pas de `amount`.	Ajoutez `amount`.
`400` — `"'sms_count' is required when mode='sms_to_amount'"`	`mode='sms_to_amount'` mais pas de `sms_count`.	Ajoutez `sms_count`.
`400` — `Invalid mode`	`mode` hors enum.	Utilisez `amount_to_sms` ou `sms_to_amount` (minuscules).
`400` — pas de tarification	Le marchand n’a aucune ligne `(pays × réseau × tarification)` configurée.	Configurez les tarifications dans le tableau de bord ou contactez le support.

Voir aussi

Vérifier le solde — solde portefeuille courant et unit_price
Limites de caractères — comptage de segments par message
Envoyer un SMS instantané — l’appel d’envoi réel utilise les prix par destination, pas la moyenne