Aller au contenu principal

Référence de l'API SMS-C

← Retour à l'Index de Documentation

Référence complète pour tous les points de terminaison de l'API REST SMS-C avec des exemples de requêtes/réponses.

Table des Matières​

Aperçu de l'API​

L'API REST SMS-C fournit un accès programmatique à la soumission, au routage et aux fonctions de gestion des messages.

URL de Base​

https://api.example.com:8443/api

Port par Défaut : 8443 (configurable)
Protocole : HTTPS (TLS requis en production)

Type de Contenu​

Toutes les requêtes et réponses utilisent JSON :

Content-Type: application/json

Version de l'API​

L'API actuelle est la version 1 (implicite). Les futures versions utiliseront la version d'URL :

https://api.example.com:8443/api/v2/...

Authentification​

Certificats Clients TLS (Recommandé)​

Les déploiements en production doivent utiliser l'authentification par certificat client TLS :

curl --cert client.crt --key client.key \
  https://api.example.com:8443/api/status

Authentification par Clé API​

Authentification par clé API personnalisée via l'en-tête X-API-Key :

curl -H "X-API-Key: your_api_key_here" \
  https://api.example.com:8443/api/status

Liste Blanche d'IP​

Restreindre l'accès à l'API aux adresses IP de confiance au niveau du pare-feu.

Formats de Réponse Communes​

Réponse de Succès​

{
  "data": {
    ...
  }
}

Réponse d'Erreur​

{
  "errors": {
    "detail": "Message d'erreur décrivant ce qui s'est mal passé"
  }
}

Réponse de Liste​

{
  "data": [
    {...},
    {...}
  ]
}

Point de Terminaison de Statut​

Point de contrôle de santé pour la surveillance et les équilibreurs de charge.

Obtenir le Statut de l'API​

Requête :

GET /api/status

Réponse (200 OK) :

{
  "status": "ok",
  "application": "OmniMessage",
  "timestamp": "2025-10-30T12:34:56Z"
}

Exemple :

curl https://api.example.com:8443/api/status

Cas d'Utilisation :

  • Vérifications de santé des équilibreurs de charge
  • Surveillance de la connectivité du système
  • Vérification de la disponibilité du service

API de File d'Attente de Messages​

Points de terminaison principaux pour la soumission et la gestion des messages.

Lister les Messages​

Récupérer les messages de la file d'attente.

Requête :

GET /api/messages

En-têtes Optionnels :

  • smsc: frontend_name - Filtrer par SMSC de destination
  • include-unrouted: true|false|1|0 - Inclure les messages sans enregistrement de localisation (par défaut : false)
    • false (par défaut) : Ne retourner que les messages avec routage explicite ou enregistrement de localisation
    • true : Inclure les messages sans enregistrement de localisation (mode rétrocompatible)

Paramètres de Requête (mode liste — uniquement lorsque aucun en-tête smsc n'est envoyé) :

  • status - Filtrer par un seul statut (par défaut : tous). Un des : queued, backoff, sent, delivered, expired, dropped, auto_replied, balance_rejected, deleted
  • limit - Max de dossiers à retourner (par défaut : 100, max : 1000)
  • offset - Dossiers à ignorer pour la pagination (par défaut : 0)

Les résultats sont retournés du plus récent au plus ancien par ID de message. Le point de terminaison est paginé par défaut : sans limit, il retourne au maximum 100 dossiers, jamais l'ensemble du magasin.

Réponse (200 OK) — un tableau JSON de messages :

[
  {
    "id": 12345,
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_text": "Hello World",
    "source_smsc": "api_client",
    "dest_smsc": "uk_gateway",
    "status": "queued",
    "send_time": "2025-10-30T12:00:00Z",
    "deliver_time": null,
    "delivery_attempts": 0,
    "inserted_at": "2025-10-30T12:00:00Z"
  }
]

Exemples :

Obtenir les messages en attente pour un SMSC spécifique (uniquement avec routage explicite ou localisation) :

curl -H "smsc: uk_gateway" \
  https://api.example.com:8443/api/messages

Obtenir les messages en attente y compris les messages non routés (rétrocompatible) :

curl -H "smsc: uk_gateway" \
  -H "include-unrouted: true" \
  https://api.example.com:8443/api/messages

Obtenir tous les messages livrés :

curl "https://api.example.com:8443/api/messages?status=delivered&limit=50"

Obtenir un Message Unique​

Récupérer les détails d'un message spécifique.

Requête :

GET /api/messages/:id

Réponse (200 OK) :

{
  "data": {
    "id": 12345,
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client",
    "dest_smsc": "uk_gateway",
    "source_imsi": null,
    "dest_imsi": null,
    "message_parts": 1,
    "message_part_number": 1,
    "tp_data_coding_scheme": "00",
    "tp_user_data_header": null,
    "status": "queued",
    "send_time": "2025-10-30T12:00:00Z",
    "deliver_time": null,
    "expires": "2025-10-31T12:00:00Z",
    "deadletter": false,
    "delivery_attempts": 0,
    "deliver_after": "2025-10-30T12:00:00Z",
    "raw_data_flag": false,
    "raw_sip_flag": false,
    "raw_pdu": null,
    "inserted_at": "2025-10-30T12:00:00Z",
    "updated_at": "2025-10-30T12:00:00Z"
  }
}

Exemple :

curl https://api.example.com:8443/api/messages/12345

Soumettre un Message (Synchronisé)​

Soumettre un message et recevoir immédiatement l'ID du message.

Requête :

POST /api/messages
Content-Type: application/json

Corps :

{
  "source_msisdn": "+15551234567",
  "destination_msisdn": "+447700900000",
  "message_body": "Hello World",
  "source_smsc": "api_client"
}

Champs Optionnels :

  • dest_smsc - Remplacer la décision de routage
  • send_time - Planifier pour une livraison future (ISO 8601)
  • message_parts - Total de parties pour un message multipart
  • message_part_number - Numéro de partie (indexé à partir de 1)
  • tp_data_coding_scheme - DCS SMS (par défaut : "00")
  • source_imsi - IMSI de l'abonné source
  • dest_imsi - IMSI de l'abonné de destination

Réponse (201 Créé) :

{
  "data": {
    "id": 12345,
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client",
    "dest_smsc": "uk_gateway",
    "status": "queued",
    "send_time": "2025-10-30T12:00:00Z",
    "inserted_at": "2025-10-30T12:00:00Z"
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/messages \
  -H "Content-Type: application/json" \
  -d '{
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Hello World",
    "source_smsc": "api_client"
  }'

Performance : ~70 messages/seconde, temps de réponse moyen de 14ms

Utiliser Quand :

  • Besoin de l'ID du message immédiatement
  • Traitement de messages/seconde
  • Nécessite une confirmation immédiate

Soumettre un Message (Asynchrone)​

Soumettre un message avec un débit élevé (traitement par lots).

Requête :

POST /api/messages/create_async
Content-Type: application/json

Corps : Identique à l'endpoint synchronisé

Réponse (202 Accepté) :

{
  "data": {
    "status": "accepted",
    "message": "Message mis en file d'attente pour traitement"
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/messages/create_async \
  -H "Content-Type: application/json" \
  -d '{
    "source_msisdn": "+15551234567",
    "destination_msisdn": "+447700900000",
    "message_body": "Message de notification en masse",
    "source_smsc": "bulk_api"
  }'

Performance : ~4,650 messages/seconde, temps de réponse moyen de 0.22ms

Latence : Le message apparaît dans la base de données dans les 100ms (configurable)

Utiliser Quand :

  • Messagerie en masse à volume élevé (> 100 msg/sec)
  • Pas besoin de l'ID du message dans la réponse API
  • Le débit est plus important que la confirmation instantanée

Mettre à Jour un Message​

Mettre à jour partiellement les champs d'un message.

Requête :

PATCH /api/messages/:id
Content-Type: application/json

Corps :

{
  "dest_smsc": "alternate_gateway",
  "deliver_after": "2025-10-30T14:00:00Z"
}

Champs Modifiables :

  • dest_smsc - Changer la destination
  • deliver_after - Retarder la livraison
  • message_body - Mettre à jour le texte du message
  • status - Changer le statut

Réponse (200 OK) :

{
  "data": {
    "id": 12345,
    "dest_smsc": "alternate_gateway",
    "deliver_after": "2025-10-30T14:00:00Z",
    ...
  }
}

Exemple :

curl -X PATCH https://api.example.com:8443/api/messages/12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dest_smsc": "backup_gateway"
  }'

Marquer un Message Comme Livré​

Marquer un message comme ayant été livré avec succès.

Requête :

POST /api/messages/:id/mark_delivered
Content-Type: application/json

Corps :

{
  "dest_smsc": "uk_gateway"
}

Réponse (200 OK) :

{
  "data": {
    "id": 12345,
    "status": "delivered",
    "deliver_time": "2025-10-30T12:05:30Z",
    "dest_smsc": "uk_gateway",
    ...
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/messages/12345/mark_delivered \
  -H "Content-Type: application/json" \
  -d '{
    "dest_smsc": "uk_gateway"
  }'

Cas d'Utilisation : Appelé par les systèmes frontend après une livraison réussie

Incrémenter la Tentative de Livraison​

Enregistrer une livraison échouée : incrémente le compteur de tentatives, déplace le message vers backoff, et planifie la prochaine tentative.

Requête :

PUT /api/messages/:id

Réponse (200 OK) — le message mis à jour :

{
  "id": 12345,
  "status": "backoff",
  "delivery_attempts": 2,
  "deliver_after": "2025-10-30T12:08:00Z"
}

Backoff : exponentiel, plafonné à 30 minutes, et jamais planifié après l'expiration du message :

deliver_after = min(now + min(2^attempts, 30) minutes, expires)

Le message reste en backoff jusqu'à ce que deliver_after passe, puis redevient éligible. Il continue à réessayer toutes les ≤30 minutes jusqu'à ce que expires soit atteint, après quoi il n'est plus servi (les livraisons échouées ne sont pas mises en lettre morte).

Exemple :

curl -X PUT https://api.example.com:8443/api/messages/12345

Cas d'Utilisation : Appelé par le frontend après un échec de livraison pour planifier une nouvelle tentative

Supprimer un Message​

Supprimer un message de la file d'attente.

Requête :

DELETE /api/messages/:id

Réponse (204 Pas de Contenu)

Exemple :

curl -X DELETE https://api.example.com:8443/api/messages/12345

Avertissement : La suppression de messages les retire définitivement. Utiliser avec précaution.

API PDU SMS Brut​

Soumettre des messages SMS en tant que PDU brut (Unité de Données de Protocole) pour une compatibilité maximale avec les systèmes hérités.

Soumettre un SMS Brut (Synchronisé)​

Requête :

POST /api/messages_raw
Content-Type: application/json

Corps :

{
  "pdu": "0001000B916407007009F0000004D4F29C0E",
  "source_smsc": "legacy_system"
}

Format PDU : SMS TPDU (Transport Protocol Data Unit) encodé en hexadécimal

Réponse (201 Créé) :

{
  "data": {
    "id": 12346,
    "source_msisdn": "+447700900000",
    "destination_msisdn": "+447700900000",
    "message_body": "Test",
    "source_smsc": "legacy_system",
    "raw_pdu": "0001000B916407007009F0000004D4F29C0E",
    ...
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/messages_raw \
  -H "Content-Type: application/json" \
  -d '{
    "pdu": "0001000B916407007009F0000004D4F29C0E",
    "source_smsc": "legacy_system"
  }'

Soumettre un SMS Brut (Asynchrone)​

Requête :

POST /api/messages_raw/async
Content-Type: application/json

Corps : Identique à l'endpoint synchronisé

Réponse (202 Accepté) :

{
  "data": {
    "status": "accepted",
    "message": "PDU mis en file d'attente pour traitement"
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/messages_raw/async \
  -H "Content-Type: application/json" \
  -d '{
    "pdu": "0001000B916407007009F0000004D4F29C0E",
    "source_smsc": "legacy_gateway"
  }'

Gestion des PDU​

Le système effectue automatiquement :

  1. Décode le PDU en utilisant les normes SMS (3GPP TS 23.040)
  2. Extrait les numéros de téléphone, le texte du message, DCS
  3. Détecte les rapports de livraison (CP-ACK, RP-ACK, etc.)
  4. Effectue une recherche IMSI vers MSISDN si nécessaire
  5. Applique les règles de routage
  6. Stocke le PDU original pour référence

Détection des Rapports de Livraison :

  • CP-ACK, CP-ERROR - Accusés de réception du protocole de connexion
  • RP-ACK, RP-ERROR, RP-SMMA - Réponses du protocole de relais
  • Les rapports de livraison sont enregistrés mais ne sont pas stockés en tant que messages

API de Gestion de Localisation​

Gérer les informations de localisation des abonnés pour la livraison de messages terminés sur mobile.

Lister les Localisations​

Requête :

GET /api/locations

Réponse (200 OK) :

{
  "data": [
    {
      "id": 1,
      "msisdn": "+15551234567",
      "imsi": "001001000000001",
      "location": "msc1.region1.example.com",
      "ran_location": "cell_tower_12345",
      "imei": "123456789012345",
      "ims_capable": true,
      "csfb": false,
      "registered": true,
      "expires": "2025-10-30T13:00:00Z",
      "user_agent": "Samsung Galaxy",
      "inserted_at": "2025-10-30T12:00:00Z",
      "updated_at": "2025-10-30T12:00:00Z"
    }
  ]
}

Exemple :

curl https://api.example.com:8443/api/locations

Obtenir une Localisation​

Requête :

GET /api/locations/:id

Réponse (200 OK) :

{
  "data": {
    "id": 1,
    "msisdn": "+15551234567",
    "imsi": "001001000000001",
    ...
  }
}

Exemple :

curl https://api.example.com:8443/api/locations/1

Créer/Mettre à Jour une Localisation​

Crée une nouvelle localisation ou met à jour une existante en fonction de l'IMSI (identifiant unique).

Requête :

POST /api/locations
Content-Type: application/json

Corps :

{
  "msisdn": "+15551234567",
  "imsi": "001001000000001",
  "location": "msc1.region1.example.com",
  "ran_location": "cell_tower_12345",
  "imei": "123456789012345",
  "ims_capable": true,
  "csfb": false,
  "registered": true,
  "expires": "2025-10-30T13:00:00Z",
  "user_agent": "Samsung Galaxy"
}

Champs Requis :

  • imsi - Identifiant unique de l'abonné
  • msisdn - Numéro de téléphone

Champs Optionnels :

  • location - Adresse MSC/VLR
  • ran_location - ID de la tour cellulaire/secteur
  • imei - Identifiant de l'appareil
  • ims_capable - Capacité VoLTE IMS
  • csfb - Indicateur de retour à circuit commuté
  • registered - Actuellement enregistré
  • expires - Expiration de l'enregistrement
  • user_agent - Modèle/info de l'appareil

Réponse (201 Créé ou 200 OK) :

{
  "data": {
    "id": 1,
    "msisdn": "+15551234567",
    ...
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/locations \
  -H "Content-Type: application/json" \
  -d '{
    "msisdn": "+15551234567",
    "imsi": "001001000000001",
    "location": "msc1.region1.example.com",
    "ims_capable": true,
    "registered": true
  }'

Cas d'Utilisation : Appelé par les systèmes de gestion de mobilité (HSS, MME, etc.) lorsque l'abonné s'enregistre

Mettre à Jour une Localisation​

Requête :

PATCH /api/locations/:id
Content-Type: application/json

Corps : Mise à jour partielle avec n'importe quel champ de localisation

Réponse (200 OK) :

{
  "data": {
    "id": 1,
    ...
  }
}

Exemple :

curl -X PATCH https://api.example.com:8443/api/locations/1 \
  -H "Content-Type: application/json" \
  -d '{
    "location": "msc2.region2.example.com",
    "ran_location": "cell_tower_67890"
  }'

Supprimer une Localisation​

Requête :

DELETE /api/locations/:id

Réponse (204 Pas de Contenu)

Exemple :

curl -X DELETE https://api.example.com:8443/api/locations/1

Cas d'Utilisation : Appelé lorsque l'abonné se désinscrit ou expire

API d'Inscription Frontend​

Suivre et gérer les connexions SMSC frontend.

Lister Tous les Frontends​

Requête :

GET /api/frontends

Réponse (200 OK) :

{
  "data": [
    {
      "id": 1,
      "frontend_name": "uk_gateway_1",
      "frontend_type": "smpp",
      "ip_address": "10.0.1.50",
      "hostname": "gateway1.uk.example.com",
      "uptime_seconds": 86400,
      "configuration": {
        "max_throughput": 1000,
        "bind_type": "transceiver"
      },
      "status": "active",
      "expires_at": "2025-10-30T12:02:00Z",
      "last_seen_at": "2025-10-30T12:00:30Z",
      "inserted_at": "2025-10-29T12:00:00Z",
      "updated_at": "2025-10-30T12:00:30Z"
    }
  ]
}

Exemple :

curl https://api.example.com:8443/api/frontends

Lister Uniquement les Frontends Actifs​

Requête :

GET /api/frontends/active

Réponse (200 OK) : Même format, uniquement les frontends actifs

Exemple :

curl https://api.example.com:8443/api/frontends/active

Cas d'Utilisation : Obtenir la liste des destinations disponibles pour le routage

Obtenir des Statistiques sur les Frontends​

Requête :

GET /api/frontends/stats

Réponse (200 OK) :

{
  "data": {
    "active_count": 5,
    "expired_count": 2,
    "unique_frontends": 7,
    "total_registrations": 1523
  }
}

Exemple :

curl https://api.example.com:8443/api/frontends/stats

Obtenir l'Histoire des Frontends​

Requête :

GET /api/frontends/history/:name

Réponse (200 OK) :

{
  "data": [
    {
      "id": 1,
      "frontend_name": "uk_gateway_1",
      "status": "active",
      "inserted_at": "2025-10-30T12:00:00Z",
      ...
    },
    {
      "id": 2,
      "frontend_name": "uk_gateway_1",
      "status": "expired",
      "inserted_at": "2025-10-29T12:00:00Z",
      ...
    }
  ]
}

Exemple :

curl https://api.example.com:8443/api/frontends/history/uk_gateway_1

Enregistrer un Frontend​

Enregistrer ou mettre à jour la connexion frontend.

Requête :

POST /api/frontends/register
Content-Type: application/json

Corps :

{
  "frontend_name": "uk_gateway_1",
  "frontend_type": "smpp",
  "ip_address": "10.0.1.50",
  "hostname": "gateway1.uk.example.com",
  "uptime_seconds": 86400,
  "configuration": {
    "max_throughput": 1000,
    "bind_type": "transceiver",
    "system_id": "gateway1"
  }
}

Champs Requis :

  • frontend_name - Identifiant unique pour le frontend
  • frontend_type - Type : smpp, sip, http, etc.

Champs Optionnels :

  • ip_address - IP du frontend
  • hostname - Nom d'hôte du frontend
  • uptime_seconds - Temps de fonctionnement depuis le démarrage
  • configuration - Objet de configuration personnalisé

Réponse (201 Créé) :

{
  "data": {
    "id": 1,
    "frontend_name": "uk_gateway_1",
    "status": "active",
    "expires_at": "2025-10-30T12:01:30Z",
    ...
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/frontends/register \
  -H "Content-Type: application/json" \
  -d '{
    "frontend_name": "uk_gateway_1",
    "frontend_type": "smpp",
    "ip_address": "10.0.1.50",
    "hostname": "gateway1.uk.example.com"
  }'

Délai d'Inscription : 90 secondes (les frontends doivent se réinscrire toutes les 60-90 secondes)

Cas d'Utilisation : Appelé périodiquement par les systèmes frontend pour maintenir le statut actif

API de Campagnes​

Messagerie en masse : téléchargez une liste de destinataires nommée, puis exécutez une campagne limitée par le taux contre celle-ci. Voir le guide de Messagerie en Masse / Campagnes pour les concepts (filtre d'audience, taux de goutte, cycle de vie, statistiques).

Listes de Destinataires​

Créer une Liste​

Requête :

POST /api/campaign_lists
Content-Type: application/json

Chaque destinataire peut porter jusqu'à quatre variables de modèle (var1..var4).

Corps — fournir les destinataires sous forme de tableau JSON, de chaîne CSV brute, ou les deux. Les destinataires JSON peuvent être des chaînes MSISDN simples ou des objets avec var1..var4 :

{
  "name": "Clients VIP",
  "description": "Abonnés de grande valeur",
  "recipients": [
    { "msisdn": "12025550101", "var1": "Alice", "var2": "Gold" },
    "12025550102"
  ]
}

Pour CSV, une ligne d'en-tête nommant une colonne msisdn / destination_msisdn / number / phone sélectionne la colonne MSISDN (sinon, la première colonne est utilisée) ; les colonnes restantes deviennent var1..var4 dans l'ordre des colonnes :

{ "name": "Importé", "csv": "msisdn,first,plan\n12025550101,Alice,Gold\n12025550102,Bob,Silver\n" }

Réponse (201 Créé) :

{ "id": 1, "name": "Clients VIP", "recipient_count": 2 }

Lister / Obtenir / Ajouter / Supprimer des Listes​

GET    /api/campaign_lists           # toutes les listes
GET    /api/campaign_lists/:id       # une liste, inclut "recipients": [{msisdn, variables}, ...]
PATCH  /api/campaign_lists/:id       # ajouter des destinataires ({"recipients": [...]} et/ou {"csv": "..."})
DELETE /api/campaign_lists/:id       # supprimer la liste et ses destinataires

Campagnes​

Créer une Campagne​

Requête :

POST /api/campaigns
Content-Type: application/json

Corps :

{
  "name": "Avis de maintenance",
  "message": "Maintenance prévue ce soir 02:00-03:00.",
  "source_msisdn": "12345",
  "source_smsc": "IMS_SMSC",
  "list_id": 1,
  "audience": "active_only",
  "drip_tps": 50
}

Champs :

  • name, message, source_msisdn, source_smsc — requis
  • list_id — liste de destinataires. Omettre pour cibler TOUS les abonnés actuellement actifs (enregistrés).
  • audience — active_only (par défaut) ou all. Ignoré lorsque list_id est omis.
  • drip_tps — messages soumis dans la file d'attente par seconde (par défaut à partir de la configuration).
  • validity_hours — période de validité du message en heures ; définit l'expires de chaque message (par défaut à partir de la configuration).
  • deliver_after — heure ISO8601 optionnelle pour maintenir les messages jusqu'à avant la livraison (envoi programmé).

Réponse (201 Créé) : la campagne dans l'état draft, incluant un bloc stats en direct.

Contrôler une Campagne (démarrer / mettre en pause / reprendre / annuler)​

Requête :

POST /api/campaigns/control
Content-Type: application/json

Corps :

{ "campaign_id": 7, "action": "start" }

action est l'un de start, pause, resume, cancel. Retourne la campagne mise à jour (200), 404 si non trouvée, ou 422 si l'action est invalide pour l'état actuel.

Lister / Obtenir des Campagnes​

GET /api/campaigns       # toutes les campagnes (les plus récentes en premier)
GET /api/campaigns/:id    # une campagne, incluant des statistiques en direct

Réponse (GET /api/campaigns/:id) :

{
  "id": 7,
  "name": "Avis de maintenance",
  "list_id": 1,
  "audience": "active_only",
  "status": "running",
  "drip_tps": 50,
  "total_targets": 1000,
  "stats": {
    "total": 1000, "pending": 600, "queued": 300,
    "delivered": 90, "failed": 10, "skipped_inactive": 0,
    "dispatched": 400, "progress_percent": 40, "delivery_percent": 22
  }
}

Supprimer (Arrêter) une Campagne​

DELETE /api/campaigns/:id

La suppression arrête la campagne (annule la livraison) mais garde l'enregistrement afin que son historique et ses statistiques restent visibles ; elle retourne la campagne annulée (200). L'enregistrement est purgé automatiquement une fois qu'il dépasse le TTL de conservation.

Résultats par Destinataire​

GET /api/campaign_targets/:id              # :id est l'ID de la campagne
GET /api/campaign_targets/:id?state=failed # filtrer par état cible

Retourne une entrée par destinataire avec son state (pending / queued / delivered / failed / skipped_inactive), les message_ids soumis, et les compteurs de parties.

API de Journalisation d'Événements​

Suivre les événements du cycle de vie des messages.

Obtenir les Événements de Message​

Requête :

GET /api/events/:message_id

Réponse (200 OK) :

{
  "data": [
    {
      "event_epoch": 1698672000,
      "name": "message_inserted",
      "description": "Message inséré dans la file d'attente",
      "event_source": "node1@server.example.com"
    },
    {
      "event_epoch": 1698672001,
      "name": "message_routed",
      "description": "Routé vers uk_gateway via route_id=42",
      "event_source": "node1@server.example.com"
    },
    {
      "event_epoch": 1698672005,
      "name": "message_delivered",
      "description": "Livré avec succès",
      "event_source": "node2@server.example.com"
    }
  ]
}

Exemple :

curl https://api.example.com:8443/api/events/12345

Types d'Événements :

  • message_inserted - Message créé
  • message_routed - Décision de routage prise
  • message_delivered - Livraison réussie
  • message_failed - Livraison échouée
  • message_dropped - Écarté par la route
  • auto_reply_sent - Réponse automatique déclenchée
  • number_translated - Transformation de numéro appliquée
  • routing_failed - Aucune route trouvée
  • charging_failed - Erreur de facturation

Enregistrer un Événement​

Requête :

POST /api/events
Content-Type: application/json

Corps :

{
  "message_id": 12345,
  "name": "custom_event",
  "description": "Description de l'événement personnalisé",
  "event_source": "external_system"
}

Réponse (201 Créé) :

{
  "data": {
    "message_id": 12345,
    "name": "custom_event",
    "description": "Description de l'événement personnalisé",
    "event_source": "external_system",
    "event_epoch": 1698672010
  }
}

Exemple :

curl -X POST https://api.example.com:8443/api/events \
  -H "Content-Type: application/json" \
  -d '{
    "message_id": 12345,
    "name": "external_delivery_confirmed",
    "description": "Confirmé par le système en aval"
  }'

Conservation des Événements : 7 jours (configurable)

API de Messages MMS​

Gérer les messages de Service de Messagerie Multimédia (MMS).

Lister les Messages MMS​

Requête :

GET /api/mms_messages

Réponse (200 OK) : Similaire aux messages SMS avec des champs MMS supplémentaires

Créer un Message MMS​

Requête :

POST /api/mms_messages
Content-Type: application/json

Corps :

{
  "source_msisdn": "+15551234567",
  "destination_msisdn": "+447700900000",
  "subject": "Photo",
  "content_type": "image/jpeg",
  "content_location": "https://cdn.example.com/media/12345.jpg",
  "message_size": 524288
}

Réponse (201 Créé) : Objet complet du message MMS

API d'Événements SS7​

Suivre les événements de signalisation SS7.

Lister les Événements SS7​

Requête :

GET /api/ss7_events

Réponse (200 OK) :

{
  "data": [
    {
      "id": 1,
      "event_type": "MAP_UPDATE_LOCATION",
      "imsi": "001001000000001",
      "msisdn": "+15551234567",
      "timestamp": "2025-10-30T12:00:00Z",
      ...
    }
  ]
}

Créer un Événement SS7​

Requête :

POST /api/ss7_events
Content-Type: application/json

Corps :

{
  "event_type": "MAP_UPDATE_LOCATION",
  "imsi": "001001000000001",
  "msisdn": "+15551234567"
}

Réponse (201 Créé) : Objet complet de l'événement

Codes d'Erreur​

Codes de Statut HTTP​

CodeSignificationDescription
200OKRequête réussie
201CrééRessource créée avec succès
202AcceptéRequête acceptée pour traitement
204Pas de ContenuSuppression réussie
400Mauvaise RequêteFormat de requête invalide
401Non AutoriséAuthentification requise
403InterditPermissions insuffisantes
404Non TrouvéLa ressource n'existe pas
422Entité Non TraitableErreurs de validation
429Trop de RequêtesLimite de taux dépassée
500Erreur Interne du ServeurErreur du serveur
503Service IndisponibleTemporairement indisponible

Format de Réponse d'Erreur​

{
  "errors": {
    "detail": "Échec de la validation : destination_msisdn est requis"
  }
}

Messages d'Erreur Courants​

ErreurCauseSolution
"destination_msisdn est requis"Champ requis manquantInclure destination_msisdn dans la requête
"Format de numéro de téléphone invalide"Numéro mal forméUtiliser le format E.164 : +15551234567
"Message trop long"Dépasse la limite de tailleDiviser en plusieurs parties
"Aucune route trouvée"Échec de routageVérifier la configuration de routage
"Échec de facturation"Erreur OCSVérifier la connectivité du système de facturation
"Message non trouvé"ID de message invalideVérifier que l'ID existe
"Frontend non enregistré"SMSC inconnuEnregistrer le frontend d'abord

Limitation de Taux​

Limites par Défaut​

Point de TerminaisonLimiteFenêtre
POST /api/messages100 req/secPar IP
POST /api/messages/create_async1000 req/secPar IP
POST /api/messages_raw100 req/secPar IP
GET /api/*1000 req/secPar IP

En-têtes de Limitation de Taux​

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1698672060

Limite de Taux Dépassée​

Réponse (429 Trop de Requêtes) :

{
  "errors": {
    "detail": "Limite de taux dépassée. Réessayez après 5 secondes."
  }
}

Meilleures Pratiques​

Soumission de Messages​

  1. Utiliser Async pour le Bulk : Utiliser /create_async pour > 100 msg/sec
  2. Inclure source_smsc : Identifier toujours votre système
  3. Valider les Numéros : Utiliser le format E.164 (+code pays)
  4. Gérer les Erreurs : Implémenter une logique de réessai pour les erreurs 5xx
  5. Vérifier le Routage : Tester les routes avant la soumission en masse

Intégration Frontend​

  1. S'inscrire Régulièrement : Se réinscrire toutes les 60 secondes
  2. Interroger pour les Messages : Interroger avec l'en-tête smsc pour vos messages
  3. Utiliser include-unrouted Judicieusement : Par défaut, seuls les messages avec routage explicite ou enregistrement de localisation sont retournés. Définir include-unrouted: true uniquement si vous avez besoin d'un comportement rétrocompatible pour recevoir tous les messages non routés
  4. Marquer Comme Livré : Toujours appeler mark_delivered après succès
  5. Incrémenter en Cas d'Échec : Utiliser l'endpoint PUT pour la logique de réessai
  6. Surveiller les Événements : Vérifier le journal des événements pour les problèmes de livraison

Performance​

  1. Mise en Cache des Connexions : Réutiliser les connexions HTTP
  2. Requêtes par Lots : Regrouper plusieurs messages par requête
  3. Traitement Parallèle : Effectuer des appels API concurrents
  4. Surveiller les Métriques : Regarder Prometheus pour les goulets d'étranglement
  5. Définir des Délais : Utiliser un délai de 30 secondes pour les appels API

Sécurité​

  1. Utiliser TLS : Toujours utiliser HTTPS en production
  2. Valider les Certificats : Ne pas ignorer la validation des certificats
  3. Faire Pivoter les Clés API : Changer régulièrement les clés
  4. Liste Blanche d'IP : Restreindre aux sources connues
  5. Journaliser l'Activité API : Surveiller les modèles suspects

Gestion des Erreurs​

  1. Réessayer les Erreurs 5xx : Les erreurs du serveur sont généralement temporaires
  2. Ne Pas Réessayer les 4xx : Les erreurs du client nécessitent des corrections de code
  3. Backoff Exponentiel : Attendre plus longtemps entre les réessais
  4. Disjoncteur : Arrêter après des échecs répétés
  5. Alerte sur les Modèles : Surveiller les taux d'erreur

Exemple d'Intégration (Python)​

import requests
import time

class SMSCClient:
    def __init__(self, base_url, api_key=None):
        self.base_url = base_url
        self.session = requests.Session()
        if api_key:
            self.session.headers.update({"X-API-Key": api_key})

    def submit_message(self, from_num, to_num, text, async_mode=False):
        endpoint = "/messages/create_async" if async_mode else "/messages"
        url = f"{self.base_url}{endpoint}"

        payload = {
            "source_msisdn": from_num,
            "destination_msisdn": to_num,
            "message_body": text,
            "source_smsc": "python_client"
        }

        try:
            response = self.session.post(url, json=payload, timeout=30)
            response.raise_for_status()
            return response.json()["data"]
        except requests.exceptions.RequestException as e:
            print(f"Erreur API : {e}")
            return None

    def get_pending_messages(self, smsc_name, include_unrouted=False):
        url = f"{self.base_url}/messages"
        headers = {"smsc": smsc_name}

        # Inclure les messages non routés si demandé (mode rétrocompatible)
        if include_unrouted:
            headers["include-unrouted"] = "true"

        try:
            response = self.session.get(url, headers=headers, timeout=30)
            response.raise_for_status()
            return response.json()["data"]
        except requests.exceptions.RequestException as e:
            print(f"Erreur API : {e}")
            return []

    def mark_delivered(self, message_id, smsc_name):
        url = f"{self.base_url}/messages/{message_id}/mark_delivered"
        payload = {"dest_smsc": smsc_name}

        try:
            response = self.session.post(url, json=payload, timeout=30)
            response.raise_for_status()
            return True
        except requests.exceptions.RequestException as e:
            print(f"Erreur API : {e}")
            return False

# Utilisation
client = SMSCClient("https://api.example.com:8443/api", api_key="your_key")

# Soumettre un message unique
result = client.submit_message("+15551234567", "+447700900000", "Hello")
print(f"ID du message : {result['id']}")

# Soumettre des messages en masse (asynchrone)
for i in range(1000):
    client.submit_message("+15551234567", f"+44770090{i:04d}", f"Bulk {i}", async_mode=True)

# Boucle de sondage frontend
while True:
    # Obtenir des messages avec routage explicite ou enregistrement de localisation
    messages = client.get_pending_messages("my_gateway")

    # Ou utiliser include_unrouted=True pour un comportement rétrocompatible
    # messages = client.get_pending_messages("my_gateway", include_unrouted=True)

    for msg in messages:
        # Livrer le message via votre protocole
        success = deliver_via_smpp(msg)

        if success:
            client.mark_delivered(msg["id"], "my_gateway")
        else:
            # Incrémenter pour réessayer
            requests.put(f"{client.base_url}/messages/{msg['id']}")

    time.sleep(5)  # Sonde toutes les 5 secondes

Journal des Changements de l'API​

Version 1 (Actuelle)​

  • Version initiale
  • CRUD de la file d'attente de messages
  • Soumission de PDU brut
  • Gestion de la localisation
  • Inscription frontend
  • Journalisation des événements

Fonctionnalités Prévues​

  • Soumission de messages par lots (une seule requête, plusieurs messages)
  • Modèles de messages
  • API de livraison programmée
  • Webhooks en temps réel pour les événements
  • Point de terminaison API GraphQL
  • Authentification OAuth2

Pour des questions ou des problèmes avec l'API, consultez le Guide de Dépannage ou contactez le support.

Dernière mise à jour le