Zomloa SMSZomloa SMS
API Gateway v1 · Documentation officielle

Documentation Développeurs

Intégrez l'envoi de SMS, la vérification OTP, la détection opérateur et les webhooks en quelques lignes de code.

REST
API v1 JSON
<15s
OTP typique
HMAC
Webhooks signés
24/7
Support & SLA

I. Démarrage rapide

Premiers pas avec l'API

Générez une clé API en 2 minutes et envoyez vos premiers SMS de test.

1

Créez un compte

Inscrivez-vous sur sms.zomloa.app/signup. Des SMS sont offerts pour tester l'API.

2

Générez votre clé API

Dans le tableau de bord, section Clés API : générez une clé secrète (zs_live_...).

3

Configurez votre Sender ID & Envoyez

Demandez un Sender ID personnalisé ou utilisez votre identifiant par défaut, puis intégrez votre code.

Point d'entrée de base (Base URL) : https://api.sms.zomloa.app

II. Endpoints & ressources

Endpoints de l'API Gateway

Toutes les réponses sont au format JSON. Format UTF-8 garanti.

II.1 Envoi de SMS

POSThttps://api.sms.zomloa.app/api/v1/gateway/sms/send

Paramètres de la requête

ParamètreType
X-Api-Keyobligatoire

Clé API secrète (zs_live_…). Alternative : query/form api_key ou Authorization: ApiKey …

header
senderid

Identifiant expéditeur alphanumérique (max. 11 car.). Si omis, le Sender ID approuvé par défaut est utilisé.

string
countryCode

Code ISO du pays de destination (ex: CM, CI, SN, MR, TD, GA, TG, LR, ML, CG). Optionnel si les numéros incluent l'indicatif international.

string
smsobligatoire

Contenu du SMS (160 caractères GSM par segment).

string
mobilesobligatoire

Numéro(s) séparés par des virgules (ex: 237670000000,237690000000).

string
https://api.sms.zomloa.app/api/v1/gateway/sms/send
curl -X POST "https://api.sms.zomloa.app/api/v1/gateway/sms/send" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zs_live_xxxxxxxx" \
  -d '{
    "senderid": "ZOMLOA",
    "countryCode": "CM",
    "sms": "Votre code de confirmation est : 482913",
    "mobiles": "237670000000,237690000000"
  }'

Exemple de réponse (200 OK)

application/json
{
  "responsecode": "200",
  "responsedescription": "SMS accepted for delivery",
  "organizationId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "messageId": "11111111-2222-3333-4444-555555555555",
  "senderid": "ZOMLOA",
  "sms": "Votre code de confirmation est : 482913",
  "mobiles": [
    "237670000000",
    "237690000000"
  ],
  "recipientCount": 2,
  "segmentCount": 1,
  "totalUnits": 2,
  "status": "SENT",
  "balance": 1017
}

II.2 Statut & Détail d'un message

Permet d'interroger en direct l'état de livraison d'un message précis grâce à son `messageId`.

GEThttps://api.sms.zomloa.app/api/v1/gateway/sms/{messageId}
https://api.sms.zomloa.app/api/v1/gateway/sms/{messageId}
curl -X GET "https://api.sms.zomloa.app/api/v1/gateway/sms/11111111-2222-3333-4444-555555555555" \
  -H "X-Api-Key: zs_live_xxxxxxxx"

II.3 Historique récent des envois

Récupère la liste des derniers SMS envoyés par votre organisation (jusqu'à 200 messages).

GEThttps://api.sms.zomloa.app/api/v1/gateway/sms/history
https://api.sms.zomloa.app/api/v1/gateway/sms/history
curl -X GET "https://api.sms.zomloa.app/api/v1/gateway/sms/history?limit=50" \
  -H "X-Api-Key: zs_live_xxxxxxxx"

II.4 Consultation du solde SMS

GET/POSThttps://api.sms.zomloa.app/api/v1/gateway/sms/credit

Paramètres

ParamètreType
X-Api-Keyobligatoire

Clé API secrète de votre organisation.

header
https://api.sms.zomloa.app/api/v1/gateway/sms/credit
curl -X GET "https://api.sms.zomloa.app/api/v1/gateway/sms/credit" \
  -H "X-Api-Key: zs_live_xxxxxxxx"
application/json
{
  "responsecode": "200",
  "responsemessage": "Success",
  "organizationId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "credit": 1017,
  "packname": "Pack 3 000 SMS"
}

II.5 API OTP & Codes de vérification (2FA)

Générez et vérifiez des codes temporaires sans avoir à gérer de stockage ni d'expiration.

1. Envoi du code OTP

POSThttps://api.sms.zomloa.app/api/v1/gateway/otp/send
https://api.sms.zomloa.app/api/v1/gateway/otp/send
curl -X POST "https://api.sms.zomloa.app/api/v1/gateway/otp/send" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zs_live_xxxxxxxx" \
  -d '{
    "mobile": "237670000000",
    "senderid": "ZOMLOA",
    "codeLength": 6,
    "ttlSeconds": 300,
    "template": "Votre code Zomloa est : {code}"
  }'
Réponse 201 Created
{
  "responsecode": "200",
  "responsedescription": "OTP sent successfully",
  "otpId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "mobile": "237670000000",
  "messageId": "11111111-2222-3333-4444-555555555555",
  "expiresAt": "2026-08-30T14:15:00.000Z",
  "codeLength": 6,
  "maxAttempts": 3
}

2. Vérification du code OTP saisi par l'utilisateur

POSThttps://api.sms.zomloa.app/api/v1/gateway/otp/verify
https://api.sms.zomloa.app/api/v1/gateway/otp/verify
curl -X POST "https://api.sms.zomloa.app/api/v1/gateway/otp/verify" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zs_live_xxxxxxxx" \
  -d '{
    "otpId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "code": "482913"
  }'
Réponse 200 OK
{
  "responsecode": "200",
  "valid": true,
  "message": "OTP verified successfully",
  "attemptsRemaining": 2
}

II.6 Détection & Validation de numéro (Lookup)

Identifiez le pays, la validité et l'opérateur mobile d'un numéro avant tout envoi.

GET/POSThttps://api.sms.zomloa.app/api/v1/gateway/lookup
https://api.sms.zomloa.app/api/v1/gateway/lookup
curl -X POST "https://api.sms.zomloa.app/api/v1/gateway/lookup" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zs_live_xxxxxxxx" \
  -d '{"mobile": "237670000000"}'
application/json
{
  "responsecode": "200",
  "mobile": "237670000000",
  "valid": true,
  "countryCode": "CM",
  "operator": "MTN",
  "isKnownOperator": true
}

II.7 Liste des Sender IDs approuvés

Récupère les identifiants d'expéditeur autorisés et validés pour votre organisation.

GEThttps://api.sms.zomloa.app/api/v1/gateway/sender-ids
https://api.sms.zomloa.app/api/v1/gateway/sender-ids
curl -X GET "https://api.sms.zomloa.app/api/v1/gateway/sender-ids" \
  -H "X-Api-Key: zs_live_xxxxxxxx"

II.8 Gestion de la Stop List (Désabonnements)

Ajoutez ou retirez des numéros de téléphone de votre liste de désinscription automatique.

GET/POSThttps://api.sms.zomloa.app/api/v1/gateway/stop-list
https://api.sms.zomloa.app/api/v1/gateway/stop-list
curl -X POST "https://api.sms.zomloa.app/api/v1/gateway/stop-list" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: zs_live_xxxxxxxx" \
  -d '{"mobile": "237670000000", "note": "Demande STOP client"}'

II.9 Webhooks & Accusés de réception (DLR)

Recevez les notifications d'état de remise en temps réel (delivered, failed) sur votre serveur avec vérification d'authenticité via signature HMAC-SHA256.

Exemple de Payload Webhook envoyé par Zomloa

application/json
{
  "event": "delivered",
  "timestamp": "2026-08-30T14:10:05.123Z",
  "data": {
    "messageId": "11111111-2222-3333-4444-555555555555",
    "recipientMobile": "237670000000",
    "senderId": "ZOMLOA",
    "units": 1,
    "status": "DELIVERED",
    "deliveredAt": "2026-08-30T14:10:04.000Z",
    "failureReason": null
  }
}

Vérification de la signature HMAC-SHA256 (Node.js & PHP)

Vérification Webhook
import crypto from 'crypto';

app.post('/webhook/sms', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-zomloa-signature'];
  const secret = process.env.ZOMLOA_WEBHOOK_SECRET;

  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(req.body).digest('hex');

  if (signature !== digest) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());
  console.log('Event received:', event.event, event.data.messageId);
  res.status(200).send('OK');
});

III. Gestion des erreurs

Codes d'erreur standard

Tableau des codes d'erreur et format de réponse en cas de rejet.

Code d'erreurSignification
ERR_INVALID_API_KEYClé API manquante, expirée ou invalide (HTTP 401)
ERR_VALIDATION_FAILEDParamètres obligatoires manquants ou invalides (HTTP 400)
ERR_INVALID_SENDER_IDFormat SID invalide (max 11 caractères alphanumériques)
ERR_SENDER_ID_NOT_APPROVEDLe Sender ID demandé n'est pas encore approuvé
ERR_INSUFFICIENT_SMS_BALANCESolde SMS insuffisant pour couvrir cet envoi (HTTP 400/402)
ERR_ORGANIZATION_SUSPENDEDOrganisation suspendue temporairement (HTTP 403)
ERR_INTERNAL_SERVER_ERRORErreur technique côté serveur (HTTP 500)

Format de réponse d'erreur

application/json
{
  "code": "ERR_INVALID_API_KEY",
  "message": "API key is invalid",
  "path": "/api/v1/gateway/sms/send",
  "timestamp": "2026-08-30T14:00:00.000Z"
}

Prêt à envoyer votre premier SMS ?

Créez votre compte Zomloa SMS et connectez votre API ou lancez une campagne en quelques minutes.

Une seule API. Tous les opérateurs. Des SMS qui arrivent.

S'inscrire gratuitementVoir les tarifs