Documentation de l'API v1

Guide de migration V1 → V2

La v2 n'est pas une réécriture de surface : elle corrige trois défauts structurels de la v1 — l'enveloppe de succès, l'authentification par la barre d'adresse et l'absence d'identifiant de requête. La migration est mécanique, mais elle n'est pas transparente.

Correspondance des points d’entrée

Authentification

Format de réponse

{
  "status": true,
  "code": "SUBMITTED",
  "description": "202: The request has been submitted and is being processed",
  "messageId": "cmd-42",
  "smsCount": 1
}

{
  "id": "msg_2f1c9d4e8a6b",
  "channel": "sms",
  "status": "queued",
  "to": "22960000000",
  "from": "FASTERMSG",
  "units": 1,
  "client_reference": "cmd-42",
  "created_at": "2026-09-07T10:00:00.000Z"
}

• Le succès n'est plus enveloppé : c'est le code HTTP qui porte l'issue.
• Les champs passent en snake_case — la v1 mélangeait camelCase et minuscules collées.
• status change de nature : booléen d'enveloppe en v1, état du message en v2 (queued, delivered…).
• smsCount devient units, et vaut pour les quatre canaux.
• Toute réponse porte un X-Request-Id, à citer au support.

Ruptures de compatibilité

Authentification

La v1 accepte cinq transports pour un même identifiant, essayés dans cet ordre. Cette souplesse est au contrat : des intégrations en place dépendent de chacune de ces variantes.

x-api-key: fm_live_xxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Environnements

Pour éprouver une intégration sans facturer, deux voies : passer un compte en mode test depuis le backoffice, ou — c'est la voie recommandée — écrire l'intégration directement sur la v2.

Le bac à sable ci-dessous vise le même environnement de test que la vue v2 : il vous permet de comparer les deux contrats sur un appel identique.

Essayer l'API

Composez un appel au format v1 et exécutez-le depuis cette page. Le script se régénère en direct dans les quatre langages.

curl -X POST https://api.fastermessage.com/v1/sms/send \
  -H "x-api-key: $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "FASTERMSG",
  "to": "",
  "text": "Votre code est 480912. Valable 5 min."
}'

Envoyer un SMS

Le même envoi existe en GET /v1/sms/send, avec les paramètres en query. Il est maintenu pour les intégrations en place mais ne doit plus être employé : il expose la clé dans l'URL.

Paramètres

curl -X POST https://api.fastermessage.com/v1/sms/send \
  -H "x-api-key: $FM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "FASTERMSG",
  "to": "22960000000",
  "text": "Votre commande cmd-42 est prête.",
  "messageId": "cmd-42",
  "dlrUrl": "https://exemple.test/webhooks/dlr"
}'

const response = await fetch('https://api.fastermessage.com/v1/sms/send', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.FM_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "from": "FASTERMSG",
    "to": "22960000000",
    "text": "Votre commande cmd-42 est prête.",
    "messageId": "cmd-42",
    "dlrUrl": "https://exemple.test/webhooks/dlr"
  }),
});

const data = await response.json();
console.log(response.status, data);

<?php
$ch = curl_init('https://api.fastermessage.com/v1/sms/send');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FM_API_KEY'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'from' => 'FASTERMSG',
    'to' => '22960000000',
    'text' => 'Votre commande cmd-42 est prête.',
    'messageId' => 'cmd-42',
    'dlrUrl' => 'https://exemple.test/webhooks/dlr',
  ]),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL . $response . PHP_EOL;

import os
import requests

response = requests.post(
    "https://api.fastermessage.com/v1/sms/send",
    headers={"x-api-key": os.environ["FM_API_KEY"]},
    json={
            "from": "FASTERMSG",
            "to": "22960000000",
            "text": "Votre commande cmd-42 est prête.",
            "messageId": "cmd-42",
            "dlrUrl": "https://exemple.test/webhooks/dlr",
        },
    timeout=15,
)

print(response.status_code, response.json())

{
  "status": true,
  "code": "SUBMITTED",
  "description": "202: The request has been submitted and is being processed",
  "messageId": "cmd-42",
  "smsCount": 1
}

{
  "status": false,
  "code": "INSUFFICIENT_BALANCE",
  "description": "402: Insufficient balance to process the request",
  "messageId": "cmd-42"
}

Consulter le solde

Renvoie le solde SMS, sans devise ni ventilation par canal — la v2 rend les quatre canaux et la devise du compte.

curl https://api.fastermessage.com/v1/sms/balance \
  -H "x-api-key: $FM_API_KEY"

const response = await fetch('https://api.fastermessage.com/v1/sms/balance', {
  method: 'GET',
  headers: {
    'x-api-key': process.env.FM_API_KEY,
  },
});

const data = await response.json();
console.log(response.status, data);

<?php
$ch = curl_init('https://api.fastermessage.com/v1/sms/balance');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'x-api-key: ' . getenv('FM_API_KEY'),
  ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status . PHP_EOL . $response . PHP_EOL;

import os
import requests

response = requests.get(
    "https://api.fastermessage.com/v1/sms/balance",
    headers={"x-api-key": os.environ["FM_API_KEY"]},
    timeout=15,
)

print(response.status_code, response.json())

{
  "status": true,
  "code": "SUCCESS",
  "description": "200: The operation was successful",
  "balance": 289009
}

Accusés de livraison (DLR)

L'URL déclarée dans dlrUrl est appelée à chaque changement d'état. La méthode est POST par défaut, GET si vous l'avez configuré ainsi.

{
  "uuid": "7d3b5e0c-1a84-4c1e-9f2a-2f1c9d4e8a6b",
  "level": 3,
  "status": "Delivered",
  "receivedAt": "2026-09-07T10:00:06.900Z",
  "messageId": "cmd-42",
  "to": "22960000000",
  "smsCount": 1
}

Quatre champs sont toujours présents : uuid, level, status et receivedAt. Les autres n'apparaissent que si vous les avez activés dans vos variables DLR, depuis le backoffice.

Variables DLR activables

Sécurité

Chaque rappel porte l'en-tête X-Fastermessage-Signature — un HMAC-SHA256 de la charge utile — et s'annonce par l'agent Fastermessage-DLR/1.0. Vérifiez la signature avant de traiter, et servez votre point de terminaison en HTTPS.

Codes de statut

Chaque réponse porte un code et une description formatée "<code HTTP>: <message>". Ces valeurs sont gelées : ni les libellés, ni les codes HTTP ne changeront, y compris pour corriger une formulation — des intégrations les comparent à des chaînes fixes.

Codes d’envoi

Codes de refus

Limites

Le débit est plafonné par compte. Un dépassement répond RATE_LIMIT_EXCEEDED en 429.

• Pas d'envoi en lot : un message par appel.
• Pas d'idempotence : un rejeu après coupure réseau renvoie et refacture le message.
• Pas d'identifiant de requête : un incident ne peut pas être corrélé à nos journaux.

Ces trois manques sont comblés par la v2 — voir le guide de migration.