Documentation API SMS

API REST complète pour l'envoi de SMS en temps réel et en lot avec gestion avancée des campagnes.

99.9%
Disponibilité
<200ms
Latence moyenne
50+
Pays couverts
24/7
Support

Nouveauté : Envoi en Lot Automatisé

Envoyez jusqu'à des millions de SMS avec notre nouveau système de traitement par lots. Gestion intelligente des files d'attente, surveillance en temps réel et reprise automatique en cas d'interruption.

URL de Base : https://edok-api.kingsmspro.com/api/v1/

Fonctionnalités Principales

  • Envoi SMS instantané
  • Envoi en lot jusqu'à 1M+ SMS
  • Traçage en temps réel
  • Webhooks DLR automatiques
  • Gestion multi-expéditeurs
  • Rapports détaillés
  • API RESTful
  • Support JSON/XML

Authentification

L'authentification se fait via les headers HTTP avec votre clé API et votre ID client.

Sécurité : Gardez votre clé API secrète et ne l'exposez jamais côté client.

Headers requis :

APIKEY: votre_cle_api_ici
CLIENTID: votre_id_client
Content-Type: application/json

Obtenir vos identifiants :

  1. Créez un compte sur KING SMS PRO
  2. Validez votre email
  3. Connectez-vous et allez dans la section "Développeur"
  4. Générez votre clé API

Envoi SMS Simple

Envoyez un SMS à un seul destinataire avec une réponse immédiate.

POST
/sms/send
Paramètres
Paramètre Type Requis Description
from string Requis Expéditeur (max 11 caractères)
to string Requis Numéro destinataire (format international)
message string Requis Contenu du message
type integer Requis 0 = Texte, 1 = Flash
dlr string Optionnel "yes" ou "no" pour accusé de réception
url url Optionnel URL webhook pour DLR

Exemple de requête

{
  "from": "KING SMS",
  "to": "22890443679",
  "message": "Bonjour, votre commande est prête !",
  "type": 0,
  "dlr": "yes",
  "url": "https://monsite.com/webhook/dlr"
}
200 OK Réponse succès 
{
  "messageId": "587854667",
  "from": "KING SMS",
  "to": "22890443679",
  "message": "Bonjour, votre commande est prête !",
  "route": "TG(TOGOCEL)",
  "type": 0,
  "sms_count": 1,
  "amount": 25,
  "currency": "XOF",
  "status": "ACT"
}

Envoi SMS en Lot

Fonctionnalité Avancée

Envoyez des SMS à des milliers de destinataires avec une seule requête. Le système traite automatiquement par lots de 100 pour optimiser les performances.

POST
/sms/send
Détection Automatique : Si le paramètre to contient plus de 10 numéros séparés par des virgules, le système active automatiquement le mode lot.
Paramètres
Paramètre Type Requis Description
from string Requis Expéditeur (max 11 caractères)
to string Requis Numéros séparés par des virgules
message string Requis Contenu du message (identique pour tous)
type integer Requis 0 = Texte, 1 = Flash
processing_mode string Optionnel "immediate", "background", "auto_worker"

Exemple de requête (Lot de 1000 SMS)

{
  "from": "PROMO2024",
  "to": "22990123456,22890654321,22790987654,...",
  "message": "🎉 Promotion spéciale ! -50% sur tous nos produits. Code: PROMO50",
  "type": 0,
  "processing_mode": "background"
}
200 OK Réponse lot accepté 
{
  "batch_id": "batch_675abc123def456",
  "message": "Bulk SMS sent successfully and queued for delivery",
  "total_contacts": 1000,
  "estimated_cost": 25000,
  "status": "accepted",
  "currency": "XOF",
  "delivery_info": "SMS messages are being processed and will be delivered shortly"
}

Modes de traitement

immediate

Traitement synchrone instantané (recommandé pour <100 SMS)

background

Traitement asynchrone en arrière-plan (par défaut)

auto_worker

Démarrage automatique de worker si nécessaire

Suivi des Lots SMS

Suivez en temps réel le statut et la progression de vos campagnes SMS en lot.

GET
/sms/batch/{batch_id}/status
Paramètres d'URL
Paramètre Type Description
batch_id string ID du lot retourné lors de l'envoi
200 OK Statut du lot 
{
  "batch_id": "batch_675abc123def456",
  "status": "processing",
  "sender": "PROMO2024",
  "message": "🎉 Promotion spéciale !",
  "type": 0,
  "created_at": "2024-12-02 10:30:00",
  "total_contacts": 1000,
  "sent_count": 750,
  "failed_count": 20,
  "pending_count": 200,
  "processing_count": 30,
  "actual_cost": 18750,
  "estimated_cost": 25000,
  "currency": "XOF",
  "progress_percentage": 77.0
}

Statuts possibles

Statut Description
accepted Lot accepté, en attente de démarrage
processing Traitement en cours
completed Traitement terminé
failed Échec du traitement
Lister tous vos lots
GET
/sms/batches

Récupère la liste paginée de tous vos lots SMS avec leur statut.

Détails d'un lot
GET
/sms/batch/{batch_id}/details

Obtient les détails de chaque SMS du lot (contact, statut, erreurs).

Traçage SMS

Vérifiez le statut d'un SMS spécifique grâce à son ID.

POST
/sms/trace
Paramètres
Paramètre Type Requis Description
messageId string Requis ID du message à tracer

Exemple de requête

{
  "messageId": "587854667"
}
200 OK Statut du SMS 
{
  "messageId": "587854667",
  "sender": "KING SMS",
  "destination": "22890443679",
  "route": "TG(TOGOCEL)",
  "status": "DLV",
  "delivered_at": "2024-12-02 10:32:15"
}

Consultation du Solde

Vérifiez le solde disponible sur votre compte.

GET
/account/balance

Aucun paramètre requis. Utilise l'authentification via headers.

200 OK Solde du compte 
{
  "balance": 15750.50,
  "currency": "XOF",
  "last_recharge": "2024-12-01 14:30:00",
  "low_balance_alert": 1000.00
}

Rapports SMS

Générez des rapports détaillés de vos envois SMS par période.

POST
/sms/reports
Paramètres
Paramètre Type Requis Description
date_start date Requis Date de début (YYYY-MM-DD)
date_end date Requis Date de fin (YYYY-MM-DD)
type integer Requis 1 = Plateforme, 2 = API, 3 = Tous
format string Optionnel "json", "csv", "excel"

Exemple de requête

{
  "date_start": "2024-12-01",
  "date_end": "2024-12-02",
  "type": 2,
  "format": "json"
}

Codes de Statut SMS

Référence complète des codes de statut retournés par l'API.

Statuts de Succès
Code Description
ACTMessage accepté
DLVLivré sur le mobile
DLGReçu par la passerelle
BUFEn file d'attente
IPREn cours de traitement
Statuts d'Erreur
Code Description
ERDErreur de livraison
EXPMessage expiré
BLONuméro bloqué
NSFSolde insuffisant
INVRéseau inconnu
Conseil : Utilisez les webhooks DLR pour recevoir les mises à jour de statut en temps réel plutôt que de faire du polling avec l'API de traçage.

Gestion des Erreurs

L'API utilise les codes de statut HTTP standards et retourne des messages d'erreur en JSON.

Codes de réponse HTTP

Code Description Action recommandée
200 Succès Continuer le traitement
400 Requête invalide Vérifier les paramètres
401 Non authentifié Vérifier APIKEY et CLIENTID
422 Données invalides Vérifier le format des données
429 Trop de requêtes Attendre avant de réessayer
500 Erreur serveur Réessayer plus tard

Format des erreurs

400 Bad Request Exemple d'erreur 
{
  "error": "Validation failed",
  "message": "The 'to' field is required",
  "code": "MISSING_PARAMETER",
  "details": {
    "field": "to",
    "expected": "string",
    "received": null
  }
}
Bonnes Pratiques :
  • Implémentez un système de retry avec backoff exponentiel
  • Loggez toutes les erreurs pour le debugging
  • Surveillez votre solde avant les gros envois
  • Validez les numéros de téléphone côté client