1. Architecture et Protocoles de Routage au Maroc
Intégrer une API SMS professionnelle au Maroc ne se résume pas à lancer une requête HTTP POST. Pour viser une délivrabilité supérieure à 99% sur les trois grands réseaux du Royaume (Maroc Telecom, Orange Maroc, Inwi), le moteur de routage doit s'appuyer sur des routes locales légitimes avec Sender ID enregistré, sans passer par des routes grises internationales. Ce guide technique détaille l'implémentation d'un flux résilient, robuste et conforme aux normes B2B.
2. Monitoring et Taux de Latence en Temps Réel
Le tableau de bord ci-dessous illustre l'importance d'un routage local légitime. Les statistiques de latence moyenne par opérateur démontrent que le routage local permet de maintenir les délais d'acheminement bien en dessous du seuil critique des 4 secondes (généralement entre 2,8s et 3,9s), ce qui est vital pour les codes d'authentification à double facteur (2FA) et les alertes transactionnelles critiques.
3. Normalisation et Formatage E.164 (+212)
Avant de soumettre une requête à l'API, vos serveurs doivent rigoureusement valider et nettoyer le numéro de téléphone du destinataire. Le format requis est la norme internationale E.164. Pour le Maroc, tous les numéros doivent commencer par le code pays +212, suivi du numéro de mobile sans le 0 initial. Par exemple, le numéro local "0612345678" devient "+212612345678". L'envoi de numéros mal formatés ou de lignes fixes non compatibles déclenche une erreur 400 Bad Request immédiate pour éviter de gaspiller vos crédits de communication.
4. Premier Envoi en cURL, Node.js et PHP
Pour démarrer rapidement, l'API EnvoiSMS.ma propose un endpoint RESTful propre. Voici les implémentations standards recommandées pour vos applications.
// Exemple 1 : Requête cURL
curl -X POST https://api.envoisms.ma/v1/messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+212612345678",
"body": "Votre code de sécurité EnvoiSMS est 849301",
"sender": "EnvoiSMS"
}'
// Exemple 2 : Intégration en Node.js (Axios)
const axios = require('axios');
async function sendSMS() {
try {
const response = await axios.post('https://api.envoisms.ma/v1/messages', {
to: '+212612345678',
body: 'Votre code de sécurité EnvoiSMS est 849301',
sender: 'EnvoiSMS'
}, {
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}
});
console.log('Message ID:', response.data.id);
} catch (error) {
console.error('Erreur d\'envoi:', error.response.data);
}
}
sendSMS();
// Exemple 3 : Intégration en PHP (cURL natif)
<?php
$ch = curl_init('https://api.envoisms.ma/v1/messages');
$payload = json_encode([
"to" => "+212612345678",
"body" => "Votre code de sécurité EnvoiSMS est 849301",
"sender" => "EnvoiSMS"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer YOUR_API_KEY',
'Content-Type: application/json'
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Erreur : ' . curl_error($ch);
} else {
$result = json_decode($response, true);
echo 'Message ID : ' . $result['id'];
}
curl_close($ch);
?>
5. Webhooks DLR et Validation de Signature HMAC SHA256
Pour suivre le cycle de vie de vos messages sans surcharger l'API de requêtes répétitives (polling), vous devez configurer un webhook dans votre console d'administration. À chaque changement d'état du message (delivering, delivered, failed), notre passerelle envoie un payload JSON à votre serveur. Pour sécuriser cet endpoint contre les attaques d'usurpation d'identité, EnvoiSMS.ma signe chaque payload avec une clé secrète partagée. Votre serveur doit obligatoirement valider la signature présente dans le header HTTP "X-EnvoiSMS-Signature" en recalculant le HMAC-SHA256 du corps de la requête.
// Validation de signature en Node.js (Express)
const crypto = require('crypto');
const express = require('express');
const app = express();
const WEBHOOK_SECRET = 'votre_cle_secrete_partagee';
app.post('/webhook/envoisms', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-envoisms-signature'];
const payload = req.body.toString();
const computedSignature = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex');
if (computedSignature !== signature) {
return res.status(401).send('Signature invalide.');
}
const event = JSON.parse(payload);
console.log(`Statut du message ${event.messageId} : ${event.status}`);
res.status(200).send('Reçu.');
});
app.listen(3000);
6. Gestion des Files d'Attente et Reprise sur Erreur (Rate-limiting)
En production, vos services peuvent être confrontés à des pics de trafic intenses ou à des indisponibilités temporaires des passerelles opérateurs. L'API EnvoiSMS applique des limites de requêtes (Rate-limiting) par jeton pour préserver la stabilité du service. Pour éviter les pertes de requêtes, implémentez une file d'attente de messages (par exemple avec Redis et BullMQ en Node.js, ou des queues RabbitMQ en PHP) et appliquez un algorithme de retry exponentiel (backoff) avec une gigue (jitter) aléatoire pour répartir la charge lors des tentatives ultérieures.
7. Conformité CNDP et Hébergement Souverain local
Le traitement des numéros de téléphone constitue une manipulation de données à caractère personnel soumise à la loi 09-08 au Maroc. EnvoiSMS.ma garantit une conformité totale en chiffrant l'intégralité des données d'abonnés en transit (TLS 1.3) et au repos (AES-256), et en assurant un hébergement local souverain. Toutes les communications marketing doivent également proposer un moyen d'opt-out (désinscription via STOP SMS) pour se conformer aux exigences de la CNDP.
Questions fréquentes
Q.Quelle est la latence moyenne de livraison d'un code OTP avec l'API ?
Grâce à nos routes locales vers Maroc Telecom, Orange et Inwi, le temps de livraison d'un SMS OTP est généralement inférieur à 4 secondes.
Q.Comment valider les signatures de webhook en production ?
Utilisez l'en-tête X-EnvoiSMS-Signature et recalculez le hash HMAC-SHA256 du corps brut de la requête (Raw Body) avec votre clé secrète pour vérifier l'authenticité.
Q.Existe-t-il un environnement de test (Sandbox) gratuit ?
Oui, EnvoiSMS fournit des clés de test Sandbox gratuites qui simulent parfaitement le comportement de l'API et des webhooks sans débiter votre solde.
