Documentation de l'API SMS G-SMS

Ce qu'il faut savoir avant de commencer

• L'adresse de base est https://api.sms.gworldship.com. Toutes les réponses sont en JSON UTF-8, les dates en ISO-8601 UTC, les montants en francs CFA entiers.
• Un envoi est débité à l'acceptation, pas à la réception. Un message qui échoue définitivement est recrédité automatiquement.
• Les champs nuls sont omis des réponses : une clé absente ne signifie pas une erreur, elle signifie « pas de valeur ».
• Le destinataire voit le numéro de la carte SIM qui a émis le message, pas un nom d'expéditeur. C'est un choix de conception lié au caractère transactionnel du service : le numéro reste joignable et rappelable.

Authentification

Chaque application créée dans la console dispose de ses propres clés. Une clé commence par gsk_ et se présente dans l'en-tête Authorization :

Authorization: Bearer gsk_votre_cle_api

La clé porte à elle seule le compte et l'application : aucun identifiant de compte ne circule dans les requêtes, et un message n'est jamais visible depuis une autre application. Une clé absente, inconnue ou révoquée donne un 401 INVALID_API_KEY ; un compte qui n'est plus actif donne un 403 ACCOUNT_SUSPENDED.

La clé complète n'est affichée qu'une fois, à sa création. Elle se stocke côté serveur, dans une variable d'environnement — jamais dans une page, une application mobile ou un dépôt.

Premier envoi, en deux minutes

Un compte neuf reçoit un crédit de bienvenue : il y a de quoi envoyer plusieurs messages avant de recharger. Remplace la clé d'exemple par la tienne et le numéro par le tien.

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."}'

La réponse arrive immédiatement, avant même que le message ne parte :

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

{
  "messageId": "0d0a6f4e-1c3b-4f6a-9a1e-52a0f6d2b311",
  "to": "+237690000000",
  "operator": "ORANGE",
  "segments": 1,
  "priceXaf": 5,
  "status": "QUEUED",
  "balanceAfterXaf": 95,
  "createdAt": "2026-09-12T10:15:00Z"
}

• messageId — identifiant à conserver : c'est lui qui sert à relire le statut.
• to — le numéro normalisé en E.164, quel que soit le format envoyé.
• operator — l'opérateur déduit du préfixe, ici Orange.
• segments et priceXaf — le découpage facturé et son coût total.
• status — QUEUED : le message est accepté et payé, il n'est pas encore remis. La suite se lit sur la page statuts et accusés de réception.
• balanceAfterXaf — le solde restant après le débit. Il n'apparaît que sur une création : un doublon ne débite rien, donc ne renvoie pas ce champ.

Aucun clientReference n'a été envoyé ici, donc le champ est absent de la réponse. En production, en poser un évite les doublons — voir l'idempotence.

Le reste de la documentation

Les endpoints

Tous demandent l'en-tête Authorization, sauf GET /v1/pricing qui est public. Les tarifs sont également lisibles sur la page Tarifs.