Référence API

Endpoints, authentification, idempotence, limites et webhooks.

Authentification et en-têtes

Base URL : https://api.coussema.com. Utilisez une clé API limitée aux droits requis, conservée côté serveur. En-tête : Authorization: Bearer <api-key> ou x-api-key.

Utilisez Idempotency-Key avec le même payload pour les retries de mutation.

Envoi SMS

POST /v1/sms/send est asynchrone.

La réponse 202 Accepted confirme la validation, la persistance et la mise en file.
Le worker traite l’envoi, les retries et la réconciliation DLR.
Conservez message.id; provider.messageId reste null sur cette surface publique, acceptez les succès 2xx et suivez la livraison par webhook ou reporting.

http

POST /v1/sms/send
Authorization: Bearer csm_live_xxxxxxxxxxxx_xxx
Idempotency-Key: 3b0d0fa7-6f8d-4d8d-95e1-8a0bf8a1f0d1

{
  "to": "+243810000000",
  "message": "Votre code est 482019",
  "senderName": "COUSSEMA"
}

202 Accepted
{
  "success": true,
  "queued": true,
  "status": "accepted",
  "count": 1,
  "remainingQuota": 999,
  "message": {
    "id": "11111111-1111-4111-8111-111111111111",
    "clientReference": null
  },
  "provider": {
    "code": "coussema",
    "messageId": null,
    "httpStatus": 202
  }
}

Endpoints

Méthode	Route	Description
GET	/v1	Index public, état du service et liens de référence.
GET	/v1/health	Contrôle de santé pour intégrations et monitoring.
GET	/v1/openapi.json	Contrat OpenAPI 3.1 généré depuis les schémas partagés.
GET	/v1/account	Résumé commercial de l’organisation authentifiée, quota inclus.
GET	/v1/usage	Ledger d’usage et d’ajustements quota, paginé par curseur.
POST	/v1/sms/send	Acceptation asynchrone d’un SMS unitaire avec clé API et idempotence ; avec `whatsappFirst`, le modèle WhatsApp part d’abord et le SMS seulement si le numéro n’a pas WhatsApp (voir API WhatsApp, « Multicanal par API »).
GET / POST	/v1/contacts	Liste et création de contacts pour l’organisation authentifiée.
DELETE	/v1/contacts?id={contactId}	Suppression d’un contact par identifiant UUID.
GET / POST	/v1/api-keys	Liste et création des clés API clientes.
DELETE	/v1/api-keys/{apiKeyId}	Révocation d’une clé API par identifiant UUID.
GET / POST	/v1/campaigns	Campagnes immédiates ou planifiées sur le runtime partagé.
GET / POST	/v1/webhooks	Liste et création des endpoints webhook sortants.
DELETE	/v1/webhooks/{webhookEndpointId}	Désactivation d’un endpoint webhook existant.

Limites et erreurs

Chaque réponse porte un x-request-id. L’endpoint SMS accepte jusqu’à 10000 requêtes par fenêtre ; les headers X-RateLimit-* indiquent le solde. Ce plafond concerne les requêtes API, pas le nombre de destinataires groupés ensuite côté worker/provider.

Erreurs APIWebhooks

← Introduction Démarrage rapide →