API SMS pour la Nouvelle-Calédonie
Votre logiciel envoie, SMS PRO achemine et vous dit ce qui est arrivé.
Mis à jour le · Équipe SMS PRO
Spécification OpenAPI 3.1 publique. Clés créées par vous, une fois votre compte ouvert par notre équipe à Nouméa.
Comment ça marche, en trois étapes
Une fois votre compte ouvert, votre premier SMS part depuis votre propre code.
- Nous ouvrons votre compte.
Notre équipe crée votre organisation et déclare votre nom d'expéditeur auprès de l'opérateur, puis le vérifie par un envoi réel.
- Vous créez une clé.
Depuis votre espace client : un nom par intégration, des droits limités à ce dont elle a besoin, et si vous le voulez, les adresses IP de vos serveurs.
- Votre logiciel appelle l'API.
Un appel pour envoyer, un webhook pour savoir ce qui est arrivé. Les numéros invalides ou désinscrits sont écartés et comptés dans la réponse, sans faire échouer l'appel.
Envoyer un SMS en un appel
Un expéditeur, un message, des destinataires. Le même appel en cURL, en PHP ou en JavaScript : choisissez votre langage.
# SMSPRO_API : l'adresse de base indiquée dans la spécification OpenAPI
# SMSPRO_CLE : une clé créée dans votre espace client
curl -X POST "$SMSPRO_API/messages" \
-H "Authorization: Bearer $SMSPRO_CLE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: commande-1042" \
-d '{
"sender": "BOUTIK EX",
"message": "Boutique Exemple : votre commande 1042 est partie. Suivez-la ici : brf.nc/Ex7k",
"recipients": ["+687560001"]
}'<?php
// SMSPRO_API : l'adresse de base indiquée dans la spécification OpenAPI
$ch = curl_init(getenv('SMSPRO_API') . '/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('SMSPRO_CLE'),
'Content-Type: application/json',
'Idempotency-Key: commande-' . $commande['id'],
],
CURLOPT_POSTFIELDS => json_encode([
'sender' => 'BOUTIK EX',
'message' => "Boutique Exemple : votre commande {$commande['id']} est partie. Suivez-la ici : brf.nc/Ex7k",
'recipients' => [$client['mobile']],
]),
]);
$envoi = json_decode(curl_exec($ch), true);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) !== 201) {
// Erreur normalisée : se brancher sur 'code', jamais sur 'detail'
error_log("Envoi refusé : {$envoi['code']}");
}// Node.js 18 ou plus. SMSPRO_API : l'adresse de base indiquée dans la spécification OpenAPI
const reponse = await fetch(`${process.env.SMSPRO_API}/messages`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.SMSPRO_CLE}`,
'Content-Type': 'application/json',
'Idempotency-Key': `commande-${commande.id}`,
},
body: JSON.stringify({
sender: 'BOUTIK EX',
message: `Boutique Exemple : votre commande ${commande.id} est partie. Suivez-la ici : brf.nc/Ex7k`,
recipients: [client.mobile],
}),
});
const envoi = await reponse.json();
if (reponse.status !== 201) console.error('Envoi refusé :', envoi.code);Ce que l'API vous répond
HTTP/1.1 201 Created
{
"id": "1364012",
"status": "accepted",
"sender": "BOUTIK EX",
"encoding": "GSM-7",
"parts_per_message": 1,
"accepted_recipients": 1,
"stopped_recipients": 0,
"invalid_recipients": [],
"created_at": "2026-11-11T08:30:00+11:00"
}« accepted » veut dire accepté et mis en file, pas encore arrivé sur le téléphone. La réponse dit combien de destinataires partent, combien sont écartés parce que désinscrits, quels numéros sont illisibles, et en combien de SMS le message est découpé.
Ce que reçoit votre client
78 caractères · 1 SMS
L'adresse de base, les noms des champs et tous les codes de réponse figurent dans la spécification OpenAPI. Les numéros s'écrivent au format international (+687560001) ou à 6 chiffres. Un champ facultatif programme l'envoi à une date et une heure données, horodatage avec son décalage : UTC+11 pour Nouméa.
Savoir ce qui est arrivé
Ne sondez pas l'API en boucle : c'est elle qui vous prévient.
Pour les SMS envoyés vers un mobile calédonien, l'opérateur renvoie un accusé de livraison. SMS PRO le rattache au message, date la réception et prévient votre logiciel par un webhook. Vous choisissez les événements qui vous intéressent :
- un envoi créé, terminé ou en échec ;
- un SMS transmis, délivré ou en échec, destinataire par destinataire ;
- une réponse à un questionnaire envoyé par lien ;
- le résultat d'un test entre deux messages.
Chaque notification est signée par un HMAC-SHA256 horodaté : votre serveur vérifie qu'elle vient bien de SMS PRO et refuse un message rejoué. Un bouton « Tester » envoie une notification de test à votre adresse, et l'historique des livraisons montre le code HTTP renvoyé par votre serveur : après une panne de votre côté, vous rejouez les notifications perdues.
Besoin d'une réponse ponctuelle ? L'API vous dit si un destinataire précis a reçu le SMS. Sans accusé, l'état reste « transmis » : nous n'écrivons jamais « délivré » sans que le réseau l'ait confirmé. Les états se lisent comme dans l'application : reçu, non délivré ou non confirmé.
curl -X POST "$SMSPRO_API/webhooks" \
-H "Authorization: Bearer $SMSPRO_CLE" \
-H "Content-Type: application/json" \
-d '{
"name": "Suivi des commandes",
"url": "https://votre-domaine.example/sms/retour",
"events": ["sms.delivered", "sms.failed"]
}'<?php
// $signature : valeur de l'en-tête de signature (son nom figure dans la documentation)
// $secret : le secret affiché une seule fois à la création du webhook
[$t, $v1] = sscanf($signature, 't=%d,v1=%s');
$attendu = hash_hmac('sha256', $t . '.' . file_get_contents('php://input'), $secret);
if (!hash_equals($attendu, $v1) || abs(time() - $t) > 300) {
http_response_code(403); // signature fausse, ou message trop ancien : rejeu refusé
exit;
}
http_response_code(200);curl "$SMSPRO_API/messages/1364012/deliveries?phone=%2B687560001" \
-H "Authorization: Bearer $SMSPRO_CLE"
{
"deliveries": [
{
"recipient": "+687560001",
"state": "delivered",
"parts": 1,
"sent_at": "2026-11-11T08:30:01+11:00",
"delivered_at": "2026-11-11T08:31:12+11:00",
"error": null
}
]
}Pas de double envoi
Un délai d'attente dépassé ne vous dit pas si l'envoi a eu lieu. Avec une clé d'idempotence, un appel rejoué n'envoie pas deux fois.
| Votre logiciel envoie | L'API répond |
|---|---|
| Une clé jamais vue | L'envoi est traité normalement. La réponse est mémorisée. |
| La même clé, avec le même contenu | La réponse d'origine revient telle quelle, marquée comme rejouée. Rien n'est exécuté une seconde fois. |
| La même clé, avec un autre contenu | L'appel est refusé : c'est une erreur d'intégration, et l'API vous le dit. |
| La même clé, pendant que le premier appel est en cours | L'API vous demande de patienter et indique dans combien de temps réessayer. |
La règle est simple : une clé nouvelle par opération métier (une commande, une relance, un rendez-vous), et la même clé pour chaque nouvelle tentative de cette opération. Un identifiant unique de votre base fait très bien l'affaire.
Des clés à votre image
Une clé par intégration : vous savez laquelle appelle quoi, et vous en coupez une sans arrêter les autres.
- Des clés multiples, chacune nommée : site de vente, logiciel de caisse, outil de gestion.
- Des droits par clé : envoyer, consulter les envois, gérer les contacts, gérer les webhooks. La clé d'un site vitrine n'a aucune raison de lire autre chose que ce qu'elle envoie.
- La restriction par adresse IP, gérée par vous : une adresse exacte ou un bloc, en IPv4 comme en IPv6.
- Une clé affichée une seule fois. Nous n'en gardons qu'une empreinte : personne, chez nous non plus, ne peut vous la relire.
- Un changement de clé sans coupure : créez la nouvelle, basculez, vérifiez, puis révoquez l'ancienne.
Comment sont protégés vos secrets et vos données : sécurité et stockage en Nouvelle-Calédonie.
Une liste STOP partagée
Une personne qui s'est désinscrite ne reçoit plus rien, qu'elle soit visée par l'application ou par votre code.
La liste STOP de votre organisation vaut pour tous ses comptes et pour toutes ses clés. Un numéro désinscrit est écarté de l'envoi et compté dans la réponse : votre logiciel sait combien de destinataires ont été retenus, sans avoir à tenir sa propre liste.
L'API permet de consulter cette liste, d'y ajouter des numéros, ou de remplacer en une fois les numéros que vous avez importés. Un tel remplacement ne touche que vos imports : une personne qui s'est désinscrite elle-même par le lien STOP de l'organisation reste désinscrite. Un réimport fait par erreur ne peut pas la remettre dans vos envois.
Ce que couvre l'API
De quoi brancher un logiciel métier entier, pas seulement un bouton « envoyer ».
Envois
Envoyer tout de suite ou à une date choisie, lister vos envois, suivre un envoi, annuler ceux qui sont encore en file.
Destinataires
L'état de chaque destinataire, ou d'un seul, avec la date de l'accusé et un motif d'échec en français, prêt à afficher.
Groupes de contacts
Créer un groupe, y ajouter ou retirer des contacts, nommer vos colonnes pour en faire des champs du message.
Liste STOP
Consulter, compléter, remplacer vos imports, sans jamais toucher aux désinscriptions volontaires.
Pièces jointes
Déposer un fichier et obtenir un lien court en doc.nc, fait pour tenir dans un SMS.
Webhooks
Créer un abonnement, voir les livraisons et leurs échecs, rejouer une notification.
Des conventions sans surprise
- JSON en entrée et en sortie, noms de champs en snake_case, identifiants en chaînes de caractères.
- Horodatages au format RFC 3339 avec leur décalage : la Nouvelle-Calédonie est à UTC+11 toute l'année.
- Erreurs au format RFC 9457, avec un code stable sur lequel brancher votre logique, et un détail lisible par un humain.
- Limitation de débit annoncée par des en-têtes standard ; au dépassement, l'API indique quand réessayer.
- Pagination par curseur sur les grandes listes : aucun élément sauté ni dupliqué pendant que vous parcourez.
- Un identifiant de requête dans chaque réponse : citez-le à notre équipe, elle retrouve votre appel.
Pour les éditeurs et les intégrateurs
Vous équipez plusieurs organisations ? Chacune garde son compte, son contrat et ses envois.
Un espace groupement vous permet de suivre plusieurs organisations indépendantes depuis un même accès. Chaque organisation garde son propre contrat, ses noms d'expéditeur, sa liste STOP et son historique. L'API vous donne, en lecture, l'activité des organisations que vous suivez.
Vos clients veulent envoyer sous leur propre nom ? Chaque nom d'expéditeur se déclare avant le premier envoi : transmettez-nous la liste, nous déclarons chaque nom et le vérifions par un envoi réel. Un nom non déclaré peut être accepté par un appel et ne jamais arriver sur le téléphone. C'est pourquoi l'API refuse un expéditeur qui n'est pas attribué à votre compte.
Votre logiciel publie un agenda plutôt que d'appeler une API ? Il existe d'autres façons de relier un agenda ou un logiciel métier.
Où partent vos SMS, où restent vos données
Les SMS vers les mobiles calédoniens partent en direct par l'opérateur local. Les SMS vers l'étranger empruntent un acheminement international.
Vos données sont stockées en Nouvelle-Calédonie, dans le cloud souverain STRATOS : vos envois, leurs accusés, vos contacts et vos journaux. Les clés API n'y sont conservées que sous forme d'empreinte.
L'état du service est public : consultez la page d'état avant de chercher une panne dans votre code.
Qui s'en sert
Éditeurs de logiciels métier
Un logiciel de cabinet, de gestion locative ou de vie scolaire qui ajoute le SMS à ses fonctions, sans construire de lien avec l'opérateur.
Sites de vente et logiciels de caisse
Commande prête, colis parti, retrait en magasin : le SMS part au moment où l'événement se produit dans votre système.
Services informatiques internes
Une alerte technique, une astreinte, un incident : votre outil interne prévient la bonne personne, sous le nom de votre organisation.
Vos questions, nos réponses.
Où est la documentation de l'API SMS ?
La spécification OpenAPI 3.1 est publique : chargez-la dans votre outil de test ou générez un client dans votre langage. La documentation lisible, avec des exemples, s'ouvre dans votre espace client.
Comment obtenir une clé API ?
Une fois votre compte ouvert par notre équipe, vous créez vos clés depuis votre espace client. Chaque clé porte un nom et des droits, et ne s'affiche qu'une seule fois : conservez-la dans une variable d'environnement ou un coffre.
Peut-on limiter une clé à nos serveurs ?
Oui. Déclarez les adresses IP autorisées, une adresse exacte ou un bloc, en IPv4 comme en IPv6. Un appel venu d'une autre adresse est refusé, même avec une clé valide.
Comment savoir si un SMS est délivré ?
Abonnez-vous aux webhooks : vous êtes prévenu quand l'accusé arrive. Vous pouvez aussi demander l'état d'un destinataire précis. Pour les SMS envoyés vers un mobile calédonien, l'opérateur renvoie un accusé de livraison ; sans accusé, l'état reste « transmis », jamais « délivré ».
Que se passe-t-il si un appel est rejoué ?
Avec une clé d'idempotence, un appel rejoué n'envoie pas deux fois : l'API renvoie la réponse d'origine, sans rien exécuter. La même clé avec un contenu différent est refusée, pour signaler l'erreur d'intégration.
Peut-on envoyer sous le nom de chacun de nos clients ?
Oui, à condition que chaque nom soit déclaré avant le premier envoi. Transmettez-nous la liste : nous déclarons chaque nom et le vérifions par un envoi réel. Sinon, gardez votre nom d'expéditeur et citez votre client dans le texte du message.
Pages liées
Agendas et logiciels reliés
Google Agenda, Outlook, logiciels de cabinet et d'optique : les autres façons de brancher SMS PRO.
Le suivi de chaque SMS
Reçu, non délivré, non confirmé : ce que veut dire chaque état, et comment il est établi.
La désinscription STOP
Le lien STOP, son code de confirmation, et son effet sur tous les comptes.
Sécurité et données
Stockage en Nouvelle-Calédonie, secrets chiffrés, double authentification, journal d'activité.
Parlons de votre intégration.
Dites-nous ce que fait votre logiciel et quand il doit prévenir quelqu'un. Un conseiller de Nouméa vous rappelle, ouvre votre compte, déclare votre nom d'expéditeur, et vous créez votre première clé.
Vous préférez appeler ?
Écrire : contact@pacific-consulting.nc
Pacific Consulting · 12 route de l'Anse Vata, 98800 Nouméa