Documentation technique

Documentation API SMS REST

Envoi de SMS transactionnels et marketing, avec sandbox, idempotence, webhooks AR et SDK PHP.

REST JSON Auth Bearer Sandbox Idempotence Webhooks SDK PHP

Vous cherchez une vue d'ensemble ? Découvrez notre API SMS (fonctionnalités, tarifs, cas d'usage) .

Base URL : https://sms-proxima.com/api
Auth : Authorization: Bearer VOTRE_TOKEN
Format : application/json

🚀 Démarrage rapide

1

Créez un compte

Inscrivez-vous et attendez la validation de votre compte.

2

Générez votre clé

Depuis votre espace API, générez votre token Bearer.

3

Envoyez votre premier SMS

Testez en sandbox — aucun crédit débité.

curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "33612345678",
    "sender": "BOUTIQUE",
    "message": "Votre commande est confirmée.",
    "sandbox": 1
  }'
// Avec le SDK officiel
// composer require sms-proxima/sdk
use SmsProxima\SmsProxima;
$sms = new SmsProxima('VOTRE_TOKEN');
$result = $sms->send('33612345678', 'BOUTIQUE', 'Votre commande est confirmée.', ['sandbox' => 1]);
echo $result['ticket']; // api-42-1712345678
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer VOTRE_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    to: '33612345678',
    sender: 'BOUTIQUE',
    message: 'Votre commande est confirmée.',
    sandbox: 1,
  }),
});
const data = await res.json();
console.log(data.ticket); // api-42-1712345678
import requests

response = requests.post(
    'https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={
        'to': '33612345678',
        'sender': 'BOUTIQUE',
        'message': 'Votre commande est confirmée.',
        'sandbox': 1,
    }
)
data = response.json()
print(data['ticket'])  # api-42-1712345678
// Réponse succès
{ "status": 1, "ticket": "api-42-1712345678", "cost": 1, "credits": 999 }

📐 Formats & validation

Numéros de téléphone

Plusieurs formats sont acceptés — l'API normalise automatiquement.

// France — tous ces formats sont équivalents
"0612345678" // format local
"33612345678" // format international
"+33612345678" // avec +
"0033612345678" // avec 00
"612345678" // sans indicatif
// International — mêmes variantes acceptées
"32612345678" // Belgique
"+32612345678" // Belgique avec +
"0032612345678" // Belgique avec 00
Expéditeur (sender)
  • Entre 4 et 11 caractères
  • Lettres A-Z, a-z et chiffres 0-9 uniquement
  • Pas d'accents, espaces, tirets ou caractères spéciaux
  • Pas que des chiffres
  • Pas 5 chiffres consécutifs
Longueur des messages & segments
SegmentsCaractères max (sans sender)Caractères max (avec sender + STOP)
1160148
2306294
3459447
6 (max)918906

Les caractères accentués courants (à, é, è, ù, €) sont acceptés en GSM-7. Pour envoyer des emojis ou des caractères non latins (arabe, cyrillique…), utilisez le paramètre ucs2=1 — la capacité passe alors à 70 caractères par segment (67 en multi-segments).

🔑 Authentification

Toutes les requêtes doivent inclure ces headers :

Authorization: Bearer VOTRE_TOKEN
Accept: application/json
Content-Type: application/json

Test de connexion :

curl https://sms-proxima.com/api/ping \
  -H "Authorization: Bearer VOTRE_TOKEN"
$sms = new SmsProxima('VOTRE_TOKEN');
$result = $sms->ping();
// ["message" => "Authentifié avec succès", "user" => [...]]
const res = await fetch('https://sms-proxima.com/api/ping', {
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN' },
});
const data = await res.json();
console.log(data.message); // Authentifié avec succès
import requests
res = requests.get('https://sms-proxima.com/api/ping',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'})
print(res.json()['message'])  # Authentifié avec succès
// Réponse
{ "message": "Authentifié avec succès", "user": { "id": 1, "email": "..." } }
POST /sms/send

📤 Envoi SMS

ChampTypeRequisDescription
tostring|arrayOuiUn numéro ou un tableau de numéros au format international
senderstringNonExpéditeur alphanumérique (4–11 caractères) — voir Formats & validation.
Si omis, un numéro court (36xxx) est assigné automatiquement — nécessaire pour recevoir des réponses SMS.
messagestring|arrayOuiContenu du SMS — max 6 segments. Accepte une chaîne unique (même message pour tous) ou un tableau aligné sur to[] pour des messages personnalisés (un message par destinataire).
stopintNon0 ou 1 — défaut 1 (mention STOP ajoutée)
timeToSendstringNonEnvoi différé — YYYY/MM/DD HH:MM ou YYYY-MM-DD HH:MM, obligatoirement dans le futur
sandboxintNon1 = simulation (SMS non envoyé, aucun crédit débité, même structure de réponse)
ucs2intNon1 = encodage Unicode (UCS-2). Requis pour les emojis et caractères non latins (arabe, cyrillique…). La capacité par segment passe de 160 à 70 caractères (67 en multi-segments). S'applique à l'ensemble des messages de la requête.
curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"33612345678","sender":"BOUTIQUE","message":"Votre commande #1234 est confirmée."}'
$result = $sms->send('33612345678', 'BOUTIQUE', 'Votre commande #1234 est confirmée.');
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '33612345678', sender: 'BOUTIQUE', message: 'Votre commande #1234 est confirmée.' }),
});
const data = await res.json();
import requests
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'to': '33612345678', 'sender': 'BOUTIQUE', 'message': 'Votre commande #1234 est confirmée.'})
data = res.json()
curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":["33612345678","33687654321","33698765432"],"sender":"BOUTIQUE","message":"Vos soldes commencent demain !"}'
$result = $sms->send(
    ['33612345678', '33687654321', '33698765432'],
    'BOUTIQUE',
    'Vos soldes commencent demain !'
);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: ['33612345678', '33687654321', '33698765432'],
    sender: 'BOUTIQUE',
    message: 'Vos soldes commencent demain !',
  }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'to': ['33612345678', '33687654321'], 'sender': 'BOUTIQUE', 'message': 'Vos soldes commencent demain !'})
curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"33612345678","sender":"BOUTIQUE","message":"N oubliez pas votre RDV demain a 14h.","timeToSend":"2026-04-15 09:00"}'
$result = $sms->send('33612345678', 'BOUTIQUE', 'N oubliez pas votre RDV demain a 14h.',
    ['timeToSend' => '2026-04-15 09:00']);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: '33612345678', sender: 'BOUTIQUE',
    message: 'N oubliez pas votre RDV demain a 14h.',
    timeToSend: '2026-04-15 09:00',
  }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'to': '33612345678', 'sender': 'BOUTIQUE',
          'message': 'N oubliez pas votre RDV demain a 14h.', 'timeToSend': '2026-04-15 09:00'})
curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"to":"33612345678","sender":"TEST","message":"Test integration.","sandbox":1}'
# SMS non envoyé, crédits non débités, réponse identique à un vrai envoi
$result = $sms->send('33612345678', 'TEST', 'Test integration.', ['sandbox' => 1]);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '33612345678', sender: 'TEST', message: 'Test integration.', sandbox: 1 }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'to': '33612345678', 'sender': 'TEST', 'message': 'Test integration.', 'sandbox': 1})
curl -X POST https://sms-proxima.com/api/sms/send   -H "Authorization: Bearer VOTRE_TOKEN"   -H "Content-Type: application/json"   -d '{
    "to": ["33612345678", "33687654321"],
    "sender": "BOUTIQUE",
    "message": ["Bonjour Marie, votre commande est prete.", "Bonjour Nicolas, votre commande est prete."]
  }'
$result = $sms->send(
    ['33612345678', '33687654321'],
    'BOUTIQUE',
    ['Bonjour Marie, votre commande est prete.', 'Bonjour Nicolas, votre commande est prete.']
);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    to: ['33612345678', '33687654321'],
    sender: 'BOUTIQUE',
    message: ['Bonjour Marie, votre commande est prete.', 'Bonjour Nicolas, votre commande est prete.'],
  }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={
        'to': ['33612345678', '33687654321'],
        'sender': 'BOUTIQUE',
        'message': ['Bonjour Marie, votre commande est prete.', 'Bonjour Nicolas, votre commande est prete.'],
    })
Le nombre de messages doit correspondre exactement au nombre de destinataires. Le coût est calculé message par message selon le nombre de segments de chacun.
curl -X POST https://sms-proxima.com/api/sms/send   -H "Authorization: Bearer VOTRE_TOKEN"   -H "Content-Type: application/json"   -d '{"to":"33612345678","sender":"BOUTIQUE","message":"Merci pour votre commande 🎉","ucs2":1}'
$result = $sms->send('33612345678', 'BOUTIQUE', 'Merci pour votre commande 🎉', ['ucs2' => 1]);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '33612345678', sender: 'BOUTIQUE', message: 'Merci pour votre commande 🎉', ucs2: 1 }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'to': '33612345678', 'sender': 'BOUTIQUE', 'message': 'Merci pour votre commande 🎉', 'ucs2': 1})
En mode Unicode, la capacité passe de 160 à 70 caractères par segment (67 en multi-segments). Sans ucs2=1, un message contenant des emojis retournera une erreur INVALID_ENCODING.

Réponse succès

{
"status": 1,
"ticket": "api-1-1712345678",
"cost": 1,
"credits": 999,
"total": 1
}

Réponse erreur

{
"status": 0,
"message": "Ce numéro est en liste noire.",
"code": "MOBILE_BLACKLISTED",
"ticket": null
}

Codes machine possibles

CodeHTTPDescription
ACCOUNT_NOT_VALIDATED403Compte en attente de validation
INSUFFICIENT_CREDITS402Crédits insuffisants
INVALID_TIME_FORMAT422Format de timeToSend invalide
INVALID_TIME_PAST422La date d'envoi est dans le passé
MESSAGE_COUNT_MISMATCH422Le nombre de messages ne correspond pas au nombre de destinataires (mode message[])
EMPTY_MESSAGE422Un message du tableau est vide
INVALID_ENCODING422Le message contient des caractères Unicode — ajouter ucs2=1
UCS2_NOT_ALLOWED422L'encodage UCS-2 n'est pas autorisé pour cette destination
MOBILE_BLACKLISTED422Numéro en liste noire (STOP)
SENDER_NOT_ALLOWED422Expéditeur non autorisé
SUPPLIER_ERROR502Erreur fournisseur — contacter le support

🔁 Idempotence (anti double-envoi)

L'endpoint POST /sms/send supporte l'idempotence afin d'éviter les doubles envois lors d'un retry réseau ou d'une requête répétée.

curl -X POST https://sms-proxima.com/api/sms/send \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"to":"33612345678","sender":"BOUTIQUE","message":"..."}'
$result = $sms->send('33612345678', 'BOUTIQUE', '...', [
    'idempotencyKey' => '550e8400-e29b-41d4-a716-446655440000',
]);
const res = await fetch('https://sms-proxima.com/api/sms/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer VOTRE_TOKEN',
    'Content-Type': 'application/json',
    'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
  },
  body: JSON.stringify({ to: '33612345678', sender: 'BOUTIQUE', message: '...' }),
});
res = requests.post('https://sms-proxima.com/api/sms/send',
    headers={
        'Authorization': 'Bearer VOTRE_TOKEN',
        'Idempotency-Key': '550e8400-e29b-41d4-a716-446655440000',
    },
    json={'to': '33612345678', 'sender': 'BOUTIQUE', 'message': '...'})
  • Sur POST /api/sms/send, une clé d'idempotence est unique par utilisateur pendant 24 heures.
  • Maximum 255 caractères. Un UUID v4 est recommandé.
  • Une requête réussie (2xx) rejouée avec la même clé et le même contenu renvoie la réponse originale, sans nouvel envoi, avec le header Idempotency-Replayed: true.
  • La même clé ne doit jamais être réutilisée pour une requête différente.
Recommandation : générez un UUID v4 côté client pour chaque envoi logique et conservez-le avec votre commande ou votre opération. En cas de timeout réseau, rejouez la requête avec la même clé et exactement le même corps.

Gestion des retries

Code machine HTTP Signification Action recommandée
IDEMPOTENCY_KEY_TOO_LONG 400 La clé dépasse 255 caractères. Corriger la clé avant de renvoyer.
IDEMPOTENCY_KEY_REUSED 409 La clé a déjà été utilisée avec un contenu différent. Ne pas modifier une requête existante : utilisez une nouvelle clé pour un nouvel envoi.
IDEMPOTENCY_KEY_IN_PROGRESS 409 Une requête utilisant cette clé est encore en cours. Réessayer dans quelques secondes avec la même clé et le même contenu.
IDEMPOTENCY_KEY_STUCK 409 Le traitement précédent a été interrompu et son résultat n'a pas pu être confirmé. Aucun ticket n'a été attribué. Ne pas créer un nouvel envoi. Vérifiez GET /campaigns avant toute nouvelle tentative. La clé se libère automatiquement après 24 heures.
SEND_STATUS_UNKNOWN 202 Distinct du précédent : l'envoi a été transmis, la campagne est enregistrée et les crédits sont débités. Seule la confirmation fournisseur manque. Rejouer la même clé renvoie cette réponse à l'identique. Consultez GET /sms/{ticket}/deliveries avec le ticket fourni.
Résultat incertain : certaines erreurs serveur peuvent survenir après qu'une partie du traitement a déjà commencé. Dans ce cas, SMS Proxima conserve la clé pendant 24 heures plutôt que d'autoriser automatiquement un nouvel envoi. Un rejeu renvoie alors IDEMPOTENCY_KEY_IN_PROGRESS dans les premières minutes, puis IDEMPOTENCY_KEY_STUCK si l'état reste indéterminé. Ne générez pas une nouvelle clé pour contourner ce blocage sans avoir vérifié vos rapports d'envoi.
Comparaison du contenu : l'idempotence compare le corps HTTP brut de la requête. Deux objets JSON contenant les mêmes valeurs mais sérialisés différemment — par exemple avec un ordre de propriétés différent — sont considérés comme deux contenus différents.
GET /credits

💳 Crédits disponibles

curl https://sms-proxima.com/api/credits \
  -H "Authorization: Bearer VOTRE_TOKEN"
$credits = $sms->credits(); // int
const res = await fetch('https://sms-proxima.com/api/credits', {
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN' },
});
const { credits } = await res.json();
res = requests.get('https://sms-proxima.com/api/credits',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'})
credits = res.json()['credits']
{ "credits": 1200 }
POST /sms/count

🔢 Comptage de caractères

Calculez le nombre de segments SMS avant envoi.

curl -X POST https://sms-proxima.com/api/sms/count \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message":"Votre code : 1234"}'
$result = $sms->count('Votre code : 1234');
// ["nb_sms" => 1, "nb_caracteres" => 18]
const res = await fetch('https://sms-proxima.com/api/sms/count', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Votre code : 1234' }),
});
const { nb_sms, nb_caracteres } = await res.json();
res = requests.post('https://sms-proxima.com/api/sms/count',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'message': 'Votre code : 1234'})
data = res.json()  # {"nb_sms": 1, "nb_caracteres": 18}
{ "nb_sms": 1, "nb_caracteres": 18 }
GET /sms/{tracker}/deliveries

📬 Accusés de réception

Liste paginée des AR reçus pour une campagne. Seuls les destinataires ayant généré un retour opérateur apparaissent. Pour les autres, consultez GET /campaigns (champ pending).

Paramètre de pagination : ?page=1 — 100 résultats par page.

curl "https://sms-proxima.com/api/sms/api-1-1712345678/deliveries?page=1" \
  -H "Authorization: Bearer VOTRE_TOKEN"
$deliveries = $sms->deliveries('api-1-1712345678');
const res = await fetch('https://sms-proxima.com/api/sms/api-1-1712345678/deliveries?page=1', {
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN' },
});
const data = await res.json();
res = requests.get('https://sms-proxima.com/api/sms/api-1-1712345678/deliveries',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    params={'page': 1})
data = res.json()
{
"tracker": "api-1-1712345678",
"data": [{
"mobile": "33612345678",
"status": "delivered",
"operator": "orange",
"is_stop": false,
"received_at": "2026-03-01T10:00:05+00:00"
}],
"total": 1, "per_page": 100, "current_page": 1, "last_page": 1
}
statusDescription
deliveredSMS remis au destinataire
failedÉchec de remise (numéro invalide, hors service…)
pendingEn attente de retour opérateur
GET /campaigns

📋 Historique campagnes

Retour paginé (50/page) avec statistiques d'envoi par campagne. Paramètre : ?page=1.

{
"data": [{
"ticket": "api-1-1712345678",
"sender": "BOUTIQUE",
"date": "2026-03-01 14:00:00",
"count": 100,
"received": 87,
"pending": 10,
"error": 2,
"stop": 1
}],
"total": 42, "per_page": 50, "current_page": 1
}
Le champ pending indique le nombre de destinataires pour lesquels aucun AR n'a encore été reçu. Pour les détails par destinataire, utilisez GET /sms/{ticket}/deliveries.

🚫 Blacklist

MéthodeEndpointDescription
GET/blacklistListe des numéros blacklistés
POST/blacklistAjouter — body : {"mobile": "33612345678"}
DELETE/blacklist/{mobile}Retirer un numéro

Ajout

curl -X POST https://sms-proxima.com/api/blacklist \
  -H "Authorization: Bearer VOTRE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mobile":"33612345678"}'
$sms->addToBlacklist('33612345678');
await fetch('https://sms-proxima.com/api/blacklist', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer VOTRE_TOKEN', 'Content-Type': 'application/json' },
  body: JSON.stringify({ mobile: '33612345678' }),
});
requests.post('https://sms-proxima.com/api/blacklist',
    headers={'Authorization': 'Bearer VOTRE_TOKEN'},
    json={'mobile': '33612345678'})

Réponse

{
"status": 1,
"message": "Numéro ajouté en liste rouge.",
"mobile": "33612345678"
}
Un numéro ayant répondu STOP ne peut pas être retiré via l'API.

🔔 Webhooks

Configurez une URL HTTPS par type d'événement depuis votre espace API. SMS Proxima envoie un POST JSON pour chaque événement, signé en HMAC SHA-256 avec le secret de signature de votre compte, commun à tous vos webhooks (voir Signature HMAC).

EventDéclencheur
delivery.receiptAccusé de réception opérateur (livré ou échec)
sms.stopLe destinataire a répondu STOP
sms.inboundRéponse SMS d'un destinataire (hors STOP)

delivery.receipt — Accusés de réception

Envoyé à chaque retour opérateur (livraison ou échec). L'event peut arriver plusieurs secondes après l'envoi.

Header envoyéValeur
X-SMSP-EventNom de l'événement (delivery.receipt, sms.stop, sms.inbound)
X-SMSP-IdIdentifiant de l'événement (event_id), identique à chaque tentative
X-SMSP-TimestampTimestamp Unix (secondes) de cette tentative, recalculé à chaque tentative
X-SMSP-Signaturet={timestamp}, v1={signature} — HMAC SHA-256 en hexadécimal minuscule, recalculé à chaque tentative (voir Signature HMAC)
Idempotency-KeyIdentifiant de l'événement (anti-doublon), égal à X-SMSP-Id
{
"version": "v1",
"event": "delivery.receipt",
"event_id": "1711175235",
"emitted_at": "2026-03-01T09:59:55+00:00",
"campaign_id": 1234,
"message": {
"provider_message_id": "abc123xyz",
"to": "33612345678"
},
"delivery": {
"status": "delivered",
"status_code": "0",
"error_code": "000",
"operator": "orange",
"received_at": "2026-03-01T09:59:55+00:00"
}
}

Exemple PHP

// webhook.php — votre endpoint
$payload = json_decode(file_get_contents('php://input'), true);
$eventId = $payload['event_id'] ?? null;

// Anti-doublon
if (alreadyProcessed($eventId)) { http_response_code(200); exit; }

$status = $payload['delivery']['status']; // "delivered", "failed"
$mobile = $payload['message']['to'];

markDelivered($mobile, $status);
http_response_code(200);

sms.stop — STOP reçus

Envoyé quand un destinataire répond STOP. Le numéro est automatiquement ajouté à votre blacklist SMS Proxima.

{
"version": "v1",
"event": "sms.stop",
"event_id": "stop-ce8e9b763426",
"emitted_at": "2026-03-01T09:59:55+00:00",
"campaign_id": 1234,
"message": {
"from": "33612345678",
"text": "STOP"
}
}
$payload = json_decode(file_get_contents('php://input'), true);
if (alreadyProcessed($payload['event_id'] ?? null)) { http_response_code(200); exit; }

$mobile = $payload['message']['from']; // numéro qui a envoyé STOP

// Déjà blacklisté chez SMS Proxima — mettez à jour votre propre base
markUnsubscribed($mobile);
http_response_code(200);

sms.inbound — Réponses SMS

Envoyé quand un destinataire répond à votre SMS (hors STOP). Nécessite un expéditeur vide (numéro court).

{
"version": "v1",
"event": "sms.inbound",
"event_id": "inb-a1b2c3d4e5f6",
"emitted_at": "2026-03-01T10:02:00+00:00",
"campaign_id": 1234,
"message": {
"provider_message_id": "xyz789abc",
"from": "33612345678",
"country_code": "33",
"text": "Merci pour l'info !",
"received_at": "2026-03-01T10:02:00+00:00"
}
}
$payload = json_decode(file_get_contents('php://input'), true);
if (alreadyProcessed($payload['event_id'] ?? null)) { http_response_code(200); exit; }

$from = $payload['message']['from']; // numéro expéditeur
$text = $payload['message']['text']; // contenu du SMS reçu

handleInboundSms($from, $text);
http_response_code(200);

Signature HMAC SHA-256

Les trois événements (delivery.receipt, sms.stop, sms.inbound) sont signés. La signature prouve que la notification vient de SMS Proxima et que son contenu n'a pas été modifié.

  • Secret : un seul secret par compte, au format whsec_ suivi de 64 caractères hexadécimaux, commun à tous vos webhooks : le même secret vérifie les trois événements (delivery.receipt, sms.stop, sms.inbound). Récupérez-le dans votre espace API (bloc « Secret de signature HMAC », bouton « Afficher / Copier »). Il sert tel quel de clé HMAC, préfixe whsec_ compris. Ne le communiquez jamais publiquement.
  • Signature : le secret est commun, mais la signature est différente pour chaque notification, car elle dépend de l'horodatage et du corps JSON.
  • Chaîne signée : la valeur de X-SMSP-Timestamp, un point, puis le corps HTTP brut exact : {timestamp}.{corps}.
  • En-tête : X-SMSP-Signature: t={timestamp}, v1={signature}, où {timestamp} est égal à X-SMSP-Timestamp et {signature} vaut hash_hmac('sha256', "{timestamp}.{corps}", secret) en hexadécimal minuscule (64 caractères).
  • Corps brut : calculez la signature sur les octets reçus, avant tout décodage JSON. Un corps décodé puis réencodé peut différer (espaces, échappements) et ne vérifie plus la signature.
  • Comparaison : utilisez une comparaison à temps constant (hash_equals en PHP), jamais ==.
  • Horodatage : rejetez les notifications dont le timestamp s'écarte de plus de 5 minutes de votre horloge, pour limiter le rejeu d'une requête interceptée.
  • Tentatives : le timestamp et la signature sont recalculés à chaque tentative ; event_id (et X-SMSP-Id) reste identique. Dédupliquez sur event_id, jamais sur la signature.

Exemple PHP de vérification

function smsproxima_verify_signature(string $body, string $header, string $secret, int $tolerance = 300): bool
{
    // En-tête attendu : t={timestamp}, v1={signature hexadécimale}
    if (!preg_match('/^t=(\d+), v1=([0-9a-f]{64})$/', $header, $m)) {
        return false;
    }
    [, $timestamp, $signature] = $m;

    // Horodatage : 5 minutes de tolérance par défaut
    if (abs(time() - (int) $timestamp) > $tolerance) {
        return false;
    }

    // Chaîne signée : timestamp + "." + corps brut, clé = secret complet (whsec_…)
    $expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

    // Comparaison à temps constant
    return hash_equals($expected, $signature);
}

// Utilisation dans votre endpoint
$secret = getenv('SMSPROXIMA_WEBHOOK_SECRET');  // whsec_… copié depuis l'espace API
$body   = file_get_contents('php://input');      // corps brut, AVANT json_decode
$header = $_SERVER['HTTP_X_SMSP_SIGNATURE'] ?? '';

if (!smsproxima_verify_signature($body, $header, $secret)) {
    http_response_code(401);  // arrêt définitif des tentatives pour cet événement
    exit;
}

$payload = json_decode($body, true);
if (alreadyProcessed($payload['event_id'])) { http_response_code(200); exit; }
// … traitement …
http_response_code(200);
Rotation du secret. Le bouton « Régénérer » de l'espace API remplace immédiatement le secret de tous les webhooks du compte, pour les trois événements : toutes les notifications suivantes, y compris les nouvelles tentatives d'événements déjà en attente, sont signées avec le nouveau secret, et l'ancien n'est plus jamais utilisé. Tant que votre système vérifie avec l'ancien secret, il rejettera ces notifications ; une réponse 400, 401, 403, 404, 410 ou 422 arrête définitivement les tentatives pour l'événement concerné. Coordonnez donc la régénération avec le système destinataire : planifiez-la, puis mettez à jour le secret de votre côté aussitôt après.

Si votre intégration ne vérifie pas la signature, rien ne change pour elle : l'en-tête X-SMSP-Signature peut être ignoré. Nous recommandons toutefois de le vérifier.

Votre endpoint doit répondre en HTTP 2xx sous 6 secondes (connexion : 3 secondes). Sinon, la notification est renvoyée : 8 tentatives au total, espacées de 1 min, 5 min, 15 min, 1 h, 3 h, 6 h puis 12 h, soit une dernière tentative environ 22 heures après la première. Les réponses 400, 401, 403, 404, 410 et 422 arrêtent définitivement les tentatives pour l'événement concerné. Utilisez event_id ou le header Idempotency-Key pour détecter les doublons.

📦 SDK PHP officiel

Compatible PHP 7.4+, zéro dépendance, open source.

// Installation
composer require sms-proxima/sdk

// Envoi simple
use SmsProxima\SmsProxima;
$sms = new SmsProxima('VOTRE_TOKEN');
$result = $sms->send('33612345678', 'BOUTIQUE', 'Commande confirmée');

// Gestion des erreurs
use SmsProxima\Exceptions\InvalidSenderException;
use SmsProxima\Exceptions\MobileBlacklistedException;
use SmsProxima\Exceptions\InsufficientCreditsException;
use SmsProxima\Exceptions\SmsProximaException;

try {
    $sms->send(...);
} catch (InvalidSenderException $e) { // expéditeur invalide
} catch (MobileBlacklistedException $e) { // numéro STOP
} catch (InsufficientCreditsException $e) { // crédits insuffisants
} catch (SmsProximaException $e) { // autre erreur — $e->getApiCode()
}

🔒 Bonnes pratiques

  • Ne jamais exposer votre token côté client — l'appel API doit toujours venir de votre serveur, jamais depuis du JavaScript public ou une app mobile.
  • Utilisez l'idempotence sur vos retries — en cas de timeout ou d'erreur réseau, rejouez d'abord la requête avec le même Idempotency-Key et le même contenu. Si l'API retourne IDEMPOTENCY_KEY_STUCK, ne créez pas une nouvelle clé avant d'avoir vérifié vos rapports d'envoi.
  • Testez toujours en sandbox d'abord — paramètre sandbox: 1, réponse identique à un vrai envoi, aucun crédit débité.
  • Stockez les événements webhook pour traitement asynchrone — enregistrez le payload en base à la réception, traitez-le dans un job. Évite les timeouts et garantit la cohérence.
  • Régénérez votre token en cas de compromission — depuis votre espace API, la régénération est immédiate et invalide l'ancien token.

⚠️ Codes HTTP

Les codes HTTP indiquent le résultat au niveau transport. Les codes machine (code dans le body) précisent la raison métier.

CodeDescription
200Succès
201Ressource créée (ex : ajout blacklist)
202Requête acceptée mais résultat d'envoi non confirmé (SEND_STATUS_UNKNOWN). Ne pas renvoyer sans vérifier le rapport.
400Requête malformée (ex : clé d'idempotence trop longue)
402Crédits insuffisants
403Accès refusé (compte non validé, tracker invalide, numéro STOP protégé)
404Ressource introuvable
409Conflit : ressource déjà existante ou gestion de l'idempotence. Voir IDEMPOTENCY_KEY_REUSED, IDEMPOTENCY_KEY_IN_PROGRESS et IDEMPOTENCY_KEY_STUCK.
422Paramètres invalides ou envoi explicitement refusé — voir le champ code dans la réponse
500Erreur interne ou mise en file non confirmée. Avec une clé d'idempotence, ne pas générer automatiquement une nouvelle clé pour renvoyer.
502Erreur fournisseur — voir le champ code ou contacter le support
503Service d'envoi temporairement indisponible

Prêt à intégrer l'API ?

Créez un compte, générez votre clé et envoyez votre premier SMS en quelques minutes.