API SMS Vert Pro V2
API REST en JSON pour l'envoi de SMS professionnels, la gestion des crédits, les rapports de livraison et plus encore.
Télécharger la collection Postman Importez-la dans Postman pour tester l'API en quelques clics (variables base_url, token et email préremplies).
Authentification
L'API supporte deux méthodes d'authentification. Le Bearer Token est recommandé pour la performance et la sécurité.
Méthode 1 : Bearer Token (recommandé)
Envoyez votre token API dans le header HTTP Authorization. C'est la méthode la plus rapide : un seul lookup indexé en base, idéal pour les envois en masse.
Authorization: Bearer votre_token_api_64_caracteres
Le body JSON ne contient plus que la requête :
{
}
Obtenir votre token
POST /api/v2/generate_token
Appelez cet endpoint avec vos identifiants. Le token est permanent : tant que vous ne le renouvelez pas, chaque appel renvoie le même token.
Authorization: Bearer votre_token.
{
"login": {
"user": "votre@email.com",
"pass": "md5_de_votre_mot_de_passe"
}
}
{
"status": "OK",
"token": "a1b2c3d4e5f6...64 caractères"
}
"renew": true au body : un nouveau token est créé et l'ancien cesse immédiatement de fonctionner.
{
"login": {
"user": "votre@email.com",
"pass": "md5_de_votre_mot_de_passe"
},
"renew": true
}
Votre token actuel
Votre token est visible depuis votre compte. Il s'obtient en une fois, et il ne s'affiche jamais en clair sans votre mot de passe.
Voir mon token Créer un compte, 10 SMS offertsMéthode 2 : Login / Password (fallback)
Pour la compatibilité, vous pouvez toujours envoyer vos identifiants dans le body JSON. Le mot de passe doit être en MD5.
{
"login": {
"user": "votre@email.com",
"pass": "md5_de_votre_mot_de_passe"
},
}
Format des requêtes
POST https://www.smsvertpro.com/api/v2/nom_du_endpoint
Exemples : /api/v2/send_sms, /api/v2/credits, /api/v2/generate_token
| Header | Valeur |
|---|---|
Content-Type | application/json |
Authorization | Bearer votre_token_api |
Body JSON avec uniquement les paramètres de l'endpoint :
{
// paramètres spécifiques à l'endpoint
}
Les requêtes comme les réponses sont en UTF-8, avec l'en-tête Content-Type: application/json; charset=UTF-8. Les caractères accentués sont transmis tels quels : configurez votre client en UTF-8 pour les lire correctement.
Si vous n'avez pas encore de Bearer Token, vous pouvez utiliser un fallback login/password :
{
"login": {
"user": "votre@email.com",
"pass": "md5_de_votre_mot_de_passe"
}
}
Codes de statut
Chaque réponse contient un champ status et retourne un code HTTP cohérent. Voici tous les codes possibles :
Succès (2xx)
| Status | HTTP | Description |
|---|---|---|
OK | 200 | Succès générique |
SEND_OK | 200 | SMS envoyé avec succès |
CANCEL_OK | 200 | Annulation de SMS réussie |
OK + result=OTP_SENT | 200 | OTP envoyé par SMS |
OK + result=OTP_TRUE | 200 | Code OTP correct |
OK + result=OTP_VERIFIED | 200 | OTP déjà vérifié précédemment |
Erreurs de requête (400 Bad Request)
| Status | HTTP | Description |
|---|---|---|
MISSING_ELEMENTS | 400 | Paramètres manquants dans la requête |
JSON_ERROR_0 | 400 | JSON invalide ou vide |
JSON_ERROR_1 | 400 | JSON mal formé |
INVALID_EMAIL | 400 | Format d'email invalide |
INVALID_SENDER | 400 | Expéditeur invalide (max 12 caractères) |
INVALID_REQUEST | 400 | Endpoint inconnu |
CONTACT_ERROR | 400 | Aucun destinataire valide |
DELAY_ERROR | 400 | Date d'envoi différé invalide ou passée |
STOPSMS_ERROR | 400 | Mention STOP manquante (route marketing) |
EMOJI_NOT_ALLOWED | 400 | Le message contient des emojis ou caractères non-GSM |
GSM_ERROR | 400 | Format de numéro de téléphone invalide |
INVALID_CREDITS | 400 | Montant de crédits invalide |
INVALID_MASTER | 400 | Compte master invalide |
INVALID_PASSWORD | 400 | Mot de passe invalide (trop court, etc.) |
INVALID_TEL | 400 | Format de téléphone invalide |
INVALID_CODE | 400 | Code parrain invalide |
INVALID_CP | 400 | Code postal invalide |
INVALID_RCS | 400 | Numéro RCS invalide |
FORMAT_ERROR | 400 | Format des paramètres d'envoi invalide |
NO_RECIPIENTS | 400 | Aucun destinataire fourni |
Méthode non autorisée (405)
| Status | HTTP | Description |
|---|---|---|
METHOD_NOT_ALLOWED | 405 | Méthode HTTP non supportée — seul POST est accepté |
Erreurs d'authentification et d'accès (401, 402, 403)
| Status | HTTP | Description |
|---|---|---|
INVALID_USER_OR_PASS | 401 | Email ou mot de passe incorrect |
INVALID_USER | 401 | Utilisateur non authentifié / token invalide |
OTP_FALSE | 401 | Code OTP incorrect |
NOT_ENOUGH_CREDITS | 402 | Solde de crédits insuffisant |
FRAUD_DETECTED | 403 | Tentative de fraude détectée |
Ressources introuvables (404 Not Found)
| Status | HTTP | Description |
|---|---|---|
REPORT_ID_ERROR | 404 | ID de campagne introuvable |
SMS_ID_ERROR | 404 | ID de SMS introuvable |
INVALID_SMS | 404 | SMS introuvable en base |
INVALID_CAMPAIGN | 404 | Campagne introuvable en base |
INVALID_LIST | 404 | Liste de contacts introuvable |
INVALID_CONTACT | 404 | Contact introuvable |
Conflit (409)
| Status | HTTP | Description |
|---|---|---|
OTP_ALREADY_EXIST | 409 | OTP déjà généré pour ce numéro |
ALREADY_SENT | 409 | Envoi déjà parti : l'annulation n'est plus possible |
ALREADY_CANCELLED | 409 | Envoi déjà annulé lors d'un appel précédent |
NOT_CANCELLABLE | 409 | Envoi connu, mais dans un état qui n'autorise pas l'annulation |
Erreurs serveur (500 Internal Server Error)
| Status | HTTP | Description |
|---|---|---|
CAMPAIGN_ERROR | 500 | Erreur lors de la création de la campagne |
SEND_ERROR | 500 | Échec technique d'envoi SMS |
TRANSFER_ERROR | 500 | Échec technique du transfert de crédits |
CANCEL_ERROR | 500 | Échec technique de l'annulation SMS |
ADD_ERROR | 500 | Échec d'ajout en base |
OTP_SEND_ERROR | 500 | Échec d'envoi SMS de l'OTP |
OTP_ERROR | 500 | Erreur générique OTP |
CREATE_ERROR | 500 | Échec de création de ressource |
INSERT_ERROR | 500 | Échec d'insertion en base |
UPDATE_ERROR | 500 | Échec de mise à jour en base |
DELETE_ERROR | 500 | Échec de suppression en base |
AJOUT_ERROR | 500 | Échec de création du compte |
GENERAL_ERROR | 500 | Erreur générique serveur |
UNKNOWN_ERROR | 500 | Erreur d'envoi non identifiée |
Authorization: Bearer votre_token_api (ou un bloc login en fallback). Voir la section Authentification.
Envoi de SMS
POST /api/v2/send_sms
Envoie un ou plusieurs SMS immédiatement ou en différé.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
message.sender | string | Oui | Nom de l'expéditeur (max 12 car.) |
message.text | string | Oui | Contenu du SMS |
message.id | string | Non | Identifiant personnalisé de la campagne. Si non fourni, un identifiant unique est généré automatiquement et retourné dans la réponse. |
message.delay | string | Non | Date d'envoi différé, obligatoirement dans le futur. Format recommandé : YYYY-MM-DD HH:MM:SS. Les formats DD-MM-YYYY HH:MM:SS et DD/MM/YYYY HH:MM:SS sont également acceptés, avec un espace ou un slash entre la date et l'heure. Une date invalide ou déjà passée retourne DELAY_ERROR. |
message.delay_cancel | boolean | Non | Si true, le SMS programmé est annulable |
recipients | array | Oui* | Liste des destinataires (obligatoire si liste_id n'est pas fourni) |
liste_id | integer | Oui* | ID d'une liste de contacts existante (obligatoire si recipients n'est pas fourni). Peut être combiné avec recipients. |
Les destinataires peuvent être envoyés sous trois formats :
"recipients": ["33612345678", "32475123456"]
"recipients": [ { "gsm": "33612345678", "id": "sms_001" }, { "gsm": "33698765432", "id": "sms_002" } ]
Le champ id de chaque destinataire est optionnel. Si non fourni, un identifiant unique par SMS est généré automatiquement. Cet identifiant permet de suivre le statut de délivrabilité de chaque SMS individuellement dans les rapports.
"recipients": [ { "gsm": "0612345678", "country": "FR" }, { "gsm": "0475123456", "country": "BE" }, { "gsm": "079 123 45 67", "country": "CH" } ]
country est fourni (code ISO 2 lettres), les numéros locaux commençant par 0 sont automatiquement convertis au format international. Exemples :-
0612345678 + FR → 33612345678-
0475123456 + BE → 32475123456-
079 123 45 67 + CH → 41791234567Sans
country, seuls les numéros français (06/07) sont convertis automatiquement (compatibilité V1). Les espaces, points, tirets et parenthèses sont nettoyés automatiquement.
Pays supportés : FR, BE, CH, LU, DE, ES, IT, PT, NL, GB, US, CA, IE, AT, PL, MA, TN, DZ, SN, CI, CM, MG, RE, GP, MQ, GF, NC, et 50+ autres.
Exemple - Envoi immédiat
{
"message": {
"sender": "MonEntreprise",
"text": "Bonjour, votre commande est prete. A retirer en magasin.",
"id": "camp_20260402"
},
"recipients": [
"33612345678",
"33698765432"
]
}
{
"status": "SEND_OK",
"credits": 4852,
"id": "camp_1234_1744224000_5678",
"sender": "MonEntreprise",
"nbsms": 2,
"date": "2026-04-02 14:30:00"
}
Note : le champ id contient l'identifiant de la campagne. Si vous n'en avez pas fourni dans message.id, un identifiant unique est généré automatiquement. Conservez cet identifiant pour consulter les rapports de délivrabilité et les réponses SMS.
Exemple - Envoi différé
{
"message": {
"sender": "MonEntreprise",
"text": "Rappel : votre rendez-vous est demain a 10h.",
"id": "camp_rdv_001",
"delay": "2026-04-10 08:00:00",
"delay_cancel": true
},
"recipients": [
{ "gsm": "33612345678", "id": "sms_001" }
]
}
Exemple - Envoi à une liste de contacts
Plutôt que d'envoyer tous les numéros dans la requête, vous pouvez envoyer à une liste existante en passant son liste_id. Tous les contacts de la liste recevront le SMS.
{
"message": {
"sender": "MonEntreprise",
"text": "Nouvelle collection disponible en magasin !"
},
"liste_id": 42
}
liste_id et recipients pour envoyer à une liste + quelques numéros supplémentaires dans le même envoi. La liste doit appartenir au compte authentifié.
Crédits
POST /api/v2/credits
Récupère le solde de crédits SMS du compte, ou de ses sous-comptes.
Paramètres optionnels
| Champ | Type | Description |
|---|---|---|
souscompte | string / true | Email d'un sous-compte spécifique, ou true pour tous les sous-comptes |
Exemple - Solde du compte principal
Aucun paramètre n'est nécessaire : le corps de la requête peut être vide, {} ou null.
{
"status": "OK",
"credits": 4852
}
Exemple - Solde des sous-comptes
{
"souscompte": true
}
{
"status": "OK",
"souscomptes": [
{
"id": 4567,
"email": "filiale@example.com",
"societe": "Filiale Paris",
"credits": 1200
}
]
}
Infos compte
POST /api/v2/infos_compte
Récupère les informations du compte client.
{
"status": "OK",
"nom": "Dupont",
"prenom": "Jean",
"societe": "Ma Société SAS",
"rcs": "123456789",
"adresse": "10 rue de la Paix",
"cp": "75001",
"ville": "Paris",
"type": "normal" // "normal", "master" ou "sous-compte"
}
Tarifs SMS
POST /api/v2/infos_sms
Récupère le tarif unitaire du SMS pour votre compte.
{
"status": "OK",
"prix_sms": 0.063,
"tva": 20,
"smsmin": 1600,
"smsmax": 50000
}
Créer un compte
POST /api/v2/create_account
Crée un nouveau compte client avec un code parrain.
{
"nom": "Dupont",
"prenom": "Jean",
"societe": "Ma Société SAS",
"rcs": "123456789",
"tel": "0612345678",
"adresse": "10 rue de la Paix",
"cp": "75001",
"ville": "Paris",
"email": "jean@societe.com",
"pass": "motdepasse",
"code": "moncode"
}
{
"status": "OK",
"message": "compte créé"
}
| Paramètre | Type | Requis | Description |
|---|---|---|---|
| nom | string | oui | Nom du client |
| prenom | string | oui | Prénom du client |
| societe | string | oui | Nom de la société |
| rcs | string | oui | Numéro RCS (numérique) |
| tel | string | oui | Numéro de téléphone (min 6 chiffres) |
| adresse | string | oui | Adresse postale |
| cp | string | oui | Code postal (min 3 chiffres) |
| ville | string | oui | Ville |
| string | oui | Adresse email (servira de login) | |
| pass | string | oui | Mot de passe (min 6 caractères) |
| code | string | oui | Code parrain |
MISSING_ELEMENTS, INVALID_TEL, INVALID_EMAIL, INVALID_PASSWORD, INVALID_RCS, INVALID_CP, INVALID_CODE, AJOUT_ERROR
Rapports
POST /api/v2/reports
Récupère les rapports de livraison de vos campagnes SMS.
Paramètres optionnels
| Champ | Type | Description |
|---|---|---|
campaign_id | string | ID de campagne spécifique |
message_id | string | ID de message spécifique |
date_start | string | Date de début du filtre, format YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Permet de remonter l'historique au-delà des 12 derniers mois (limite par défaut). |
date_end | string | Date de fin du filtre, format YYYY-MM-DD ou YYYY-MM-DD HH:MM:SS. Si l'heure n'est pas spécifiée, la journée entière est incluse jusqu'à 23:59:59. |
Exemple
Tous les paramètres sont facultatifs : sans aucun filtre (corps vide, {} ou null), l'API renvoie les campagnes des 12 derniers mois.
{
"campaign_id": "camp_20260402"
}
{
"date_start": "2026-01-01",
"date_end": "2026-03-31"
}
{
"status": "OK",
"campaigns": [
{
"id": "camp_20260402",
"date": "2026-04-02 14:30:00",
"sender": "MonEntreprise",
"text": "Bonjour, votre commande est prete.",
"total_credits": 2,
"total_sms": 2,
"sms": [
{
"id": "sms_001",
"gsm": "33612345678",
"sent_date": "2026-04-02 14:30:01",
"done_date": "2026-04-02 14:30:04",
"status": "DELIVERED",
"credits": 1,
"cancelled": false
},
{
"id": "sms_002",
"gsm": "33698765432",
"sent_date": "2026-04-02 14:30:01",
"done_date": null,
"status": "PENDING",
"credits": 1,
"cancelled": false
}
]
}
]
}
Statuts de livraison
| Statut | Description |
|---|---|
DELIVERED | Message remis au destinataire, confirmé par l'accusé de réception. C'est le statut final attendu. |
PENDING | En attente. Deux cas : le message est parti mais l'accusé de réception n'est pas encore revenu (téléphone éteint, hors réseau), ou il s'agit d'un envoi programmé qui n'est pas encore parti. Statut transitoire : il évolue ensuite vers DELIVERED, UNDELIVERABLE ou EXPIRED. |
UNDELIVERABLE | Message non remis : numéro inexistant ou non attribué, terminal incompatible, ou destinataire injoignable de façon définitive. |
EXPIRED | Délai de validité dépassé : le destinataire est resté injoignable pendant toute la période de tentative de remise. Le message n'a pas été délivré. |
REJECTED | Message refusé avant toute tentative de remise. Causes les plus fréquentes : numéro inscrit en liste STOP, numéro au format invalide, nom d'expéditeur non autorisé, ou filtrage appliqué par l'opérateur du destinataire. |
CANCELLED | Envoi programmé annulé avant son départ, via la route cancel. Les crédits sont restitués : le champ cancelled vaut true et credits repasse à 0. |
Cette liste est exhaustive : le champ status ne peut prendre aucune autre valeur. Il n'est jamais null — un message dont l'accusé de réception n'est pas encore parvenu est renvoyé en PENDING.
Seuls DELIVERED, UNDELIVERABLE, EXPIRED, REJECTED et CANCELLED sont des états définitifs. Un message en PENDING doit être réinterrogé ultérieurement pour connaître son issue.
SMS 2-Way (réponses)
POST /api/v2/sms_2way
Récupère les SMS de réponse reçus dans les 3 dernières heures.
{
"status": "OK",
"content": [
{
"id": 12345,
"date": "2026-04-02 15:42:00",
"text": "OK merci",
"gsm": "33612345678"
}
]
}
{
"status": "OK",
"content": [],
"message": "no data"
}
status: "OK" indique que la requête a réussi. Le champ message est uniquement présent quand aucune donnée n'est retournée.
Exemples d'intégration
cURL (ligne de commande)
curl -X POST https://www.smsvertpro.com/api/v2/credits \ -H "Content-Type: application/json" \ -H "Authorization: Bearer VOTRE_TOKEN_API"
PHP
$token = 'VOTRE_TOKEN_API';
$data = [
'message' => [
'sender' => 'MonEntreprise',
'text' => 'Bonjour, votre colis est en livraison.'
],
'recipients' => ['33612345678']
];
$ch = curl_init('https://www.smsvertpro.com/api/v2/send_sms');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = json_decode(curl_exec($ch));
curl_close($ch);
echo $response->status; // SEND_OK
echo $response->credits; // 4851
Python
import requests
token = "VOTRE_TOKEN_API"
data = {
"message": {
"sender": "MonEntreprise",
"text": "Bonjour, votre colis est en livraison."
},
"recipients": ["33612345678"]
}
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {token}"
}
r = requests.post("https://www.smsvertpro.com/api/v2/send_sms", json=data, headers=headers)
print(r.json())
C# / .NET
var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", "VOTRE_TOKEN_API");
var content = new StringContent("{}", Encoding.UTF8, "application/json");
var response = await client.PostAsync(
"https://www.smsvertpro.com/api/v2/credits", content
);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
WinDev (WLangage)
sToken est une chaine = "VOTRE_TOKEN_API"
sJSON est une chaine = [
{
"message": {
"sender": "MonEntreprise",
"text": "Bonjour, votre colis est pret."
},
"recipients": ["33612345678"]
}
]
cRequete est un httpRequete
cRequete.URL = "https://www.smsvertpro.com/api/v2/send_sms"
cRequete.Methode = httpPost
cRequete.ContentType = "application/json"
cRequete.Entete["Authorization"] = "Bearer " + sToken
cRequete.Contenu = sJSON
cReponse est un httpReponse = HTTPEnvoie(cRequete)
SI cReponse.CodeEtat = 200 ALORS
sResultat est une chaine = cReponse.Contenu
Info(sResultat)
FIN
Réponses par campagne
POST /api/v2/responses
Récupère les SMS de réponse reçus, filtrables par campagne.
Paramètres optionnels
| Champ | Type | Description |
|---|---|---|
campaign_id | string | ID de campagne pour filtrer les réponses |
{
"status": "OK",
"responses": [
{
"campaign_id": "camp_001",
"date": "2026-04-02 16:30:00",
"gsm": "33612345678",
"text": "OK merci pour l'info"
}
]
}
{
"status": "OK",
"responses": [],
"message": "no data"
}
Liste noire (STOP SMS)
POST /api/v2/blacklist
Récupère la liste des numéros qui ont envoyé STOP (désinscrits).
{
"status": "OK",
"blacklist": [
{
"gsm": "33612345678",
"date": "2026-03-15 09:12:00",
"text": "STOP"
}
]
}
Ajouter un numéro en liste noire
POST /api/v2/add_blacklist
Ajoute manuellement un numéro dans la liste noire du compte. Les numéros blacklistés sont automatiquement exclus de tous vos envois SMS.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
gsm | string | Oui | Numéro de téléphone au format international (ex: 33612345678) |
{
"gsm": "33612345678"
}
{
"status": "OK",
"gsm": "33612345678"
}
OK avec un champ info précisant que le numéro est déjà présent. Les caractères non numériques (espaces, +, tirets) sont nettoyés automatiquement.
Transfert de crédits
POST /api/v2/transfer
Transfère des crédits SMS du compte master vers un sous-compte.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
email | string | Oui | Email du sous-compte destinataire |
id | integer | Oui | ID du sous-compte destinataire (retourné par add_subaccount ou credits) |
credits | integer | Oui | Nombre de crédits à transférer |
{
"email": "souscompte@email.com",
"id": 4567,
"credits": 500
}
{
"status": "OK",
"message": "transfert effectué",
"credits": 4352 // solde restant du master
}
Annulation de SMS programmés
POST /api/v2/cancel
Annule un SMS spécifique ou une campagne entière programmée (non encore envoyée).
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
campaign_id | string | Oui | ID de la campagne |
sms_id | string | Non | ID d'un SMS spécifique (si absent, annule toute la campagne) |
Annuler toute une campagne
{
"campaign_id": "camp_promo_001"
}
Annuler un SMS spécifique
{
"campaign_id": "camp_promo_001",
"sms_id": "sms_002"
}
{
"status": "CANCEL_OK",
"credits": 4853 // solde du compte après restitution
}
Seuls les SMS programmés et non encore partis sont annulables ; les crédits correspondants sont immédiatement restitués. Après annulation, le rapport renvoie pour ces SMS le statut CANCELLED, cancelled: true et credits: 0. Un campaign_id ou un sms_id inconnu retourne INVALID_CAMPAIGN ou INVALID_SMS (404).
Si l'envoi visé existe bien mais n'est plus annulable, la réponse est un 409 Conflict qui distingue les deux cas :
| Status | HTTP | Situation |
|---|---|---|
ALREADY_SENT | 409 | Le SMS ou la campagne est déjà parti : il n'y a plus rien à annuler ni à restituer. |
ALREADY_CANCELLED | 409 | L'annulation a déjà été faite lors d'un appel précédent ; les crédits ont déjà été restitués à ce moment-là. |
NOT_CANCELLABLE | 409 | L'envoi n'est jamais parti mais n'est plus en attente : il s'est soldé par une erreur d'acheminement. Son statut est consultable dans le rapport. |
Sur une campagne partiellement partie, les SMS encore programmés sont annulés normalement et la réponse reste CANCEL_OK ; ALREADY_SENT n'est renvoyé que lorsqu'il ne reste plus aucun SMS annulable.
Créer un sous-compte
POST /api/v2/add_subaccount
Crée un nouveau sous-compte rattaché au compte master.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
email | string | Oui | Email du sous-compte |
service | string | Oui | Nom de la société / service |
nom | string | Oui | Nom |
prenom | string | Oui | Prénom |
tel | string | Oui | Téléphone (min 6 chiffres) |
pass | string | Oui | Mot de passe (min 6 caractères, sera hashé en MD5) |
{
"email": "filiale@example.com",
"service": "Filiale Lyon",
"nom": "Dupont",
"prenom": "Marie",
"tel": "0612345678",
"pass": "motdepasse123"
}
{
"status": "OK",
"id": 4567
}
id retourné est nécessaire pour les transferts de crédits vers ce sous-compte.
Générer un OTP
POST /api/v2/generate_otp
Génère un code à usage unique et l'envoie par SMS au numéro indiqué. Le code expire après 5 minutes.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
gsm | string | Oui | Numéro de téléphone du destinataire |
sender | string | Non | Expéditeur du SMS (défaut: 36173) |
{
"gsm": "33612345678",
"sender": "MonApp"
}
{
"status": "OK",
"result": "OTP_SENT",
"expires": "2026-04-02 15:05:00"
}
verify_otp pour vérifier le code saisi par l'utilisateur.
Vérifier un OTP
POST /api/v2/verify_otp
Vérifie si le code OTP saisi par l'utilisateur est valide.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
code | string | Oui | Code OTP saisi par l'utilisateur |
gsm | string | Oui | Numéro de téléphone associé |
{
"code": "847392",
"gsm": "33612345678"
}
Réponses possibles
| status | result | Description |
|---|---|---|
OK | OTP_TRUE | Code valide, authentification réussie |
OK | OTP_VERIFIED | Code déjà utilisé (retourne aussi verified_at) |
OTP_FALSE | — | Code invalide ou expiré (HTTP 401) |
{
"status": "OK",
"result": "OTP_TRUE"
}
{
"status": "OK",
"result": "OTP_VERIFIED",
"verified_at": "2026-04-02 15:02:30"
}
Créer une liste de contacts
POST /api/v2/create_list
Crée une nouvelle liste de contacts vide, prête à recevoir des numéros.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
name | string | Oui | Nom de la liste |
{
"name": "Clients VIP Mars 2026"
}
{
"status": "OK",
"liste_id": 123,
"name": "Clients VIP Mars 2026"
}
Ajouter des contacts à une liste
POST /api/v2/add_contacts
Ajoute un ou plusieurs contacts à une liste existante. Les contacts peuvent être envoyés avec des champs personnalisés (info1 à info5) pour le publipostage.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste |
contacts | array | Oui | Liste des contacts à ajouter |
Les contacts peuvent être envoyés sous deux formats :
{
"liste_id": 123,
"contacts": ["33612345678", "33698765432"]
}
{
"liste_id": 123,
"contacts": [
{
"gsm": "33612345678",
"info1": "Marie Dupont",
"info2": "Paris",
"info3": "Client VIP"
},
{
"gsm": "33698765432",
"info1": "Jean Martin",
"info2": "Lyon"
}
]
}
{
"status": "OK",
"added": 2,
"errors": 0
}
info1 à info5 sont optionnels. Ils peuvent être utilisés pour le publipostage dans vos messages SMS (nom, prénom, ville, etc.). Les numéros sont nettoyés automatiquement (espaces, points, tirets supprimés). L'insertion est optimisée par lots de 500 contacts.
Récupérer les contacts d'une liste
POST /api/v2/get_contacts
Récupère tous les contacts d'une liste, avec pagination optionnelle.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste |
limit | integer | Non | Nombre maximum de contacts à retourner (0 = tous) |
offset | integer | Non | Décalage pour la pagination (défaut: 0) |
{
"liste_id": 42,
"limit": 100,
"offset": 0
}
{
"status": "OK",
"liste_id": 42,
"total": 523,
"count": 100,
"contacts": [
{
"id": 1,
"gsm": "33612345678",
"info1": "Jean",
"info2": "Dupont",
"info3": "Paris",
"info4": null,
"info5": null
}
]
}
total contient le nombre total de contacts dans la liste, count le nombre retourné dans cet appel. Utilisez limit et offset pour paginer les listes volumineuses.
Modifier un contact
POST /api/v2/update_contact
Modifie le numéro ou les champs personnalisés d'un contact existant.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste |
contact_id | integer | Oui | ID du contact |
gsm | string | Non | Nouveau numéro |
info1 à info5 | string | Non | Champs personnalisés |
{
"liste_id": 123,
"contact_id": 4567,
"gsm": "33699887766",
"info1": "Marie Martin"
}
{
"status": "OK"
}
Supprimer un contact
POST /api/v2/delete_contact
Supprime un contact d'une liste.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste |
contact_id | integer | Oui | ID du contact à supprimer |
{
"liste_id": 123,
"contact_id": 4567
}
{
"status": "OK"
}
Supprimer une liste de contacts
POST /api/v2/delete_list
Supprime une liste de contacts ainsi que tous les contacts qu'elle contient. Cette action est irréversible.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste à supprimer |
{
"liste_id": 123
}
{
"status": "OK",
"liste_id": 123
}
Vérifier le format des numéros
POST /api/v2/verify_numbers
Vérifie et corrige le format des numéros de téléphone d'une liste de contacts. Identifie les numéros erronés et convertit les numéros français locaux (06/07) au format international (336/337).
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste de contacts |
action | string | Non | "check" (défaut) pour identifier les problèmes, "fix" pour convertir les numéros FR et lister les invalides |
Vérifier (check)
Liste les numéros au mauvais format et indique combien sont convertibles automatiquement.
{
"liste_id": 42
}
{
"status": "OK",
"invalid": [
{ "id": 1234, "gsm": "061234" },
{ "id": 1235, "gsm": "abc123" }
],
"nb_invalid": 2,
"convertible": 15,
"liste_id": 42
}
convertible indique le nombre de numéros au format local français (06/07) qui seront convertis automatiquement avec l'action "fix".
Corriger (fix)
Convertit les numéros FR au format international et retourne la liste des numéros toujours invalides après conversion.
{
"liste_id": 42,
"action": "fix"
}
{
"status": "OK",
"converted": 15,
"invalid": [
{ "id": 1235, "gsm": "abc123" }
],
"nb_invalid": 1
}
0612345678 → 33612345678, 612345678 → 33612345678. Les espaces, points, tirets et le préfixe +33 sont nettoyés automatiquement. Les numéros déjà au format international ne sont pas modifiés.
Nettoyer les contacts en liste noire
POST /api/v2/clean_blacklist
Identifie et supprime d'une liste de contacts les numéros qui ont envoyé STOP (présents dans votre liste noire). Permet de nettoyer vos listes avant un envoi pour éviter les envois inutiles.
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste de contacts |
action | string | Non | "check" (défaut) pour lister les contacts en liste noire, "delete" pour les supprimer |
Vérifier (check)
{
"liste_id": 42
}
{
"status": "OK",
"found": [
{ "id": 1234, "gsm": "33612345678" },
{ "id": 1235, "gsm": "33698765432" }
],
"nb_found": 2,
"liste_id": 42
}
Supprimer (delete)
{
"liste_id": 42,
"action": "delete"
}
{
"status": "OK",
"deleted": 2
}
Dédoublonner une liste de contacts
POST /api/v2/deduplicate
Identifie et supprime les numéros en doublon dans une liste de contacts. Deux modes disponibles : vérification (check) ou suppression (delete).
Paramètres
| Champ | Type | Requis | Description |
|---|---|---|---|
liste_id | integer | Oui | ID de la liste de contacts |
action | string | Non | "check" (défaut) pour lister les doublons, "delete" pour les supprimer |
Vérifier les doublons
{
"liste_id": 42,
"action": "check"
}
{
"status": "OK",
"doublons": [
{ "gsm": "33612345678", "count": 3 },
{ "gsm": "33698765432", "count": 2 }
],
"total": 3,
"liste_id": 42
}
total indique le nombre de contacts en trop (qui seront supprimés). count est le nombre d'occurrences de chaque numéro.
Supprimer les doublons
{
"liste_id": 42,
"action": "delete"
}
{
"status": "OK",
"deleted": 3
}