Envoyer un SMS en Python avec une API REST (requests, Django, FastAPI)

Script d'automatisation, back-end Django ou API FastAPI : Python permet d'envoyer un SMS en quelques lignes. Voici comment utiliser l'API SMS Gold proprement, avec une gestion des erreurs adaptée à la production.

Prérequis

• Un compte SMS Gold activé, avec des crédits et un nom d'expéditeur approuvé.
• Une clé API (Paramètres → Clés API), exportée dans une variable d'environnement : export SMSGOLD_API_KEY=sk_live_…
• Python 3.8+ et la bibliothèque requests : pip install requests

1. Le premier SMS

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": "Votre commande n°1042 est prête.",
        "sender_name": "MABOUTIQUE",
    },
    timeout=30,
)
print(response.status_code, response.json())

Le paramètre json= encode le corps et ajoute l'en-tête Content-Type: application/json automatiquement. Le timeout évite qu'un appel bloque indéfiniment votre programme.

2. Une fonction réutilisable

import os
import re
import requests

API_URL = "https://smsgold.tornixtech.com/api/v2/sms/send"


class SmsError(Exception):
    def __init__(self, status: int, message: str):
        super().__init__(f"{status} : {message}")
        self.status = status


def normalize_ci(phone: str) -> str:
    """07 00 00 00 00 -> +2250700000000"""
    digits = re.sub(r"\D", "", phone)
    return "+" + digits if digits.startswith("225") else "+225" + digits


def send_sms(to: str, message: str, sender: str = "MABOUTIQUE") -> dict:
    try:
        r = requests.post(
            API_URL,
            headers={"Authorization": f"Bearer {os.environ['SMSGOLD_API_KEY']}"},
            json={"to": normalize_ci(to), "message": message, "sender_name": sender},
            timeout=30,
        )
    except requests.RequestException as exc:
        raise SmsError(0, f"connexion impossible : {exc}") from exc

    data = r.json() if r.content else {}
    if r.status_code != 200 or not data.get("success"):
        raise SmsError(r.status_code, data.get("error", "erreur inconnue"))
    return data

3. Dans Django

Placez la fonction dans un module (par exemple notifications/sms.py) et appelez-la après l'enregistrement d'une commande. Pour ne pas ralentir la réponse HTTP, déléguez l'envoi à une tâche asynchrone (Celery, Django-Q, RQ) :

# tasks.py (Celery)
from celery import shared_task
from notifications.sms import send_sms, SmsError

@shared_task(bind=True, max_retries=3, default_retry_delay=60)
def notify_order_ready(self, phone: str, order_id: int):
    try:
        send_sms(phone, f"Votre commande n°{order_id} est prête. Retrait dès aujourd'hui.")
    except SmsError as exc:
        # On ne relance que les problèmes de connexion, pas les erreurs de requête
        if exc.status == 0:
            raise self.retry(exc=exc)
        raise

4. Dans FastAPI

Avec FastAPI, les BackgroundTasks suffisent pour un volume modéré :

from fastapi import FastAPI, BackgroundTasks
from notifications.sms import send_sms

app = FastAPI()

@app.post("/orders/{order_id}/ready")
def order_ready(order_id: int, phone: str, tasks: BackgroundTasks):
    tasks.add_task(send_sms, phone, f"Votre commande n°{order_id} est prête.")
    return {"ok": True}

5. Quelles erreurs relancer ?

• Connexion impossible (réseau, DNS) : vous pouvez relancer après quelques secondes.
• 401, 403, 422 : la requête est incorrecte ou le compte doit être vérifié. Relancer ne changera rien.
• 402 : crédits insuffisants. Rechargez avant de relancer.
• 502 : l'opérateur n'a pas confirmé, mais le SMS a pu partir. Vérifiez votre solde (GET /account/credits) avant toute relance pour éviter un doublon.

6. Consulter son solde

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()["credits"])

Pratique pour déclencher une alerte interne lorsque le solde passe sous un seuil.

Pour aller plus loin

Consultez la documentation de l'API, les exemples en PHP et Node.js, et notre guide pour envoyer des codes OTP par SMS en toute sécurité.