Envoyer un SMS : POST /v1/sms

Requête

POST https://api.sms.gworldship.com/v1/sms, avec un en-tête Authorization: Bearer gsk_… et un corps JSON.

curl -X POST 'https://api.sms.gworldship.com/v1/sms' \
  -H 'Authorization: Bearer gsk_votre_cle_api' \
  -H 'Content-Type: application/json' \
  -d '{"to":"+237690000000","text":"Votre code de confirmation est 4821."}'

Le même envoi, muni d'une référence métier et d'un numéro saisi au format local : les espaces sont ignorés, le numéro est normalisé.

curl -X POST 'https://api.sms.gworldship.com/v1/sms' \
  -H 'Authorization: Bearer gsk_votre_cle_api' \
  -H 'Content-Type: application/json' \
  -d '{
        "to": "677 12 34 56",
        "text": "Commande 10427 confirmee. Livraison prevue jeudi.",
        "clientReference": "commande-10427-confirmation"
      }'

Paramètres

Aucun autre champ n'est lu. Il n'existe pas de nom d'expéditeur personnalisé : le destinataire voit le numéro de la carte SIM émettrice.

Réponse : 202 Accepted

HTTP/1.1 202 Accepted

{
  "messageId": "0d0a6f4e-1c3b-4f6a-9a1e-52a0f6d2b311",
  "to": "+237677123456",
  "operator": "MTN",
  "segments": 1,
  "priceXaf": 5,
  "status": "QUEUED",
  "clientReference": "commande-10427-confirmation",
  "balanceAfterXaf": 4995,
  "createdAt": "2026-09-12T10:15:00Z"
}

La même structure est renvoyée par GET /v1/sms/{messageId} et par chaque entrée du journal GET /v1/sms, à ceci près que balanceAfterXaf n'apparaît que sur la création.

Détection de l'opérateur par le préfixe

Il n'y a rien à préciser dans la requête : l'opérateur est déduit du numéro, par correspondance du préfixe le plus long. Cette règle n'est pas un détail — les plages 654 et 688 sont découpées entre opérateurs, et une correspondance sur trois chiffres seulement enverrait le message sur le mauvais réseau.

Un numéro dont le préfixe n'est couvert par aucune règle n'est pas rejeté : il part par la route par défaut, tracée DEFAULT et facturée à son propre tarif. C'est le cas des sous-plages encore non attribuées au plan national.

Ces règles de préfixes vivent en base et suivent les attributions du régulateur : elles peuvent évoluer. Pour vérifier un numéro précis, l'outil opérateur d'un numéro camerounais applique exactement les mêmes règles.

Ordre des contrôles

Connaître cet ordre évite des heures de perplexité : quand deux problèmes coexistent, c'est toujours le premier de cette liste qui est signalé.

1. Le compte porteur de la clé existe et est actif.
2. Le clientReference, s'il est fourni, n'a jamais servi. Sinon la réponse est un 409 qui contient le message existant — et rien n'est débité.
3. Le texte et le numéro sont valides, l'opérateur est résolu, le prix est calculé (TEXT_EMPTY, TEXT_TOO_LONG, INVALID_NUMBER, PRICE_NOT_CONFIGURED).
4. L'opérateur visé n'est pas suspendu. S'il l'est, 503 OPERATOR_DISABLED est renvoyé avant tout débit.
5. Le quota journalier du compte n'est pas atteint.
6. Le solde couvre le prix : le débit et l'enregistrement du message se font dans la même transaction. Si le solde est insuffisant, 402 INSUFFICIENT_BALANCE.

Le débit du solde et la création du message sont indissociables : il n'existe pas de cas où un compte est débité sans message, ni de message sans débit.

Cas d'échec

Une erreur a toujours la même forme : un code stable et un message explicatif.

HTTP/1.1 400 Bad Request

{
  "code": "INVALID_NUMBER",
  "message": "Numéro invalide : formats acceptés +2376XXXXXXXX, 2376XXXXXXXX, 6XXXXXXXX"
}

La liste complète des codes du serveur, classée par statut HTTP, est sur la page codes d'erreur.