1. Interpréter HTTP 202 correctement
HTTP 202 signifie que la plateforme a accepté la demande dans sa file. Ce n’est pas une confirmation de transmission ni de réception sur le téléphone. Conservez l’identifiant renvoyé et consultez son statut ou les événements reçus par votre endpoint.
Les événements message.submitted, message.sent et message.delivered décrivent des étapes distinctes dans le contrat. Un état de réconciliation indique une incertitude à résoudre, pas une invitation à recréer immédiatement un autre envoi. Les délais de traitement de la plateforme et d’acheminement opérateur sont également distincts.
2. Conserver une clé par demande logique
Avant l’appel, enregistrez une clé d’idempotence stable avec votre opération métier. Pour rejouer la même demande après une réponse réseau incertaine, réutilisez cette même clé et le même contenu. Générer une nouvelle clé à chaque essai représente une nouvelle demande et peut produire un second SMS.
La clé attendue contient 16 à 100 caractères alphanumériques, tirets ou traits de soulignement. Ne la construisez pas avec le numéro, le texte du SMS ou un code OTP. Si le contenu métier change, traitez-le explicitement comme une nouvelle opération plutôt que de modifier silencieusement une reprise.
POST /v1/messages
Authorization: Bearer <clé conservée côté serveur>
Content-Type: application/json
Idempotency-Key: order_update_example_a3. Prévoir la réponse incertaine et les limites
Un timeout peut se produire après l’acceptation de la demande. Votre application doit rapprocher le résultat connu et utiliser la même clé lors d’une reprise conforme au contrat. Évitez les boucles de réessai immédiates et illimitées ; conservez l’identifiant de corrélation pour votre diagnostic.
En cas de limitation, respectez l’indication Retry-After lorsqu’elle est fournie. Vérifiez également le forfait, l’allocation restante et le maximum quotidien. Le fait de disposer d’une API n’ajoute pas d’unités ni de capacité hors du forfait.
4. Vérifier et dédupliquer les callbacks
Configurez un endpoint HTTPS côté serveur. Vérifiez la signature sur le corps brut, avec l’horodatage et la clé de signature prévus dans la référence, avant de faire confiance au contenu. Le helper téléchargeable fournit cette vérification ; évitez de réinventer une variante de l’algorithme.
Enregistrez durablement l’identifiant de l’événement déjà traité. Un endpoint indisponible peut recevoir des reprises : le même événement doit pouvoir être reçu plusieurs fois sans répéter une action métier. N’utilisez pas l’arrivée d’un callback comme déclencheur d’un nouveau SMS pour la demande initiale.
Répondez avec un statut de succès après avoir enregistré le traitement ou sa prise en charge durable. Un test d’endpoint et le suivi des tentatives permettent de distinguer un problème de configuration de votre serveur d’un événement SMS encore en attente.
Pour une rotation, acceptez temporairement les deux secrets, ajoutez et vérifiez la destination de remplacement, puis désactivez l’ancienne. Dédupliquez les identifiants d’événement pendant ce chevauchement. Une tentative déjà en cours peut encore arriver après désactivation. Les livraisons épuisées et les événements manqués pendant une désactivation ne sont pas rejoués : consultez les messages connus avec GET /v1/messages/{id}, sans renvoyer leurs SMS.
5. Garder la vérification OTP dans votre application
Pour un OTP, votre application génère le code, définit son expiration, limite les demandes et les tentatives, puis contrôle la saisie. SMSMarocPro transporte le SMS. Un statut d’envoi ou un callback ne prouve jamais que l’utilisateur a fourni le bon code.
Conservez les clés API et de webhook dans vos secrets serveur. N’envoyez ni code OTP, ni numéro, ni corps du message dans vos outils marketing ou vos URLs. Testez votre traitement avec des événements simulés avant de solliciter des destinataires réels ; la réception immédiate n’est pas garantie.