Documentation API SMS : référence et exemples

Vue d'ensemble

L'API SMS Gold vous permet d'envoyer des SMS unitaires directement depuis votre code, sans passer par l'interface web. Chaque requête est authentifiée par une clé API et consomme un crédit par SMS envoyé.

Prérequis

Un compte activé : la mise en service de l'envoi est réglée depuis votre espace.
Un nom d'expéditeur approuvé : au moins un Sender ID validé par notre équipe, nécessaire pour créer une clé API.
Des crédits SMS : un crédit par SMS, achetés depuis votre espace (voir les tarifs).

Authentification

Toutes les requêtes doivent inclure l'en-tête Authorization avec votre clé API au format Bearer :

En-tête HTTP

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Créez et révoquez vos clés depuis Paramètres → Clés API dans votre espace, jusqu'à 5 clés actives. Conservez-les côté serveur (variable d'environnement), jamais dans une application mobile ou un dépôt de code public.

URL de base

https://smsgold.tornixtech.com/api/v2

Toutes les communications sont chiffrées en TLS (HTTPS).

POST/sms/send

Envoyer un SMS

Envoie un SMS à un numéro. Un crédit est consommé par envoi.

Corps de la requête (JSON)

Champ	Type	Requis	Description
`to`	string	Oui	Numéro destinataire au format international (`+225…`).
`message`	string	Oui	Contenu du SMS. Un SMS standard contient jusqu'à 160 caractères.
`sender_name`	string	Oui	Nom d'expéditeur approuvé pour votre compte (11 caractères maximum).

Exemples

curl -X POST https://smsgold.tornixtech.com/api/v2/sms/send \
  -H "Authorization: Bearer $SMSGOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+2250700000000",
    "message": "Bonjour Awa, votre commande n°1042 est prête. Retrait dès aujourd'\''hui.",
    "sender_name": "MABOUTIQUE"
  }'

<?php
$ch = curl_init('https://smsgold.tornixtech.com/api/v2/sms/send');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('SMSGOLD_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'to'          => '+2250700000000',
        'message'     => "Bonjour Awa, votre commande n°1042 est prête. Retrait dès aujourd'hui.",
        'sender_name' => 'MABOUTIQUE',
    ]),
]);

$body   = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 200 && $body['success']) {
    echo "SMS envoyé : {$body['message_id']}";
} else {
    echo "Erreur $status : {$body['error']}";
}

import os
import requests

response = requests.post(
    "https://smsgold.tornixtech.com/api/v2/sms/send",
    headers={"Authorization": f"Bearer {os.environ['SMSGOLD_API_KEY']}"},
    json={
        "to": "+2250700000000",
        "message": "Bonjour Awa, votre commande n°1042 est prête. Retrait dès aujourd'hui.",
        "sender_name": "MABOUTIQUE",
    },
    timeout=30,
)

data = response.json()
if response.ok and data["success"]:
    print("SMS envoyé :", data["message_id"], "- crédits restants :", data["credits_remaining"])
else:
    print("Erreur", response.status_code, data.get("error"))

// Node.js 18+ (fetch natif)
const response = await fetch("https://smsgold.tornixtech.com/api/v2/sms/send", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SMSGOLD_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    to: "+2250700000000",
    message: "Bonjour Awa, votre commande n°1042 est prête. Retrait dès aujourd'hui.",
    sender_name: "MABOUTIQUE",
  }),
});

const data = await response.json();
if (response.ok && data.success) {
  console.log("SMS envoyé :", data.message_id);
} else {
  console.error("Erreur", response.status, data.error);
}

Réponse en cas de succès

200 OK

{
  "success": true,
  "message_id": "tel%3A%2B2250700000000-abc123",
  "status": "sent",
  "credits_remaining": 498,
  "error": null
}

message_id est l'identifiant attribué par l'opérateur. credits_remaining indique votre solde après l'envoi.

Réponse si le solde est insuffisant

402 Payment Required

{
  "success": false,
  "error": "Crédits insuffisants",
  "available": 0
}

GET/account/credits

Consulter le solde

Retourne le solde de crédits SMS disponibles pour votre compte.

curl https://smsgold.tornixtech.com/api/v2/account/credits \
  -H "Authorization: Bearer $SMSGOLD_API_KEY"

<?php
$ch = curl_init('https://smsgold.tornixtech.com/api/v2/account/credits');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('SMSGOLD_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Crédits disponibles : {$body['credits']}";

import os
import requests

r = requests.get(
    "https://smsgold.tornixtech.com/api/v2/account/credits",
    headers={"Authorization": f"Bearer {os.environ['SMSGOLD_API_KEY']}"},
    timeout=15,
)
print(r.json())  # {"success": true, "company": "...", "credits": 499}

const res = await fetch("https://smsgold.tornixtech.com/api/v2/account/credits", {
  headers: { Authorization: `Bearer ${process.env.SMSGOLD_API_KEY}` },
});
const { credits } = await res.json();
console.log("Crédits disponibles :", credits);

Réponse

200 OK

{
  "success": true,
  "company": "Ma Boutique SARL",
  "credits": 499
}

Crédits et remboursements

Le crédit est pré-débité au moment de la requête, puis remboursé automatiquement si l'opérateur confirme ne pas avoir traité l'envoi.

Situation	Crédit remboursé	Raison
Solde insuffisant (402)	Aucun débit	La requête est refusée avant l'envoi.
L'opérateur accepte le SMS	Non	SMS envoyé.
L'opérateur rejette la requête (4xx)	Oui	Rejet explicite : le SMS n'est jamais parti.
Connexion impossible	Oui	La requête n'a jamais atteint l'opérateur.
Erreur serveur opérateur (5xx)	Non	Le SMS a pu être mis en file d'attente.
Délai de réponse dépassé	Non	La requête est partie ; le SMS est peut-être en route.

Sur une erreur 502, un crédit peut avoir été consommé sans confirmation. En cas de doute, consultez votre solde avec GET /account/credits avant de relancer l'envoi, pour éviter un doublon chez votre destinataire.

Noms d'expéditeur

Le champ sender_name doit correspondre exactement à un nom d'expéditeur approuvé pour votre compte. Un nom en attente de validation, ou appartenant à un autre compte, est refusé.

Conditions d'approbation

1 à 11 caractères alphanumériques, sans caractères spéciaux.
Cohérence avec l'activité déclarée et le site web fourni.
Validation par notre équipe sous 2 à 3 jours ouvrés.
Le premier nom est inclus dans la mise en service ; chaque nom supplémentaire est facturé (voir les tarifs).

Soumettez vos demandes depuis Facturation → Noms d'expéditeur dans votre espace.

Erreur renvoyée si le nom n'est pas approuvé

422 Unprocessable Entity

{
  "success": false,
  "error": "Expéditeur \"MON_NOM\" non approuvé pour ce compte"
}

Codes d'erreur

Les erreurs suivent toujours le format { "success": false, "error": "…" }.

Code	Statut	Cause
401	`Unauthorized`	Clé API absente, invalide ou révoquée.
402	`Payment Required`	Crédits insuffisants pour l'envoi (aucun débit).
403	`Forbidden`	Compte désactivé, ou aucun nom d'expéditeur approuvé.
422	`Unprocessable Entity`	Champ manquant (to, message, sender_name) ou nom d'expéditeur non approuvé pour ce compte.
502	`Bad Gateway`	L'opérateur n'a pas confirmé l'envoi. Si le rejet est certain, le crédit est remboursé automatiquement.

Limites

Ressource	Limite
Clés API actives par compte	5
Destinataires par requête	1
Longueur d'un SMS standard	160 caractères
Nom d'expéditeur	11 caractères alphanumériques
Format du numéro	International E.164 (`+225XXXXXXXXXX`)
Délai d'attente côté opérateur	15 secondes

Besoin d'aide ?

Consultez la FAQ ou écrivez-nous via la page contact (réponse sous 24 h ouvrées). Pour une vue d'ensemble des possibilités de l'API, voir la page API SMS.

Référence de l'API SMS Gold