HSMS API — API HSMS - Documentation
Une nouvelle documentation API interactive est disponible pour les endpoints v2. Voir la documentation API v2

API HSMS - Documentation

Obsolète

Cette documentation API est obsolète. Veuillez utiliser la nouvelle documentation interactive de l'API v2 : Voir la documentation API v2

Introduction

L'API HSMS vous permet d'envoyer des SMS, de vérifier votre solde et de suivre la livraison de vos messages depuis votre application. Toutes les requêtes utilisent le format JSON et nécessitent une authentification par token Bearer.

URL de base

https://hsms.ci/api/

Format des requêtes

Toutes les requêtes doivent être envoyées en POST avec le header Content-Type: application/json.

Format des réponses

Toutes les réponses retournent un objet JSON contenant au minimum les champs success (booléen) et message (chaîne).

{
    "success": true,
    "message": "OK",
    "data": { ... }
}

Démarrage rapide

Pour envoyer votre premier SMS via l'API, suivez ces 3 étapes :

  1. Obtenez votre token d'API — POST /api/token/
  2. Identifiez votre application — clientid + clientsecret
  3. Envoyez votre SMS — POST /api/v2/sms/send/

Authentification

L'API HSMS utilise une authentification en deux couches : un token Bearer pour identifier l'utilisateur, et des identifiants d'application (clientid/clientsecret) pour identifier l'application SMS à utiliser.

Flux d'authentification : Créez un compte → Créez une application → Obtenez un token → Utilisez le token + les identifiants de l'application dans chaque requête.

1. Obtenir un token

Envoyez vos identifiants de connexion (email et mot de passe) pour recevoir un token d'API. Ce token est persistant et peut être réutilisé pour toutes vos requêtes.

Method: POST

URL: https://hsms.ci/api/token/

Content-Type: application/json

Corps de la requête
Paramètre Type Requis Description
email string Oui Votre adresse email de connexion
password string Oui Votre mot de passe

cURL 

curl -X POST https://hsms.ci/api/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your_password"
  }'

Python 

import requests

response = requests.post("https://hsms.ci/api/token/", json={
    "email": "[email protected]",
    "password": "your_password"
})
token = response.json()["token"]

Réponse en cas de succès (HTTP 202) 

{
    "success": true,
    "message": "OK",
    "token": "your_api_token_here"
}

Réponse en cas d'erreur (HTTP 403) 

{
    "success": false,
    "message": "Invalid email or password"
}

2. Utiliser le token

Incluez le token dans le header Authorization de chaque requête API :

Authorization: Bearer your_api_token_here

3. Identifiants d'application

En plus du token Bearer, chaque requête SMS nécessite les identifiants de votre application (clientid et clientsecret). Ces identifiants sont envoyés dans le corps de la requête.

Paramètre Description
clientid Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret Clé secrète de votre application (visible dans votre tableau de bord)

Vous trouverez vos identifiants clientid et clientsecret dans la page de détails de votre application, onglet « Identifiants API ».

Envoyer un SMS (API Legacy) Legacy

Cette API est toujours fonctionnelle et supportée, mais nous recommandons d'utiliser l'API v2 pour les nouvelles intégrations. L'API v2 offre un format de réponse amélioré.

Envoi standard

Envoyez un SMS à un ou plusieurs destinataires via l'endpoint legacy.

Method: POST

URL: https://hsms.ci/api/envoi-sms

Authorization: Bearer <token>

Paramètre Type Requis Description
clientid string Oui Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret string Oui Clé secrète de votre application (visible dans votre tableau de bord)
telephone string Oui Numéro(s) de téléphone du/des destinataire(s), séparés par des virgules. Incluez l'indicatif pays (ex : 2250700000001).
message string Oui Contenu du message SMS à envoyer
unicode boolean Non Mettre à true pour les messages contenant des caractères non-latins (arabe, chinois, etc.). Par défaut : false.

Exemple — cURL

curl -X POST https://hsms.ci/api/envoi-sms \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "YOUR_CLIENT_ID",
    "clientsecret": "YOUR_CLIENT_SECRET",
    "telephone": "2250700000001",
    "message": "Hello from HSMS!"
  }'

SMS programmé

Programmez l'envoi d'un SMS à une date et heure précises.

Method: POST

URL: https://hsms.ci/api/envoi-sms/sms-programme

Paramètre Type Requis Description
clientid string Oui Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret string Oui Clé secrète de votre application (visible dans votre tableau de bord)
telephone string Oui Numéro(s) de téléphone du/des destinataire(s), séparés par des virgules. Incluez l'indicatif pays (ex : 2250700000001).
message string Oui Contenu du message SMS à envoyer
dateenvoi string Oui Date et heure d'envoi au format AAAA-MM-JJ HH:MM:SS (ex : 2026-03-15 10:00:00)

Exemple — cURL

curl -X POST https://hsms.ci/api/envoi-sms/sms-programme \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "YOUR_CLIENT_ID",
    "clientsecret": "YOUR_CLIENT_SECRET",
    "telephone": "2250700000001",
    "message": "Scheduled message",
    "dateenvoi": "2026-03-15 10:00:00"
  }'

Accusés de réception (DLR)

Les accusés de réception (Delivery Reports) vous permettent de connaître le statut de livraison de vos SMS. HSMS propose deux méthodes : le mode Push (webhook) et le mode Pull (polling).

Codes de statut SMS

Chaque SMS passe par les statuts suivants au cours de son cycle de vie :

Code Libellé Description
0 En attente Le message est en file d'attente, pas encore traité.
1 En cours d'envoi Le message est en cours de transmission vers l'opérateur.
2 Envoyé à l'opérateur Le message a été transmis à l'opérateur mobile, en attente de livraison.
3 Délivré Le message a été livré avec succès au destinataire.
4 Rejeté Le message a été rejeté par l'opérateur (numéro invalide, filtrage, etc.).
5 Non délivré Le message n'a pas pu être livré (téléphone éteint, hors réseau, délai expiré).

Mode Push (Webhook)

Configurez une URL de notification dans les paramètres de votre application. HSMS enverra automatiquement une requête POST à cette URL à chaque changement de statut de vos messages.

HSMS enverra le payload suivant à votre URL de notification :

POST https://your-server.com/your-webhook-url

{
    "ticket": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": 3,
    "status_label": "Delivered",
    "recipient": "+2250700000001"
}

Pour activer les webhooks DLR, configurez le champ « URL de notification » dans les paramètres de votre application depuis le tableau de bord.

Mode Pull (Polling)

Si vous préférez interroger activement le statut de vos messages, utilisez les endpoints de polling ci-dessous.

Interroger par ticket

Method: POST

URL: https://hsms.ci/api/envoi-sms/notifications

Paramètre Type Requis Description
clientid string Oui Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret string Oui Clé secrète de votre application (visible dans votre tableau de bord)
tickets array Oui Liste des identifiants de tickets à interroger
max integer Non Nombre maximum de résultats à retourner (par défaut : 50) 
curl -X POST https://hsms.ci/api/envoi-sms/notifications \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "YOUR_CLIENT_ID",
    "clientsecret": "YOUR_CLIENT_SECRET",
    "tickets": ["ticket-uuid-1", "ticket-uuid-2"],
    "max": 50
  }'
Récupérer toutes les notifications en attente

Récupérez toutes les notifications DLR en attente pour votre application. Les notifications retournées sont marquées comme lues.

Method: POST

URL: https://hsms.ci/api/envoi-sms/notifications-pulling

Paramètre Type Requis Description
clientid string Oui Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret string Oui Clé secrète de votre application (visible dans votre tableau de bord)
max integer Non Nombre maximum de résultats à retourner (par défaut : 50)

Cette fonctionnalité nécessite que le mode « DLR Pulling » soit activé dans les paramètres de votre application et qu'un Sender ID soit configuré. 

curl -X POST https://hsms.ci/api/envoi-sms/notifications-pulling \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "YOUR_CLIENT_ID",
    "clientsecret": "YOUR_CLIENT_SECRET",
    "max": 50
  }'

Vérifier le solde

Vérifiez le nombre de SMS disponibles sur votre application.

Method: POST

URL: https://hsms.ci/api/check-sms

Authorization: Bearer <token>

Paramètre Type Requis Description
clientid string Oui Identifiant unique de votre application (visible dans votre tableau de bord)
clientsecret string Oui Clé secrète de votre application (visible dans votre tableau de bord)

Exemple — cURL

curl -X POST https://hsms.ci/api/check-sms \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "clientid": "YOUR_CLIENT_ID",
    "clientsecret": "YOUR_CLIENT_SECRET"
  }'

Réponse en cas de succès

{
    "SMS disponibles": 1500,
    "Application": "MY_APP"
}

Référence des erreurs

L'API retourne des codes HTTP standards accompagnés d'un objet JSON détaillant l'erreur.

Codes HTTP

Code Signification
200 Succès — La requête a été traitée avec succès.
201 Créé — La ressource a été créée (envoi simple).
202 Accepté — La requête a été acceptée (token généré).
400 Requête invalide — Paramètres manquants ou invalides.
401 Non autorisé — Token invalide ou identifiants incorrects.
403 Interdit — Accès refusé (mauvais email/mot de passe).

Erreurs courantes

Erreur HTTP Cause
Identifiants manquants 400 Les champs clientid ou clientsecret ne sont pas fournis dans la requête.
Identifiants invalides 401 Le clientid ou clientsecret ne correspond à aucune application de votre compte.
Solde insuffisant 400 Votre application n'a pas assez de SMS pour envoyer le message.
Numéro invalide 400 Le numéro de téléphone fourni n'est pas valide ou ne contient pas l'indicatif pays.
Application inactive 400 L'application est désactivée. Activez-la depuis votre tableau de bord.

Format de réponse d'erreur

{
    "success": false,
    "message": "Error description",
    "errors": {
        "field_name": ["Specific validation error"]
    }
}