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 JSON Quickstart SDK Voir les endpoints

Auth claire

Utilisez `Authorization: Bearer <api-key>` ou `x-api-key` pour authentifier chaque requête.

Idempotence

Ajoutez `Idempotency-Key` sur les mutations critiques pour rejouer sans doublons.

Request IDs

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

Débit contrôlé

Les limites apparaissent dans `X-RateLimit-*` et les réponses `429` signalent le retry.

Exemple de requête

Simple, explicite, traçable

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

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

200 OK
{
  "success": true,
  "count": 1,
  "remainingQuota": 999,
  "provider": {
    "code": "coussema",
    "messageId": "provider-msg-123",
    "httpStatus": 200
  }
}

OpenAPI JSONopenapi/coussema-public-api.json

Spec live/v1/openapi.json sur l’hôte API

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/sendEnvoi SMS unitaire avec clé API et idempotence.

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.

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.

SDK JavaScript Changelog produit

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é.

Créez une organisation puis générez une clé API dans le dashboard.
Appelez `GET /v1` ou `GET /v1/health` pour valider le contexte et les headers.
Envoyez un premier SMS via `POST /v1/sms/send` avec `Idempotency-Key`.
Lisez les webhooks `message.delivered` pour synchroniser vos statuts métier.

Télécharger le contrat Créer un compte