🧩 Étape 1 — Comprendre le fonctionnement de l'API

Objectif

Savoir comment l'API Envopulse fonctionne avant d'écrire la moindre ligne de code.

À retenir

  • API REST accessible via /api/v1/public/*

  • Format JSON uniquement

  • Sécurité par :

  • clé API

  • signature HMAC

  • horodatage

Ce que permet l'API

  • envoyer des SMS transactionnels

  • sécuriser des parcours (OTP)

  • suivre les statuts et les logs

  • interagir avec les ressources du compte

👉 Tout passe par une authentification forte, pensée pour les usages production.

🔐 Étape 2 — Récupérer ses identifiants API

Objectif

Obtenir les éléments nécessaires pour s'authentifier.

Depuis l'espace client Envopulse, vous disposez de :

  • une clé API (X-API-KEY)

  • un secret HMAC

  • un accès sandbox / production

⚠️ Ces informations sont strictement confidentielles et ne doivent jamais être exposées côté client.

🔏 Étape 3 — Générer la signature HMAC

Objectif

Signer correctement chaque requête API.

Principe de la signature

Pour chaque requête, vous devez :

  • Construire un message signé :

  • METHOD|PATH|TIMESTAMP|BODY

  • METHOD : GET, POST, PUT, DELETE

  • PATH : /api/v1/public/...

  • TIMESTAMP : ISO 8601 avec millisecondes

  • BODY : JSON brut (ou chaîne vide pour GET)

  • Calculer :

  • HMAC_SHA256(message, apiSecret)

  • Ajouter les headers requis :

  • X-API-KEY

  • X-TIMESTAMP

  • X-SIGNATURE

⏱️ Le timestamp doit être dans une fenêtre de ±5 minutes, sinon la requête est rejetée.

👉 Cette mécanique garantit :

  • l'intégrité des requêtes

  • l'authenticité du client

  • la protection contre le replay

🧪 Étape 4 — Tester l'authentification API

Objectif

Vérifier que votre configuration est correcte avant d'envoyer un vrai SMS.

Test rapide : ping
Endpoint

GET /api/v1/public/test/ping

Résultat attendu

{
  "success": true,
  "message": "✅ Authentification API réussie."
}

Test complet : signature HMAC
Endpoint

POST /api/v1/public/test/signature

Exemple de payload

{
  "to": "+33612345678",
  "content": "Bonjour !"
}

Résultat attendu

{
  "success": true,
  "message": "✅ Signature HMAC valide - Authentification API réussie."
}

👉 À ce stade, votre API est prête.

📤 Étape 5 — Envoyer votre premier SMS

Objectif

Envoyer un SMS transactionnel réel via l'API.

Endpoint

POST /api/v1/public/sms/send

Exemple cURL

curl -X POST https://votre-domaine.com/api/v1/public/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: VOTRE_CLE_API" \
  -H "X-TIMESTAMP: 2025-11-02T17:00:00.428Z" \
  -H "X-SIGNATURE: VOTRE_SIGNATURE_HMAC" \
  -d '{
    "content": "Votre code de vérification est : 123456",
    "recipient": "+33612345678",
    "sender": "ENVOPULSE"
  }'

Points importants

  • le sender doit être préalablement configuré

  • l'envoi est transactionnel

  • les erreurs sont explicites (ex : INVALID_SENDER)

👉 En quelques requêtes, votre SMS est envoyé de manière sécurisée.

✅ Et après ?

Une fois l'intégration de base réalisée, vous pouvez :

  • gérer des templates SMS

  • envoyer des OTP

  • recevoir des statuts et webhooks

  • utiliser la sandbox

  • automatiser à grande échelle

👉 L'API est conçue pour évoluer avec vos usages.

🔗 Liens internes recommandés

Liens sortants :

Liens entrants suggérés :

  • Page API SMS

  • Pages OTP / Transactionnel

  • Articles blog techniques