Documentation développeur

L'API Omnicus360 expose l'envoi de SMS, la consultation des statuts, les campagnes et les contacts. Elle masque totalement l'agrégateur sous-jacent : votre intégration ne change pas lorsque l'on ajoute, remplace ou bascule un fournisseur.

URL de base : https://omnicus360.com

1. Démarrage rapide

1. Créez une clé API depuis votre espace client et conservez le secret complet (affiché une seule fois).
2. Faites approuver un Sender ID (ou utilisez le libellé OMNICUS360 par défaut).
3. Envoyez votre premier message.

curl

curl -X POST https://omnicus360.com/api/v1/sms \
  -H "Authorization: Bearer sk_xxxxxxxx.votre_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+237690000001",
    "sender": "MONENTREPRISE",
    "message": "Bonjour, votre commande est prête."
  }'

json

{
  "success": true,
  "data": {
    "message_id": "clx7f2k9a0001",
    "status": "SUBMITTED",
    "to": "237690000001",
    "segments": 1,
    "credits_used": 1,
    "balance": 4832
  }
}

2. Authentification

Chaque requête porte l'en-tête Authorization: Bearer <clé>. L'en-tête X-API-KEY est également accepté. Une clé peut être restreinte à des adresses IP et à un sous-ensemble de permissions ; elle est révocable à tout moment depuis l'espace client. Le débit est limité à 120 appels par minute et par clé (30 pour les envois en masse).

3. Points d'entrée

Méthode	Endpoint	Permission	Description
POST	/api/v1/sms	sms:send	Envoi d'un SMS unitaire
POST	/api/v1/sms/bulk	sms:send	Envoi vers plusieurs destinataires (200 max)
GET	/api/v1/sms/{id}	sms:read	Statut détaillé d'un message
GET	/api/v1/messages	sms:read	Historique paginé et filtrable
GET	/api/v1/balance	balance:read	Solde de crédits et tarif applicable
GET	/api/v1/campaigns	sms:read	Liste des campagnes
POST	/api/v1/campaigns	campaigns:write	Création et lancement d'une campagne
GET	/api/v1/campaigns/{id}	sms:read	État d'une campagne
POST	/api/v1/campaigns/{id}	campaigns:write	Lancer, suspendre ou annuler
POST	/api/v1/otp	sms:send	Génération / vérification d'un code OTP
GET	/api/v1/contacts	sms:read	Liste des contacts
POST	/api/v1/contacts	contacts:write	Création ou mise à jour de contacts

4. Exemples d'intégration

Envoi en masse avec personnalisation

json

POST /api/v1/sms/bulk

{
  "sender": "MONENTREPRISE",
  "message": "Bonjour {{prenom}}, votre facture du {{date}} est disponible.",
  "to": [
    { "to": "+237690000001", "variables": { "prenom": "Awa" } },
    { "to": "+237677000002", "variables": { "prenom": "Jean" } }
  ]
}

Node.js

javascript

const res = await fetch('https://omnicus360.com/api/v1/sms', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OMNICUS360_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '+237690000001',
    message: 'Votre code de livraison : 4821',
  }),
});

const { success, data, error } = await res.json();
if (!success) throw new Error(error.code + ' — ' + error.message);
console.log('Message', data.message_id, 'statut', data.status);

PHP

php

$ch = curl_init('https://omnicus360.com/api/v1/sms');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('OMNICUS360_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'to' => '+237690000001',
    'message' => 'Votre commande est confirmée.',
  ]),
]);
$response = json_decode(curl_exec($ch), true);

Code à usage unique (OTP)

bash

# 1. Génération et envoi
curl -X POST https://omnicus360.com/api/v1/otp \
  -H "Authorization: Bearer $OMNICUS360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+237690000001", "length": 6 }'

# 2. Vérification du code saisi par l'utilisateur
curl -X POST https://omnicus360.com/api/v1/otp \
  -H "Authorization: Bearer $OMNICUS360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+237690000001", "code": "482193" }'

5. Webhooks

Déclarez une URL depuis l'espace webhooks. Chaque notification est signée : recalculez le HMAC-SHA256 du corps brut avec votre secret et comparez-le à l'en-tête X-Omnicus360-Signature. La clé d'idempotenceX-Omnicus360-Delivery permet d'ignorer les rejeux. Cinq tentatives sont effectuées avec un délai croissant (30 s → 1 h) tant que votre serveur ne répond pas 2xx.

json

POST https://votre-serveur.com/webhook
X-Omnicus360-Event: message.delivered
X-Omnicus360-Signature: sha256=9f8c...
X-Omnicus360-Delivery: clx7...-message.delivered-a1b2

{
  "event": "message.delivered",
  "sent_at": "2026-08-27T10:12:44.120Z",
  "data": {
    "message_id": "clx7f2k9a0001",
    "provider_message_id": "sim-8f2c4a91",
    "to": "237690000001",
    "delivered_at": "2026-08-27T10:12:43.900Z"
  }
}

javascript

import crypto from 'crypto';

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.OMNICUS360_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (`sha256=${expected}` !== req.headers['x-omnicus360-signature']) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString());
  // traiter event.event / event.data puis répondre rapidement
  res.status(200).json({ received: true });
});

6. Cycle de vie d'un message

ACCEPTED

Message accepté par la plateforme, crédits débités

SUBMITTED

Transmis à l'agrégateur, identifiant reçu

SENT

Pris en charge par l'opérateur

PENDING

En attente du rapport de livraison

DELIVERED

Reçu sur le terminal du destinataire

FAILED

Échec définitif (crédits remboursés si non soumis)

EXPIRED

Durée de validité dépassée chez l'opérateur

REJECTED

Rejeté (numéro invalide, contenu refusé, annulation)

7. Codes d'erreur

Code	HTTP	Signification
MISSING_API_KEY	401	Aucune clé API transmise
INVALID_API_KEY	401	Clé inconnue ou secret incorrect
KEY_DISABLED	403	Clé désactivée par le client
IP_NOT_ALLOWED	403	IP appelante hors liste blanche
SCOPE_DENIED	403	Permission absente de la clé
INVALID_MSISDN	400	Numéro invalide ou non normalisable
SENDER_NOT_APPROVED	400	Sender ID non validé par l'exploitant
INSUFFICIENT_CREDITS	402	Solde de crédits insuffisant
NO_ROUTE	400	Aucune route ne couvre ce numéro
RATE_LIMITED	429	Limite de débit dépassée (120 appels/min)

8. Environnement de test

L'agrégateur « Simulateur » reproduit la chaîne complète — soumission, identifiant fournisseur, rapport de livraison asynchrone — sans contrat opérateur. Tout numéro se terminant par 0000 déclenche volontairement un rejet INVALID_MSISDN, ce qui permet de recetter vos traitements d'erreur. Les crédits consommés en simulation suivent les mêmes règles qu'en production.