Aller au contenu principal
SMSverifica
Pour les développeurs

API SMS en Espagne : une API REST de messagerie multicanal pour SMS, WhatsApp et Telegram

Intégrez l’envoi de SMS, de WhatsApp Business API et de Telegram avec une seule API REST en JSON : authentification par X-Api-Key, idempotence native, webhooks de statut signés en HMAC-SHA256, limite de débit configurable, erreurs claires et mode sandbox pour intégrer sans dépenser un euro.

Créez votre compte gratuit Comment fonctionne le mode sandbox
  • Idempotence native
  • Webhooks signés HMAC-SHA256
  • Sandbox sans frais
  • Solde sans expiration

📘 Documentation de l’API

Authentification, endpoints et exemples curl prêts à copier, pas à pas.

✉️ Envoi unitaire

POST /messages : votre premier SMS en cinq minutes, avec idempotence.

🚀 Envoi en masse (bulk)

POST /messages/bulk : jusqu’à 5 000 SMS en un seul appel, avec relance sûre.

📜 SMS certifiés via l’API

Notifications et contrats à valeur probante, depuis le même jeton.

📣 Campagnes depuis le web

Le même message à des centaines ou des milliers de personnes, sans programmer : listes, fichier ou saisie manuelle.

🧪 Sandbox

Intégrez et testez tout le parcours sans dépenser et sans que rien n’arrive à personne.

Envoyez votre premier SMS avec l’API REST en cinq minutes

Pas de SDK obligatoire, pas de liste blanche d’IP, pas besoin de parler au commercial pour activer des canaux : une requête HTTPS en JSON et votre message est en file d’attente.

1. Créez votre compte

Inscrivez-vous gratuitement. Le compte naît en attente et une personne l’examine avant d’activer l’envoi réel ; le mode sandbox vous permet d’intégrer et de tester l’API sans dépenser de solde et sans qu’aucun message ne parte.

2. Copiez vos identifiants

Dans le tableau de bord, vous trouverez votre api_key (format sk_live_…) et votre api_secret. Ils s’envoient dans les en-têtes X-Api-Key et X-Api-Secret de chaque requête, toujours en HTTPS. Le secret n’est affiché qu’une seule fois, au moment de sa génération. Si vous venez d’une autre plateforme, ce sont les deux mêmes champs que vous avez déjà configurés : seules les valeurs changent.

3. Faites le POST

Appelez POST /api/v1/messages avec le canal, le destinataire au format E.164 et le texte. L’expéditeur va dans from et il est facultatif : si vous ne l’indiquez pas, l’expéditeur par défaut de la plateforme est utilisé. La réponse vous renvoie le message créé, son coût en euros et son statut.

terminal — envoyer un SMS
curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: pedido-1234-confirmacion" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "to": "+34612345678",
    "from": "MITIENDA",
    "body": "Votre commande 1234 a été expédiée. Vous la recevrez demain avant 14h00."
  }'
réponse — 201 Created
{
  "data": {
    "id": 98231,
    "channel": "sms",
    "direction": "out",
    "to": "+34612345678",
    "from": "MITIENDA",
    "status": "queued",
    "cost_eur": "0.0390",
    "queued_at": "2026-07-08T10:15:02+02:00",
    "created_at": "2026-07-08T10:15:02+02:00"
  }
}

Le destinataire est normalisé au format E.164 et l’indicatif du pays est détecté automatiquement pour appliquer le bon tarif (consultez les tarifs SMS par pays). Le coût est déduit de votre solde de façon transactionnelle à la mise en file et, si le message échoue définitivement, il est remboursé automatiquement.

Une seule API de messagerie multicanal : SMS, WhatsApp Business API et Telegram

Le même endpoint, le même JSON et les mêmes webhooks pour les trois canaux : passer du SMS à WhatsApp ou à Telegram, c’est changer la valeur d’un champ. Une API WhatsApp Business et une API Telegram qui ne vous obligent pas à apprendre trois intégrations différentes.

Envoyer un modèle WhatsApp Business API

Envoyez des modèles approuvés par Meta avec des variables et indiquez la catégorie de conversation pour une tarification exacte par message (prix WhatsApp par catégorie). Le texte libre dans la fenêtre de service de 24 heures est également pris en charge.

terminal — envoyer un WhatsApp avec un modèle
curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: entrega-5566-aviso" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp",
    "to": "+34612345678",
    "template_name": "aviso_entrega",
    "template_vars": { "1": "Maria", "2": "jeudi de 9h00 à 14h00" },
    "category": "utility"
  }'

Envoyer un message Telegram (0,010 € par message)

Connectez votre propre bot et envoyez des notifications Telegram à 0,010 € par message. Notre webhook Telegram capture automatiquement le chat_id lorsque le client démarre une conversation avec votre bot ; ensuite, vous envoyez en utilisant son numéro de téléphone comme référence.

terminal — envoyer un Telegram
curl -X POST https://app.smsverifica.com/api/v1/messages \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Idempotency-Key: visita-889-recepcion" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "telegram",
    "to": "+34612345678",
    "body": "Votre visiteur vient d’arriver à l’accueil. Avis automatique de QRACCESO."
  }'

Consulter votre solde

terminal — solde du compte
curl https://app.smsverifica.com/api/v1/account/balance \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret"

# {"data":{"balance_eur":"842.3100"}}

Créer une campagne complète en une seule requête

C’est rare sur le marché espagnol : une vraie API de campagnes. Avec POST /api/v1/campaigns, vous lancez un envoi en masse à toute une liste de contacts, avec programmation de la date et vérification préalable du solde ; la plateforme calcule le coût, met les messages en file et met à jour en temps réel les compteurs d’envoyés, remis, échoués et lus.

terminal — créer une campagne programmée
curl -X POST https://app.smsverifica.com/api/v1/campaigns \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "sms",
    "name": "Rappel contrôle technique octobre",
    "contact_list_id": 42,
    "body": "Votre contrôle technique expire ce mois-ci. Prenez rendez-vous dans votre garage habituel.",
    "scheduled_at": "2026-10-01T09:00:00+02:00"
  }'

# {"data":{"id":57,"status":"scheduled","total":1840,"cost_estimate":"71.7600", ...}}

Si vous préférez commencer par le tableau de bord avant d’intégrer, le manuel d’utilisation passe en revue chaque écran avec des captures.

La messagerie certifiée via l’API : deux endpoints et en production

La messagerie certifiée —dossier de preuves chaînées et PDF vérifiable— est incluse dans la même API REST, sans modules séparés ni contrats supplémentaires : tous les fournisseurs ne la proposent pas via l’API, et ceux qui avaient intégré celle d’un autre et en ont été privés peuvent migrer ici avec deux endpoints. Le supplément de certification est de 0,25 € par message, identique sur les trois canaux, en plus du prix du canal.

terminal — envoyer une notification certifiée
curl -X POST https://app.smsverifica.com/api/v1/certified \
  -H "X-Api-Key: sk_live_tu_api_key" \
  -H "X-Api-Secret: tu_api_secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: notif-2026-0001" \
  -d '{
    "channel": "sms",
    "to": "+34612345678",
    "subject": "Mise en demeure de payer",
    "content": "Texte intégral qui sera certifié dans le dossier."
  }'

# {"data":{"id":31,"status":"queued","content_hash":"5f1c…","portal_url":"…/c/…", ...}}
# Le PDF de preuves, quand vous en avez besoin : GET /api/v1/certified/31/certificate

Disponible aujourd’hui uniquement vers l’Espagne (+34) et en tant que service d’envoi recommandé électronique non qualifié (art. 3.36 du règlement eIDAS), avec un horodatage qualifié de Camerfirma sur chaque dossier — les limites et ce que prouve chaque élément, sur la page de la messagerie certifiée.

Tous les endpoints de l’API v1

Endpoints de l’API REST v1 (préfixe /api/v1)
Méthode et cheminCe qu’il fait
POST /messagesEnvoie un SMS, un WhatsApp ou un Telegram. Accepte Idempotency-Key.
GET /messages/{id}Consulte un message : statut, coût, horodatages de tout son cycle de vie.
GET /messagesListe vos messages avec pagination et filtres.
POST /campaignsCrée et confirme une campagne en masse sur une liste de contacts, avec programmation facultative.
GET /campaigns/{id}Statistiques de campagne : envoyés, remis, échoués, lus et coût.
POST /verify/startEnvoie un code OTP de vérification par SMS, WhatsApp ou Telegram.
POST /verify/checkVérifie le code OTP (un code erroné est un 200 avec status: invalid).
POST /certifiedEnvoie une communication certifiée : dossier de preuves + portail du destinataire.
GET /certified/{id}Statut du dossier certifié : ouvertures, lecture, signature.
GET /certified/{id}/certificateTélécharge le PDF de preuves (émis à la demande).
GET /account/balanceSolde en euros, en temps réel.
GET /pricing/smsTarifs SMS par indicatif de pays, toujours à jour.
GET /sendersVos expéditeurs et leur statut au Registre des alias de la CNMC : s’ils partiraient avec votre marque, avec l’expéditeur de secours ou s’ils seraient rejetés lors d’un envoi vers l’Espagne.
GET /senders/checkLa même chose pour un envoi précis (from et to), avant de l’envoyer.

Idempotence native : réessayez sans crainte d’envois en double

Un délai réseau dépassé au pire moment et votre client reçoit deux fois le même SMS... que vous payez deux fois. Avec SMSverifica, cela ne peut pas arriver.

Ajoutez l’en-tête Idempotency-Key à votre POST /messages avec un identifiant unique de votre opération (par exemple, pedido-1234-confirmacion). Si vous répétez la requête — parce que votre tâche l’a relancée, parce qu’il y a eu un délai dépassé, parce que votre processus a redémarré — l’API ne crée pas de second message et ne facture pas deux fois : elle vous renvoie la réponse d’origine avec l’en-tête X-Idempotency-Replayed: true.

C’est une idempotence d’envoi native, intégrée à l’API elle-même, et c’est un vrai facteur de différenciation : aucun des fournisseurs espagnols de SMS ne la documente dans son API, pas plus que les grandes plateformes internationales de messagerie sur leur endpoint d’envoi. Si vous construisez des systèmes sérieux — files d’attente, relances avec backoff, workers — vous savez exactement pourquoi c’est important.

La vérification, documentation à l’appui et avec la date de consultation, figure dans les comparatifs avec Twilio, LabsMobile, Esendex, Instasent et BulkGate (en espagnol).

seconde requête identique — réponse rejouée
# On répète le même POST avec la même Idempotency-Key
curl -i -X POST https://app.smsverifica.com/api/v1/messages \
  -H "Idempotency-Key: pedido-1234-confirmacion" \
  ...

HTTP/2 201
X-Idempotency-Replayed: true

# Même JSON, même message id : zéro doublon, zéro double facturation

Webhooks de statut signés en HMAC-SHA256, avec relances et renvoi manuel

Recevez sur votre serveur chaque transition de statut — message.sent, message.delivered, message.failed, message.read, message.received et campaign.completed — avec une signature cryptographique qui vous permet de vérifier que l’avis est authentique. Parmi les fournisseurs espagnols dont nous avons examiné la documentation en juillet 2026, aucun ne signait ses notifications de remise ; nous les signons toutes.

POST vers votre endpoint — payload signé
X-Signature: sha256=7f83b1657ff1fc53b92dc18148a1d6...
Content-Type: application/json

{
  "event": "message.delivered",
  "delivery_id": 4521,
  "timestamp": "2026-07-08T10:15:09+02:00",
  "data": {
    "id": 98231,
    "channel": "sms",
    "to": "+34612345678",
    "status": "delivered",
    "delivered_at": "2026-07-08T10:15:08+02:00"
  }
}
vérifier la signature en PHP
// Vous définissez le secret par webhook dans votre tableau de bord
$cuerpo = file_get_contents('php://input');
$esperada = 'sha256=' . hash_hmac('sha256', $cuerpo, $secreto);

if (hash_equals($esperada, $_SERVER['HTTP_X_SIGNATURE'] ?? '')) {
    // Payload authentique : traitez l’événement
}

Signature HMAC-SHA256

Chaque remise porte l’en-tête X-Signature: sha256=<hmac> calculé sur le corps exact avec votre secret. La vérifier tient en trois lignes de code dans n’importe quel langage.

Relances automatiques

Si votre endpoint ne répond pas 2xx, nous réessayons jusqu’à 5 fois avec des attentes croissantes (1 min, 5 min, 15 min, 1 h, 4 h). Sémantique at-least-once : utilisez delivery_id pour dédoublonner.

Journal et renvoi manuel

Chaque tentative est enregistrée dans votre tableau de bord avec le code de réponse et la date. Votre serveur était en panne ? Renvoyez la remise manuellement en un clic, sans ouvrir de ticket.

Mode sandbox : intégrez l’API sans dépenser un seul euro

Un environnement de simulation documenté, sans frais : intégrez et testez sans dépenser de solde et sans qu’aucun vrai message ne parte.

Avec le mode sandbox activé, vos requêtes à l’API se comportent exactement comme en production — mêmes endpoints, mêmes réponses, mêmes webhooks signés — mais aucun message ne part sur le réseau et le coût est de 0,0000 de solde. Le simulateur parcourt tout le cycle de vie du message : queued → sent → delivered (ou failed/read), en déclenchant vos webhooks à chaque transition pour que vous testiez votre intégration de bout en bout.

Vous disposez aussi de numéros de test (magic numbers) qui forcent chaque statut final — remis, échoué, lu — pour vérifier comment votre application réagit à chaque scénario, y compris le remboursement automatique d’un envoi échoué. Le tout documenté dans votre tableau de bord, sans carte bancaire et sans expiration du compte de test.

Comment ça marche, sans fioritures : l’inscription crée le compte au statut en attente et en mode sandbox ; en sandbox, aucun message ne part et aucun solde n’est dépensé. Une personne examine l’inscription avant d’activer l’envoi réel. Pour toute question, écrivez-nous.

Créez votre compte gratuit

Ce que vous pouvez tester en sandbox

  • Envois SMS, WhatsApp et Telegram avec une vraie réponse JSON
  • Webhooks de statut signés à chaque transition
  • Statuts forcés avec des numéros de test : remis, échoué, lu
  • Idempotence avec Idempotency-Key et réponses rejouées
  • Campagnes complètes avec estimation du coût
  • Gestion des erreurs : 402, 422, 429 et validations par champ

Des erreurs JSON claires et une limite de débit configurable par compte

Toutes les erreurs partagent le même format — {"error":{"code":"<slug>","message":"..."}} — avec un code stable sur lequel programmer et un message lisible par un humain. Les validations incluent le détail par champ.

Codes d’erreur de l’API v1
HTTPCodeQuand cela arrive
401unauthorizedClé d’API ou secret invalides.
402insufficient_balanceSolde insuffisant : le message ou la campagne n’est pas mis en file. Il n’y a jamais d’envois à moitié faits.
403account_not_activeCompte en attente de validation ou suspendu.
404not_foundLa ressource n’existe pas ou appartient à un autre compte (isolation multi-tenant).
422validation_failedDonnées invalides ; inclut details avec les erreurs par champ.
422wa_outside_windowTexte libre WhatsApp hors de la fenêtre de service de 24 h : utilisez un modèle.
422telegram_no_chat_idLe contact n’a pas encore démarré de conversation avec votre bot Telegram.
422no_providerAucun fournisseur n’est configuré pour ce canal sur votre compte.
422no_pricingIndicatif de destination sans tarif : nous n’envoyons jamais à l’aveugle, ni gratuitement par erreur.
429rate_limitedVotre limite de requêtes par minute est dépassée.

Une limite de débit par compte, pas par plateforme

Chaque compte a sa propre limite — 60 requêtes par minute par défaut, extensible selon votre volume réel —, de sorte que le trafic des autres clients n’affecte jamais le vôtre. Pour les envois en masse, inutile de marteler l’API : POST /campaigns expédie des milliers de messages en une seule requête et avec un débit maîtrisé vers les opérateurs.

402 : pas de solde, pas de surprise

Si votre solde ne couvre pas l’envoi, vous recevez immédiatement un 402 insufficient_balance et rien n’est mis en file. La déduction du solde est transactionnelle, avec remboursement automatique si le message échoue définitivement, et vous pouvez activer la recharge automatique avec seuil pour que le solde ne vous freine jamais. Consultez le modèle de solde sans expiration.

Une plateforme multi-tenant avec des comptes validés manuellement

La qualité de remise de vos SMS dépend de la réputation des routes. C’est pourquoi nous ne laissons pas entrer n’importe qui.

Chaque inscription chez SMSverifica est examinée par une personne avant l’activation du compte. Ce filtre antispam garde nos routes et nos expéditeurs propres, et vise à ce que votre trafic légitime —vos OTP, vos avis de livraison, vos campagnes— ne partage pas de route avec des envois indésirables. Le mode sandbox n’attend pas cet examen : il s’ouvre de lui-même quand vous vérifiez votre e-mail, et l’examen humain débloque ensuite l’envoi réel et les paiements.

L’isolation entre comptes est totale : vos messages, contacts, campagnes et identifiants vivent sous votre account_id et sont invisibles pour tout autre compte. Les identifiants de canal sont stockés chiffrés en base de données et vous pouvez faire tourner votre api_secret depuis le tableau de bord à tout moment.

  • Validation manuelle antispam : meilleure réputation des routes et des expéditeurs
  • Isolation multi-tenant vérifiée par des tests automatiques
  • Identifiants chiffrés et rotation des secrets en libre-service
  • RGPD et LSSI : serveurs dans l’UE et facturation espagnole avec TVA
  • Routage configurable par canal : chaque compte définit son fournisseur principal et, s’il en a souscrit un second, un fournisseur de secours au sein du même canal
  • Solde sans expiration : votre solde d’intégration n’expire jamais

Questions fréquentes sur l’API SMS et de messagerie

Puis-je utiliser l’API SMS depuis PHP, Python, Node.js ou tout autre langage ?

Oui. C’est une API REST standard en JSON sur HTTPS : tout langage capable de faire une requête HTTP peut envoyer des SMS, des WhatsApp et des Telegram. Les exemples curl de cette page se transposent tels quels en PHP (cURL/Guzzle), Python (requests), Node.js (fetch/axios), Java, C# ou Go.

Ai-je besoin d’une carte bancaire pour tester l’API ?

Non, et le mode sandbox non plus : il simule tout le cycle de vie du message (en file, envoyé, remis, échoué, lu) à coût nul et sans qu’aucun vrai message ne parte. L’envoi réel est activé quand une personne examine et valide votre compte.

Comment recevoir les statuts de remise des messages ?

De deux façons : en interrogeant GET /api/v1/messages/{id} ou, mieux, en recevant des webhooks de statut sur votre serveur (message.sent, message.delivered, message.failed, message.read, message.received et campaign.completed). Chaque webhook est signé en HMAC-SHA256 dans l’en-tête X-Signature et relancé automatiquement avec des attentes croissantes si votre endpoint ne répond pas.

Que se passe-t-il si mon compte n’a plus de solde ?

L’API répond 402 avec le code insufficient_balance et le message n’est pas mis en file : jamais d’envois à moitié faits ni de surprises de facturation. Vous pouvez activer la recharge automatique avec seuil pour que le solde se reconstitue de lui-même.

Quelle limite de requêtes a l’API ?

Chaque compte a sa propre limite de débit, 60 requêtes par minute par défaut, extensible sur demande selon votre volume. Si vous la dépassez, vous recevez un 429 (rate_limited) standard. Pour les envois en masse, utilisez POST /campaigns : une seule requête pour des milliers de destinataires.

Que se passe-t-il si j’envoie deux fois la même requête POST /messages ?

Si vous incluez l’en-tête Idempotency-Key, la seconde requête ne génère ni envoi ni facturation en double : l’API renvoie la réponse d’origine avec l’en-tête X-Idempotency-Replayed: true. C’est l’idempotence native de l’API, idéale pour des relances sûres après un délai dépassé.

Créez votre compte et envoyez votre premier SMS via l’API

Un compte gratuit et sans carte, un mode sandbox sans carte bancaire, une inscription vérifiée à la main, un solde sans expiration et une assistance en espagnol par des gens qui ont lu la même documentation que vous. Vous mettez en place une vérification des utilisateurs ? Voyez aussi l’API de vérification OTP par SMS.

Créez votre compte gratuit API de vérification OTP