Documentation API Client

Guide complet pour envoyer des SMS via API REST ou SMPP avec l'API Simplify-SMS

Introduction

Cette documentation vous guide dans l'utilisation de l'API Simplify-SMS pour envoyer des SMS via le protocole SMPP ou API REST. Vous apprendrez comment authentifier vos requêtes, envoyer des messages, suivre leur statut et consulter vos informations de compte.

GET Base URL

Toutes les requêtes doivent être envoyées à l'URL de base de votre serveur.

Base URL

https://sms.sn

Fonctionnalités disponibles

Envoi de SMS unique ou multiple via SMPP ou API REST
Suivi du statut de vos messages (sent, delivered, failed, etc.)
Consultation des logs de messages avec filtres avancés
Téléchargement de rapports Excel
Vérification du solde de votre compte

Authentification

Tous les endpoints (sauf l'envoi de SMS) nécessitent une authentification via token JWT Bearer dans les headers. Vous devez d'abord vous connecter pour obtenir un token d'accès.

POST /auth/login

🔓 Aucune authentification requise

Connectez-vous avec vos identifiants client (email et mot de passe) pour obtenir un token JWT.

Headers

Content-Type: application/json

Body

                            {
  "username": "client@example.com",
  "password": "votre_mot_de_passe"
}
                        

Réponse

                            {
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "role": "client",
  "user": {
    "id": "123",
    "clientId": "client_abc123",
    "username": "client@example.com",
    "role": "client"
  }
}
                        

Exemple cURL

                            curl -X POST https://sms.sn/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "client@example.com",
    "password": "votre_mot_de_passe"
  }'
                        

Utilisation du Token

Une fois le token obtenu, incluez-le dans toutes vos requêtes authentifiées :

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Durée de validité

Le token JWT est valide pendant 5 jours. Après expiration, vous devrez vous reconnecter pour obtenir un nouveau token.

Envoi de SMS

Vous pouvez envoyer des SMS de deux façons : via API REST (simple et rapide) ou via protocole SMPP (pour une intégration native SMPP). Les deux méthodes envoient les messages en temps réel à l'opérateur via notre gateway SMPP.

📋 Comparaison des méthodes

Caractéristique	API REST	Protocole SMPP
Complexité	Simple (HTTP/JSON)	Avancée (protocole binaire SMPP)
Connexion	Stateless (chaque requête est indépendante)	Stateful (connexion persistante)
DLR (Delivery Receipts)	Via webhook URL optionnel	Reçus automatiquement via DELIVER_SM
Débit	5 req/min (rate limit)	Illimité (selon votre configuration)
Idéal pour	Intégrations simples, applications web	Applications haute performance, systèmes existants SMPP

Méthode 1 : API REST

POST /sms/send

🔓 Aucune authentification requise

Envoie un SMS unique via API REST. Le message est relayé à l'opérateur via notre gateway SMPP en temps réel.

Limite de débit

⚠️ Limite : 5 requêtes par minute par IP

Body - Paramètres

Paramètre	Type	Requis	Description
username	string	Requis	System ID SMPP de votre compte
password	string	Requis	Mot de passe SMPP de votre compte
msisdn	string	Requis	Numéro de téléphone du destinataire (format international, ex: +33612345678)
message	string	Requis	Contenu du SMS (1-500 caractères)
source_addr	string	Optionnel	Adresse source (expéditeur). Si non fourni, utilise l'adresse par défaut
webhookUrl	string (URL)	Optionnel	URL de callback pour recevoir les DLR (Delivery Receipts)
clientMessageId	string	Optionnel	ID personnalisé pour le suivi de votre message

Exemple de Requête

                            {
  "username": "mon_system_id",
  "password": "mon_mot_de_passe_smpp",
  "msisdn": "+33612345678",
  "message": "Bonjour, ceci est un message de test",
  "source_addr": "MONENTREPRISE",
  "clientMessageId": "msg_20241201_001",
  "webhookUrl": "https://mon-site.com/webhook/dlr"
}
                        

Exemple cURL

                            curl -X POST https://sms.sn/sms/send \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mon_system_id",
    "password": "mon_mot_de_passe_smpp",
    "msisdn": "+33612345678",
    "message": "Bonjour, ceci est un message de test",
    "source_addr": "MONENTREPRISE",
    "clientMessageId": "msg_20241201_001"
  }'
                        

Réponse

                            {
  "success": true,
  "messageId": "SMPP_MSG_1234567890",
  "simulated": false
}
                        

Codes d'erreur possibles

Code	Description
400	Paramètres invalides (message trop long, msisdn invalide, etc.)
401	Identifiants SMPP invalides
402	Crédits insuffisants
429	Trop de requêtes (rate limit dépassé)
502	Erreur SMPP (problème de connexion avec l'opérateur)

POST /sms/send-multi

🔓 Aucune authentification requise

Envoie plusieurs SMS en utilisant la file d'attente (queue). Idéal pour les campagnes ou l'envoi en masse. Les messages sont traités de manière asynchrone et relayés à l'opérateur via notre gateway SMPP.

Limite de débit

⚠️ Limite : 3 requêtes par minute par IP

Body

Même structure que /sms/send. Le message sera ajouté à la queue pour traitement asynchrone.

                            {
  "username": "mon_system_id",
  "password": "mon_mot_de_passe_smpp",
  "msisdn": "+33612345678",
  "message": "Message pour plusieurs destinataires",
  "source_addr": "MONENTREPRISE",
  "clientMessageId": "campaign_20241201_001"
}
                        

Exemple cURL

                            curl -X POST https://sms.sn/sms/send-multi \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mon_system_id",
    "password": "mon_mot_de_passe_smpp",
    "msisdn": "+33612345678",
    "message": "Message pour plusieurs destinataires"
  }'
                        

Réponse

                            {
  "id": "job_1234567890",
  "name": "send",
  "data": { ... },
  "opts": { ... },
  "timestamp": 1701432000000
}
                        

Méthode 2 : Protocole SMPP

SMPP Connexion SMPP

🔐 Authentification SMPP requise

Connectez-vous directement via le protocole SMPP pour envoyer des messages. Cette méthode nécessite une connexion persistante et est idéale pour les applications haute performance.

Configuration de connexion

Paramètre	Valeur	Description
Host	votre-domaine.com	Adresse du serveur SMPP
Port	2775	Port SMPP (par défaut, peut être configuré via SMPP_LISTEN_PORT)
System ID	votre_system_id	Votre identifiant SMPP (fourni lors de la création du compte)
Password	votre_password	Votre mot de passe SMPP
Bind Type	BIND_TRANSCEIVER	Type de bind (permet d'envoyer et recevoir)

Étapes de connexion

Connexion TCP : Établissez une connexion TCP vers le serveur SMPP
BIND_TRANSCEIVER : Envoyez une commande BIND avec votre system_id et password
Validation : Le serveur valide vos identifiants, votre IP (whitelist), et vos crédits
Confirmation : Si validé, vous recevez un BIND_RESP avec command_status = 0
Envoi de messages : Vous pouvez maintenant envoyer des SUBMIT_SM

Exemple de BIND_TRANSCEIVER (Node.js avec smpp)

                            const smpp = require('smpp');

const session = smpp.connect({
  host: 'votre-domaine.com',
  port: 2775
});

session.on('connect', () => {
  session.bind_transceiver({
    system_id: 'votre_system_id',
    password: 'votre_password'
  }, (pdu) => {
    if (pdu.command_status === 0) {
      console.log('Connecté avec succès !');
      // Vous pouvez maintenant envoyer des messages
    } else {
      console.error('Erreur de connexion:', pdu.command_status);
    }
  });
});
                        

Envoi d'un message (SUBMIT_SM)

                            session.submit_sm({
  source_addr: 'MONENTREPRISE',
  destination_addr: '+33612345678',
  short_message: 'Votre message SMS ici'
}, (pdu) => {
  if (pdu.command_status === 0) {
    console.log('Message ID:', pdu.message_id);
    // Le message_id retourné est le clientMessageId
  } else {
    console.error('Erreur:', pdu.command_status);
  }
});
                        

Réception des DLR (Delivery Receipts)

Les DLR sont automatiquement relayés depuis l'opérateur vers votre session SMPP via des PDU DELIVER_SM.

                            session.on('deliver_sm', (pdu) => {
  // Le DLR contient le statut de livraison
  const shortMessage = pdu.short_message?.message || pdu.short_message;
  console.log('DLR reçu:', shortMessage);
  
  // Parser le DLR pour obtenir le statut
  // Format typique: id:... sub:... dlvrd:... submit date:... done date:... stat:... err:... text:...
});
                        

Codes d'erreur SMPP courants

Code	Nom	Description
0x00000003	ESME_RINVSYSID	System ID invalide ou IP non autorisée
0x0000000E	ESME_RINVPASWD	Mot de passe invalide
0x00000009	ESME_RINVBNDSTS	Bind requis avant d'envoyer des messages
0x0000040B	ESME_RNOCREDITS	Crédits insuffisants
0x0000040C	ESME_RINVALIDPHONENUMBER	Numéro de téléphone invalide
0x00000058	ESME_RTHROTTLED	Quota horaire ou journalier dépassé

Validations effectuées

Lors de la connexion et de l'envoi, le serveur effectue les validations suivantes :

BIND : Validation IP whitelist, identifiants, crédits disponibles
SUBMIT_SM : Validation source address, quotas horaires/journaux, crédits, numéro de téléphone
Relais : Le message est relayé à l'opérateur via notre gateway SMPP
DLR : Les DLR de l'opérateur sont automatiquement relayés vers votre session

Note importante

⚠️ Votre adresse IP doit être dans la whitelist autorisée pour votre System ID. Contactez le support pour ajouter votre IP à la whitelist si nécessaire.

Statut et suivi des messages

Consultez le statut de vos messages envoyés, consultez les logs et téléchargez des rapports détaillés.

GET /smpp/client/message-status

🔒 Authentification requise

Récupère le statut détaillé d'un message envoyé. Vous pouvez utiliser soit le clientMessageId que vous avez fourni lors de l'envoi, soit le operatorMessageId retourné par l'opérateur.

Query Parameters

Paramètre	Type	Requis	Description
clientMessageId	string	Optionnel*	ID du message fourni lors de l'envoi (au moins un des deux est requis)
operatorMessageId	string	Optionnel*	ID du message retourné par l'opérateur SMPP (au moins un des deux est requis)

* Au moins un des deux paramètres doit être fourni

Exemple de Requête

                            GET /smpp/client/message-status?clientMessageId=msg_20241201_001
Headers:
  Authorization: Bearer <votre_token>
                        

Exemple cURL

                            curl -X GET "https://sms.sn/smpp/client/message-status?clientMessageId=msg_20241201_001" \
  -H "Authorization: Bearer <votre_token>"
                        

Réponse

                            {
  "id": "12345",
  "clientMessageId": "msg_20241201_001",
  "operatorMessageId": "SMPP_MSG_1234567890",
  "status": "delivered",
  "sourceAddr": "MONENTREPRISE",
  "destinationAddr": "+33612345678",
  "country": "FR",
  "createdAt": "2024-12-01T10:00:00.000Z",
  "updatedAt": "2024-12-01T10:00:05.000Z",
  "dlr": {
    "status": "DELIVRD",
    "statusText": "Message delivered",
    "errorCode": null,
    "msisdn": "+33612345678",
    "deliveryDateTime": "2024-12-01T10:00:05.000Z",
    "sendDateTime": "2024-12-01T10:00:00.000Z"
  },
  "systemId": "mon_system_id",
  "client": {
    "clientId": "client_abc123",
    "name": "Mon Entreprise",
    "email": "client@example.com"
  }
}
                        

Statuts possibles

Statut	Description
pending	Message en attente d'envoi
sent	Message envoyé à l'opérateur
delivered	Message livré au destinataire
failed	Échec de l'envoi
expired	Message expiré (non livré dans les délais)

GET /smpp/client/messages-logs/:id

🔒 Authentification requise

Liste tous vos messages envoyés avec pagination et filtres avancés. Permet de rechercher dans l'historique de vos messages.

Path Parameters

Paramètre	Type	Description
:id	string	Votre Client ID

Query Parameters

Paramètre	Type	Requis	Description
page	number	Optionnel	Numéro de page (défaut: 1)
limit	number	Optionnel	Nombre d'éléments par page (défaut: 10)
recipient	string	Optionnel	Filtrer par numéro de destinataire
fromDate	string	Optionnel	Date de début (format: YYYY-MM-DD)
toDate	string	Optionnel	Date de fin (format: YYYY-MM-DD)
status	string	Optionnel	Filtrer par statut (sent, delivered, failed, pending, expired)
clientMessageId	string	Optionnel	Rechercher par ID de message client
operatorMessageId	string	Optionnel	Rechercher par ID de message opérateur
texte	string	Optionnel	Rechercher dans le contenu des messages

Exemple de Requête

                            GET /smpp/client/messages-logs/client_abc123?page=1&limit=20&status=delivered&fromDate=2024-12-01&toDate=2024-12-31
Headers:
  Authorization: Bearer <votre_token>
                        

Exemple cURL

                            curl -X GET "https://sms.sn/smpp/client/messages-logs/client_abc123?page=1&limit=20&status=delivered" \
  -H "Authorization: Bearer <votre_token>"
                        

Réponse

                            {
  "data": [
    {
      "id": "12345",
      "clientMessageId": "msg_20241201_001",
      "operatorMessageId": "SMPP_MSG_1234567890",
      "status": "delivered",
      "sourceAddr": "MONENTREPRISE",
      "destinationAddr": "+33612345678",
      "texte": "Bonjour, ceci est un message de test",
      "country": "FR",
      "createdAt": "2024-12-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}
                        

GET /smpp/client/messages-report

🔒 Authentification requise

Télécharge un rapport Excel (.xlsx) contenant tous vos messages avec les mêmes filtres que l'endpoint messages-logs. Le fichier est généré dynamiquement et téléchargé directement.

Query Parameters

Mêmes paramètres que /smpp/client/messages-logs/:id (sauf page et limit qui ne sont pas nécessaires pour un export complet).

Paramètre	Type	Description
recipient	string	Filtrer par numéro de destinataire
fromDate	string	Date de début (format: YYYY-MM-DD)
toDate	string	Date de fin (format: YYYY-MM-DD)
status	string	Filtrer par statut
clientMessageId	string	Rechercher par ID de message client
operatorMessageId	string	Rechercher par ID de message opérateur
texte	string	Rechercher dans le contenu des messages
sourceAddr	string	Filtrer par adresse source (expéditeur)

Exemple cURL

                            curl -X GET "https://sms.sn/smpp/client/messages-report?fromDate=2024-12-01&toDate=2024-12-31&status=delivered" \
  -H "Authorization: Bearer <votre_token>" \
  -o rapport-messages.xlsx
                        

Réponse

Le serveur retourne un fichier Excel (.xlsx) avec le nom de fichier au format : rapport-messages-{clientId}-{date}.xlsx

Le fichier contient les colonnes suivantes : ID, Client Message ID, Operator Message ID, Statut, Expéditeur, Destinataire, Message, Pays, Date de création, etc.

Informations du compte

Consultez les informations de votre compte, votre solde et votre profil.

GET /smpp/client/balance

🔒 Authentification requise

Récupère le solde actuel de votre compte SMPP. Le solde est automatiquement débité lors de l'envoi de messages.

Exemple de Requête

                            GET /smpp/client/balance
Headers:
  Authorization: Bearer <votre_token>
                        

Exemple cURL

                            curl -X GET https://sms.sn/smpp/client/balance \
  -H "Authorization: Bearer <votre_token>"
                        

Réponse

                            {
  "type": "SMS",
  "amount": 1500.50,
  "currency": "EUR"
}
                        

GET /smpp/client/profile/:clientId

🔒 Authentification requise

Récupère les informations de profil de votre compte client, incluant vos System IDs SMPP et leurs configurations.

Path Parameters

Paramètre	Type	Description
:clientId	string	Votre Client ID

Exemple de Requête

                            GET /smpp/client/profile/client_abc123
Headers:
  Authorization: Bearer <votre_token>
                        

Exemple cURL

                            curl -X GET https://sms.sn/smpp/client/profile/client_abc123 \
  -H "Authorization: Bearer <votre_token>"
                        

Réponse

                            {
  "clientId": "client_abc123",
  "name": "Mon Entreprise",
  "email": "client@example.com",
  "systemIds": [
    {
      "systemId": "mon_system_id",
      "status": "active",
      "credits": 1500.50,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
                        