đ±
API Passerelle SMS B2B (SMS)
Référentiel complet des Endpoints, RÎles et Payloads
Envoi unitaire de SMS sécurisé (LCR / QoS)
Expédie un SMS sécurisé avec signature HMAC-SHA256, Smart Routing dynamique (LCR au moindre coût ou QoS haute qualité) et bascule automatique Circuit Breaker.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/json |
X-SMS-API-KEY |
sms_live_key_acme_2026_x89f2 |
X-SMS-TIMESTAMP |
1774198200 (Timestamp UNIX actuel, tolérance ±300s) |
X-SMS-NONCE |
nonce_aleatoire_unique_16_caracteres |
X-SMS-SIGNATURE |
HMAC-SHA256(METHOD\nPATH\nTIMESTAMP\nNONCE\nSHA256(BODY), SECRET) |
Structure du Payload (Corps JSON)
| Champ | Type | Obligatoire ? | Description |
to |
string |
OUI
|
Numéro destinataire au format international E.164 (ex: "+33612345678") |
from |
string |
Optionnel
|
Expéditeur alphanumérique personnalisé (jusqu'à 11 caractÚres, ex: "MON-ENTREPRISE") |
message |
string |
OUI
|
Corps du texte SMS (encodage GSM-7 ou UCS-2 Unicode géré automatiquement) |
routing_strategy |
string |
Optionnel
|
"lcr" (moindre coût, par défaut), "qos" (qualité maximale) ou "balanced" |
provider_id |
integer |
Optionnel
|
ID d'un opérateur spécifique pour forcer son utilisation prioritaire |
Exemple de RequĂȘte JSON
{
"to": "+33612345678",
"from": "ACME-NOTIF",
"message": "Votre code d'authentification est : 492019. Valable 10 minutes.",
"routing_strategy": "lcr"
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"message_uuid": "d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234",
"status": "sent",
"recipient": "+33612345678",
"sender_id": "ACME-NOTIF",
"segments": 1,
"encoding": "GSM7",
"character_count": 64,
"routing_strategy": "lcr",
"provider_used": "Twilio Direct API",
"provider_message_id": "SM_twilio_9981240129",
"cost_debited": 0.035,
"currency": "EUR",
"remaining_balance": 99.965,
"attempts_count": 1
}
Réponse Erreur Type
{
"success": false,
"error": "Signature HMAC-SHA256 invalide ou timestamp expiré.",
"code": 401
}
Envoi groupé de SMS (Bulk)
Permet d'expédier en lot des SMS personnalisés avec gestion des quotas et débit régulé.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/json |
X-SMS-API-KEY |
sms_live_key_acme_2026_x89f2 |
X-SMS-TIMESTAMP |
1774198200 |
X-SMS-NONCE |
nonce_aleatoire_unique |
X-SMS-SIGNATURE |
HMAC-SHA256 signature |
Structure du Payload (Corps JSON)
| Champ | Type | Obligatoire ? | Description |
messages |
array of objects |
OUI
|
Tableau de SMS contenant chacun "to", "message" et éventuellement "from" |
routing_strategy |
string |
Optionnel
|
"lcr" ou "qos" |
Exemple de RequĂȘte JSON
{
"messages": [
{
"to": "+33612345678",
"message": "Rappel : Votre rendez-vous de demain à 14h30 est confirmé."
},
{
"to": "+33698765432",
"message": "Rappel : Votre rendez-vous de demain à 15h00 est confirmé."
}
],
"routing_strategy": "lcr"
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"batch_uuid": "batch_sms_44a19e8",
"total": 2,
"accepted": 2,
"failed": 0,
"total_cost": 0.07,
"currency": "EUR",
"results": [
{
"to": "+33612345678",
"uuid": "msg_1",
"status": "sent"
},
{
"to": "+33698765432",
"uuid": "msg_2",
"status": "sent"
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "Solde insuffisant pour expédier ce lot de SMS.",
"code": 402
}
Statut & historique de bascule d'un SMS
Consulte le statut d'acheminement d'un SMS, son statut de remise DLR (DELIVRD, UNDELIV) et l'historique des tentatives de routage.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
| En-tĂȘte | Valeur / Exemple |
X-SMS-API-KEY |
sms_live_key_acme_2026_x89f2 |
X-SMS-TIMESTAMP |
1774198200 |
X-SMS-NONCE |
nonce_unique |
X-SMS-SIGNATURE |
HMAC-SHA256 signature |
Structure du Payload (ParamĂštres d'URL)
| Champ | Type | Obligatoire ? | Description |
uuid |
string (query param) |
OUI
|
Identifiant UUID du SMS retourné lors de l'envoi |
Exemple de RequĂȘte JSON
{
"query_params": "?uuid=d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234"
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"message_uuid": "d4a8e2b1-5f3c-4a92-91e8-73b0c95a1234",
"status": "delivered",
"recipient": "+33612345678",
"provider_used": "Twilio Direct API",
"dlr_status": "DELIVRD",
"dlr_received_at": "2026-09-22 01:18:24",
"cascade_attempts": [
{
"attempt": 1,
"provider": "Twilio Direct API",
"success": true,
"latency_ms": 140
}
]
}
Réponse Erreur Type
{
"success": false,
"error": "SMS UUID introuvable.",
"code": 404
}
Solde de crédits & consommation des quotas
Retourne le solde financier disponible en temps réel, la devise, les quotas mensuels alloués et le volume consommé.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
| En-tĂȘte | Valeur / Exemple |
X-SMS-API-KEY |
sms_live_key_acme_2026_x89f2 |
X-SMS-TIMESTAMP |
1774198200 |
X-SMS-NONCE |
nonce_unique |
X-SMS-SIGNATURE |
HMAC-SHA256 signature |
Structure du Payload (ParamĂštres d'URL)
| Champ | Type | Obligatoire ? | Description |
format |
string (query param) |
Optionnel
|
Optionnel ("json") |
Exemple de RequĂȘte JSON
{
"query_params": ""
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"tenant": "Acme Corporation",
"credit_balance": 99.965,
"currency": "EUR",
"monthly_quota_sms": 10000,
"monthly_consumed_sms": 124,
"quota_remaining_sms": 9876,
"rate_limit_per_second": 50
}
Réponse Erreur Type
{
"success": false,
"error": "Non authentifié.",
"code": 401
}
Réception des accusés de remise (DLR)
Endpoint récepteur des notifications de remise (Delivery Reports) envoyées par les opérateurs SMS (Twilio, Infobip, Vonage) pour mettre à jour l'état final de réception sur le terminal de l'utilisateur.
En-tĂȘtes HTTP Requis (HMAC-SHA256)
| En-tĂȘte | Valeur / Exemple |
Content-Type |
application/x-www-form-urlencoded ou application/json |
Structure du Payload (Corps JSON)
| Champ | Type | Obligatoire ? | Description |
MessageSid |
string |
OUI
|
ID externe du message |
MessageStatus |
string |
OUI
|
"delivered", "undelivered", "failed" |
Exemple de RequĂȘte JSON
{
"MessageSid": "SM_twilio_9981240129",
"MessageStatus": "delivered"
}
Réponse SuccÚs (HTTP 200)
{
"success": true,
"message": "DLR acquitté."
}
Réponse Erreur Type
{
"success": false,
"error": "Message introuvable pour ce DLR."
}