Developer Platform

Référence API Coussema

Une référence unique pour intégrer l’envoi SMS, les webhooks et la gestion d’organisation sans dépendre du dashboard.

Télécharger OpenAPI JSONQuickstart RESTVoir les endpoints

Auth claire

Utilisez une clé API avec les droits minimaux requis, puis envoyez-la via `Authorization: Bearer <api-key>` ou `x-api-key`.

Idempotence

Réutilisez `Idempotency-Key` avec le même payload pour identifier un retry de mutation.

Request IDs

Chaque réponse porte un `x-request-id` pour corréler logs, erreurs et support.

Débit contrôlé

`POST /v1/sms/send` autorise jusqu’à `10000` requêtes par fenêtre; les headers `X-RateLimit-*` signalent le solde.

Exemple de requête

Simple, explicite, traçable

v1
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
  }
}
OpenAPI JSONopenapi/coussema-public-api.json
Spec live/v1/openapi.json sur l’hôte API
Mise à jour · 18 juin 2026

L’envoi SMS API est asynchrone et rate-limité par usage

Cette note ne remplace pas l’historique de l’API: elle documente le comportement courant de `POST /v1/sms/send` et la règle de migration pour les clients qui validaient uniquement un `200 OK` ou un identifiant fournisseur immédiat. Le plafond courant du endpoint SMS est `10000` requêtes par fenêtre de rate limit.

Succès canonique

`202 Accepted` signifie que Coussema a validé la requête, persisté le message et l’a placé dans la file d’envoi.

Dispatch différé

L’envoi fournisseur, les retries et la réconciliation DLR sont exécutés par le worker après la réponse HTTP.

Référence Coussema

`message.id` est la référence durable de l’envoi. `provider.messageId` reste toujours `null` sur cette surface publique.

Migration client

Les intégrations doivent accepter les succès `2xx`, utiliser `Idempotency-Key`, puis suivre le statut via webhooks ou reporting.

Limite API SMS

`POST /v1/sms/send` est plafonné par défaut à `10000` requêtes par fenêtre de rate limit. Ce plafond concerne les requêtes API, pas le nombre de destinataires groupés ensuite côté worker/provider.

Ce que couvre l’API

Les endpoints publics sont stables, versionnés en `/v1`, et partagent les mêmes règles entre le dashboard et les intégrations directes.

GET/v1Index public, état du service et liens de référence.
GET/v1/healthContrôle de santé pour intégrations et monitoring.
GET/v1/openapi.jsonContrat OpenAPI 3.1 généré depuis les schémas partagés.
GET/v1/accountRésumé commercial de l’organisation authentifiée, quota inclus.
GET/v1/usageLedger d’usage et d’ajustements quota, paginé par curseur.
POST/v1/sms/sendAcceptation asynchrone d’un SMS unitaire avec clé API et idempotence.
POST/v1/whatsapp/messagesEnvoi WhatsApp template ou réponse texte dans la fenêtre de service.
GET/v1/whatsapp/templatesTemplates WhatsApp paginés et filtrables pour l’organisation authentifiée.
GET/v1/whatsapp/conversationsConversations WhatsApp paginées avec statut et destinataire.
GET/v1/whatsapp/messagesHistorique WhatsApp customer-safe sans données provider internes.
GET / POST/v1/contactsListe 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-keysListe 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/campaignsCampagnes immédiates ou planifiées sur le runtime partagé.
GET / POST/v1/webhooksListe et création des endpoints webhook sortants.
DELETE/v1/webhooks/{webhookEndpointId}Désactivation d’un endpoint webhook existant.

Guides de démarrage

Les guides ci-dessous servent de point d’entrée opérationnel. Ils suivent les vrais champs, les vrais headers et les vraies réponses de l’API publique.

Quickstart JavaScript
/docs/api/quickstart

Un guide Node.js pour envoyer un premier SMS, gérer l’idempotence et lire les réponses réelles.

API WhatsApp
/docs/api/whatsapp

Templates approuvés, conversations, messages et SDK pour Coussema WhatsApp.

Guide webhooks
/docs/api/webhooks

Créer un endpoint, vérifier la signature et consommer les événements `message.delivered` / `message.failed`.

Erreurs et retries
/docs/api/errors

Tous les codes d’erreur utiles, les règles de replay et le rôle des request IDs.

Exemples prêts à brancher
/docs/api/examples

Curl et JavaScript pour SMS, contacts, campagnes et webhooks sur le runtime public.

Guide PHP
/docs/sdk/php

Guzzle, cURL natif et Laravel controller pour brancher l’API Coussema côté serveur.

Webhooks

Les événements sortants vous permettent de synchroniser l’état d’un message dans votre système sans polling.

  • message.delivered pour marquer une livraison réussie.
  • message.failed pour les erreurs provider ou la non-délivrance.
  • Chaque callback transporte un identifiant d’événement et un request traceable.

Premiers pas

Trois étapes pour démarrer sans ambiguïté.

  1. Créez une organisation puis générez une clé API avec le profil « Envoi SMS uniquement » dans le dashboard.
  2. Appelez `GET /v1` ou `GET /v1/health` pour valider le contexte et les headers.
  3. Envoyez un premier SMS via `POST /v1/sms/send` avec `Idempotency-Key`, puis traitez `202 Accepted` comme l’acceptation plateforme.
  4. Lisez les webhooks `message.delivered` pour synchroniser vos statuts métier.
Télécharger le contratCréer un compte