API v1
Documentation de l'API GNAKRYSMS.
Envoyez des SMS, suivez leur statut, consultez votre solde et recevez des webhooks depuis vos applications.
Introduction
L'API GNAKRYSMS permet d'envoyer des SMS, de suivre leur statut et de consulter votre solde de crédits depuis vos propres applications.
URL de base
https://www.gnakrysms.com/api/v1
Format
JSON
Encodage
UTF-8
Authentification
Clé API dans le header Authorization
Limite de requêtes
60 par minute et par clé
Version
1.0.0
Chaque réponse porte les headers X-RateLimit-Limit, X-RateLimit-Remaining et X-Request-Id. Au-delà de la limite, l'API répond 429.
Démarrage rapide
Suivez ces étapes pour envoyer votre premier message depuis une application externe.
- 1
Créer une clé API
Connectez-vous au dashboard et générez une clé dans l'espace développeur.
- 2
Valider un expéditeur
Ajoutez le nom qui s'affichera chez vos destinataires.
- 3
Envoyer une requête
Appelez l'endpoint d'envoi de SMS avec votre clé API.
curl -X POST https://www.gnakrysms.com/api/v1/sms/send \
-H "Authorization: Bearer gsk_live_xxxxxxxxx" \
-H "Idempotency-Key: commande-2481" \
-H "Content-Type: application/json" \
-d '{
"to": ["+224XXXXXXXXX"],
"from": "VOTREMARQUE",
"message": "Votre commande est prête."
}'Authentification
Chaque requête doit inclure une clé API générée depuis le tableau de bord. Les clés doivent rester privées et ne jamais être exposées côté navigateur.
Authorization: Bearer gsk_live_xxxxxxxxx
Content-Type: application/jsonChaque clé porte des permissions. Une clé sans la permission requise reçoit une erreur 403 insufficient_scope.
Spécification OpenAPI
La spécification est disponible au format OpenAPI pour tester les endpoints dans des outils comme Postman, Insomnia, Swagger UI ou Scalar.
Format
OpenAPI 3.1
URL
https://www.gnakrysms.com/openapi.json
Version
1.0.0
Authentification
Bearer (clé API)
Envoyer un SMS
Envoyez un SMS à un destinataire ou à une liste de 100 numéros au plus. Le nom d'expéditeur doit être validé avant usage.
Les crédits sont débités à la mise en file : un crédit par segment SMS et par destinataire. La réponse est un 202. Une requête rejouée avec la même clé et le même contenu renvoie un 200 avec idempotent_replay: true ; avec un contenu différent, elle renvoie un 409.
L'encodage dépend du texte : tant que tous les caractères appartiennent à l'alphabet GSM-7, un segment contient 160 caractères (153 au-delà d'un segment). Dès qu'un caractère en sort (par exemple ê, ç minuscule ou un emoji), le message passe en UCS-2 : 70 caractères par segment (67 au-delà). La réponse indique l'encodage retenu et le nombre de segments.
{
"request_id": "req_9f2c4d7a1b3e4c58a6d0e1f2b3c4d5e6",
"status": "queued",
"recipients": 1,
"segments_per_recipient": 1,
"encoding": "UCS-2",
"credits_reserved": 1,
"remaining_credits": 12449,
"messages": [
{
"id": "msg_3a7e1c9d5b2f4e8a90c1d2e3f4a5b6c7",
"to": "+224XXXXXXXXX",
"status": "queued"
}
],
"idempotent_replay": false
}Suivre un message
{
"id": "msg_3a7e1c9d5b2f4e8a90c1d2e3f4a5b6c7",
"to": "+224XXXXXXXXX",
"status": "delivered",
"operator": "orange",
"provider": "orange",
"segments": 1,
"credits_charged": 1,
"error": null,
"queued_at": "2026-06-15T10:41:12.000Z",
"sent_at": "2026-06-15T10:41:14.000Z",
"delivered_at": "2026-06-15T10:42:00.000Z"
}WhatsApp Business
Les messages WhatsApp utilisent des crédits séparés et sont pensés pour les confirmations, relances et conversations automatisées.
L'API v1 n'expose pas WhatsApp : seuls l'envoi de SMS, le suivi des messages et le solde sont disponibles. WhatsApp s'utilise depuis le tableau de bord.
Contacts
Ajoutez des contacts, organisez-les par groupes et réutilisez ces groupes dans vos campagnes.
L'API v1 n'expose pas la gestion des contacts : elle se fait depuis le tableau de bord.
Crédits
Consultez votre solde et vérifiez que votre compte dispose d'assez de crédits avant de lancer un envoi.
{
"balance": 12450,
"unit": "sms_segment"
}Webhooks
Recevez sur votre serveur les événements d'envoi, de livraison ou d'échec de vos SMS. Les URL de réception (HTTPS publiques) se configurent depuis le tableau de bord.
{
"id": "evt_5c8d2e1f3a4b4c9d8e7f6a5b4c3d2e1f",
"type": "message.delivered",
"created_at": "2026-06-15T10:42:01.000Z",
"data": {
"message": {
"id": "msg_3a7e1c9d5b2f4e8a90c1d2e3f4a5b6c7",
"to": "+224XXXXXXXXX",
"from": "VOTREMARQUE",
"status": "delivered",
"operator": "orange",
"provider": "orange",
"segments": 1,
"credits_charged": 1,
"error": null,
"source": "api",
"queued_at": "2026-06-15T10:41:12.000Z",
"sent_at": "2026-06-15T10:41:14.000Z",
"delivered_at": "2026-06-15T10:42:00.000Z"
}
}
}Pour vérifier la signature, calculez le HMAC-SHA256 de {timestamp}.{corps brut} avec le secret de votre endpoint, puis comparez-le à la valeur après v1=. Répondez par un code 2xx : toute autre réponse est rejouée, jusqu'à 8 tentatives espacées de 30 secondes à 15 heures.
Codes d'erreur
L'API retourne des codes HTTP standards avec un corps JSON : un objet error (code, message, details éventuels) et l'identifiant request_id.
{
"error": {
"code": "insufficient_credits",
"message": "Crédits insuffisants : 3 requis",
"details": { "required": 3 }
},
"request_id": "7b1f0a52-6c1e-4d0e-9b8e-2f3a4c5d6e7f"
}