Retour aux docs API
Integration cookbook

Exemples prêts à brancher

Curl pour le diagnostic rapide, SDK JavaScript pour un backend Node propre. Les exemples suivent les routes réellement exposées par la plateforme publique.

Voir le SDK JavaScript Gérer les erreurs
JavaScript SDK

Exemple Node.js

examples.mjs Télécharger le SDK 
import crypto from 'node:crypto';
import { CutumaClient } from './cutuma-client.mjs';

const client = new CutumaClient({
  baseUrl: process.env.CUTUMA_BASE_URL ?? 'https://cutuma.com/api/v1',
  apiKey: process.env.CUTUMA_API_KEY ?? '',
});

const sms = await client.sendSms(
  {
    to: '+243810000000',
    message: 'Bonjour depuis CUTUMA.',
    senderName: 'CUTUMA',
  },
  {
    idempotencyKey: crypto.randomUUID(),
    requestId: 'docs-example-001',
  }
);

const contacts = await client.listContacts({ limit: 20 });

console.log({
  accepted: sms.data.queued === true && sms.data.status === 'accepted',
  providerMessageId: sms.data.provider.messageId,
  contacts: contacts.data.data.length,
});

Envoyer un SMS

Mutation idempotente minimale avec corrélation explicite. La réponse 202 Accepted confirme la mise en file.

curl -X POST https://cutuma.com/api/v1/sms/send \
  -H 'Authorization: Bearer at_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7228b5c7-cb1d-43c0-8d68-2e9f68a5fba5' \
  -H 'X-Request-Id: send-001' \
  -d '{
    "to": "+243810000000",
    "message": "Votre code est 482019",
    "senderName": "CUTUMA",
    "clientReference": "order-482019"
  }'

Réponse attendue

HTTP/1.1 202 Accepted
Content-Type: application/json

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

Créer un contact

Le contact rejoint immédiatement le runtime partagé du dashboard et des campagnes.

curl -X POST https://cutuma.com/api/v1/contacts \
  -H 'Authorization: Bearer at_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: contact-create-001' \
  -d '{
    "name": "Amina Mbayo",
    "phone": "+243810000000",
    "email": "amina@example.com",
    "tags": "clients-vip,kinshasa"
  }'
201 Created
{
  "success": true,
  "contact": {
    "id": 12,
    "name": "Amina Mbayo",
    "phone": "+243810000000",
    "email": "amina@example.com",
    "tags": "clients-vip,kinshasa"
  }
}

Planifier une campagne

Le worker se charge ensuite du staging, des retries opérateur et des webhooks sortants.

curl -X POST https://cutuma.com/api/v1/campaigns \
  -H 'Authorization: Bearer at_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 26b7af09-c8b0-4b11-b0b5-99a3e2d82d90' \
  -d '{
    "name": "Lancement Avril",
    "content": "Notre offre est disponible jusqu a dimanche.",
    "senderName": "CUTUMA",
    "scheduledAt": "2026-04-10T08:00:00.000Z",
    "recipients": [
      "+243810000000",
      "+243820000000"
    ]
  }'

Endpoint POST /v1/campaigns — disponible prochainement. Créez vos campagnes via le dashboard en attendant.

Créer un webhook sortant

Le secret de signature est renvoyé une seule fois. Conservez-le immédiatement.

curl -X POST https://cutuma.com/api/v1/webhooks \
  -H 'Authorization: Bearer at_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://cutuma.com/webhooks/cutuma",
    "subscribed_events": ["message.delivered", "message.failed"]
  }'
202 Accepted
{
  "success": true,
  "webhookEndpoint": {
    "id": "7d5f1e88-6fd8-4ca7-a1a5-3b338f5f0f50",
    "url": "https://cutuma.com/webhooks/cutuma",
    "subscribed_events": ["message.delivered", "message.failed"],
    "status": "active"
  },
  "signingSecret": "at_whsec_..."
}

Voir la section webhooks du Quickstart pour la validation de signature.

Aller plus loin

SDK officiel, quickstart et référence complète.

SDK JavaScript Quickstart Référence API