Developer Platform

Référence API CUTUMA

Une référence unique pour intégrer l'envoi SMS, la gestion des contacts et des campagnes sans dépendre du dashboard.

Télécharger OpenAPI JSON Explorer OpenAPI Quickstart SDK Exemples SDK JavaScript Voir les endpoints

Auth claire

Utilisez Authorization: Bearer <api-key> ou x-api-key.

Idempotence

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

Request IDs

Chaque réponse porte un X-Request-Id pour corréler logs et support.

Débit contrôlé

POST /v1/sms/send — headers X-RateLimit-* signalent le solde.

Exemple de requête · v1 Simple, explicite, traçable 
POST https://cutuma.com/api/v1/sms/send
Authorization: Bearer at_live_xxx
Idempotency-Key: 3b0d0fa7-6f8d-4d8d-95e1-8a0bf8a1f0d1
Content-Type: application/json

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

202 Accepted
{
  "success": true,
  "queued": true,
  "status": "accepted",
  "count": 1,
  "remainingQuota": 999,
  "provider": {
    "code": "cutuma",
    "messageId": "42",
    "httpStatus": 202
  }
}

L'envoi SMS API est asynchrone

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

Identifiant fournisseur — provider.messageId référence le log interne. Suivez le statut via le dashboard ou les webhooks.

Migration client — Acceptez les succès 2xx, utilisez Idempotency-Key, puis suivez le statut via reporting.

Endpoints API v1

Base URL : https://cutuma.com/api/v1 — tous les chemins ci-dessous sont relatifs à cette racine.

Explorer dans Swagger UI →

Platform

Découverte du service, santé et contrat OpenAPI.

GET Public
/

Métadonnées API, liens docs et endpoints disponibles.

GET Public
/health

Health check pour monitoring et intégrations.

GET Public
/openapi.json

Contrat OpenAPI 3.1 — JSON ou interface interactive.

Compte & usage

Quota, solde SMS et historique de consommation.

GET Bearer
/account

Profil organisation, email et quota restant.

GET Bearer
/usage

Historique d'utilisation et statistiques.

SMS

Envoi unitaire asynchrone avec idempotence.

POST Bearer
/sms/send

Accepte un SMS (202 Accepted), décrémente le quota.

Contacts

Carnet d'adresses de l'organisation.

GET Bearer
/contacts

Liste paginée des contacts.

POST Bearer
/contacts

Création d'un contact.

DELETE Bearer
/contacts?id={id}

Suppression par identifiant (query string).

Campagnes

Diffusion SMS en masse.

GET Bearer
/campaigns

Liste des campagnes et statistiques.

POST Bearer
/campaigns

Création et lancement d'une campagne.

Sender IDs

Identités d'expéditeur approuvées.

GET Bearer
/sender-ids

Liste des Sender IDs et statuts.

POST Bearer
/sender-ids

Demande d'un nouveau Sender ID.

Clés API

Gestion des clés pour l'authentification Bearer.

GET Bearer
/api-keys

Liste des clés (préfixes masqués).

POST Bearer
/api-keys

Création — le secret n'est affiché qu'une fois.

DELETE Bearer
/api-keys/{apiKeyId}

Révocation d'une clé.

Webhooks

Notifications HTTP sur les événements SMS.

GET Bearer
/webhooks

Liste des endpoints webhook configurés.

POST Bearer
/webhooks

Création + secret de signature HMAC.

DELETE Bearer
/webhooks/{webhookEndpointId}

Suppression d'un endpoint.

Fournisseur · sous-comptes

API revendeur, réservée aux comptes fournisseurs actifs : gérez vos propres clients depuis votre plateforme.

GET Bearer
/sub-accounts

Sous-comptes, soldes, consommation et montant au prix de revente.

POST Bearer
/sub-accounts

Créer un sous-compte (la référence rend l'appel idempotent).

PATCH Bearer
/sub-accounts/{id}

Suspendre, réactiver, prix de revente ou alerte de solde.

POST Bearer
/sub-accounts/{id}/transfers

Donner (allocation) ou reprendre (reclaim) des SMS — Idempotency-Key obligatoire.

GET Bearer
/sub-accounts/{id}/statement

Relevé jour par jour au prix de revente.

GET Bearer
/sub-accounts/{id}/messages

SMS du sous-compte et statuts de livraison.

POST Bearer
/sub-accounts/{id}/api-keys

Créer la clé d'envoi d'un client (secret affiché une fois).

POST Bearer
/sub-accounts/{id}/sender-ids

Demander un Sender ID pour le client final.

Authentification

Header Authorization: Bearer at_live_… ou x-api-key. Mutations : ajoutez Idempotency-Key.

Tester un endpoint →

Programme fournisseur

Devenir fournisseur CUTUMA

Revendez des SMS à vos propres clients : un sous-compte par client, des SMS transférés depuis votre solde, vos clés d’envoi et votre prix de revente. Après acceptation de votre dossier par l’administrateur CUTUMA, votre compte fournisseur reçoit un accès à l’API revendeur.

  • →Sous-comptes illimités par API
  • →Transferts de SMS idempotents
  • →Relevés au prix que vous facturez
  • →Sender IDs validés par l’administrateur
Devenir fournisseur → Guide API fournisseur

Quickstart JavaScript

Intégrez votre premier SMS en Node.js avec le SDK officiel.

Voir le guide →

Guides de démarrage

Quickstart JavaScript →

SDK Node.js, réponse 202, idempotence et webhooks.

Exemples d'intégration →

Curl et SDK pour SMS, contacts, campagnes et webhooks.

SDK JavaScript officiel →

Installation, sendSms, contrat 202 et helpers webhook.

Erreurs et retries →

Codes d'erreur, règles de replay et rôle des request IDs (OpenAPI).
quickstart — curl
# 1. Vérifier la santé de l'API
curl https://cutuma.com/api/v1/health

# 2. Consulter votre compte
curl https://cutuma.com/api/v1/account \
  -H "Authorization: Bearer at_live_VOTRE_CLE"

# 3. Envoyer un SMS
curl -X POST https://cutuma.com/api/v1/sms/send \
  -H "Authorization: Bearer at_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"to":"+243812000000","message":"Hello API","senderName":"CUTUMA"}'

Webhooks

Synchronisez l'état d'un message sans polling.

message.delivered

Marquer une livraison réussie dans votre système.

message.failed

Erreurs provider ou non-délivrance.

Guide webhooks complet →

Premiers pas

  1. 1. Créez un compte puis générez une clé API dans le dashboard.
  2. 2. Appelez GET /v1/health pour valider le contexte.
  3. 3. Envoyez un SMS via POST /v1/sms/send avec Idempotency-Key.
  4. 4. Traitez 202 Accepted comme l'acceptation plateforme.
Télécharger le contrat Créer un compte