SMS v1 et migration
La v1 reste disponible
Section intitulée « La v1 reste disponible »Les routes /api/smsko/v1/, clés et réponses historiques sont conservées pendant la migration.
La documentation historique et la collection Postman v1 décrivent ce contrat legacy.
Aucune date de retrait n’est annoncée sur cette page. Le calendrier dépend de la disponibilité générale de v2, de la couverture des usages et de l’accompagnement des intégrateurs.
Comparer les contrats
Section intitulée « Comparer les contrats »Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.
| Sujet | v1 | v2 |
|---|---|---|
| Namespace | /api/smsko/v1/ | /api/sms/v2/ |
| Clé | Contrat historique | Clé organisationnelle bf_sms_ uniquement |
| Authentification | Authorization: <key> avec la clé brute, sans préfixe Bearer | Authorization: Bearer <key> |
| Organisation | Résolution historique | Déduite de la clé |
| Envoi | Routes historiques | Ressource messages |
| Programmation | Routes dédiées | Champ send_at, ou ressource message-batches |
| Date | Format historique | RFC 3339 avec fuseau explicite |
| Idempotence | Comportement historique | Clé obligatoire pour les messages et lots |
| Statut | Contrat historique | Identifiant UUID et état explicite |
| Réponses | Réponses historiques | Champs, codes et messages en anglais |
Une ancienne clé reste refusée en v2 même lorsqu’elle a été rattachée à une organisation. Ne remplacez donc pas simplement v1 par v2 dans une URL.
En v1, l’en-tête contient directement la clé historique ou organisationnelle acceptée par ce contrat. En v2, le préfixe Bearer et une clé organisationnelle sont obligatoires.
Retrouver chaque usage
Section intitulée « Retrouver chaque usage »Les chemins v1 ci-dessous utilisent la base /api/smsko/v1/ ; les chemins v2 utilisent /api/sms/v2/.
Défilement horizontal si nécessaire. Au clavier : Tab, puis les flèches gauche et droite.
| Usage | Route v1 | Équivalent v2 |
|---|---|---|
| Envoi immédiat | POST send/ | POST messages/, sans send_at |
| Programmation simple | POST sendlater/ | POST messages/, avec send_at |
| Programmation multiple | POST sendbulk/ | POST message-batches/, avec une date future send_at commune |
| Solde | GET balance/ | GET balance/ |
| Contact | POST contact/ | POST contacts/ |
| Statut de livraison | GET get-delivery-status/ | GET messages/{message_id}/ |
Cette correspondance décrit la migration des usages, pas une compatibilité des corps ou réponses. Pour les champs et réponses v1 complets, consultez la documentation historique et la collection liées plus haut.
Migrer progressivement
Section intitulée « Migrer progressivement »- Recensez vos envois immédiats, programmations, lots, lectures de solde, contacts et consultations de statut.
- Créez une clé organisationnelle avec les permissions nécessaires.
- Adaptez les champs de requête et le traitement des réponses.
- Enregistrez l’idempotence et les identifiants publics dans votre application.
- Vérifiez les cas d’erreur, les crédits insuffisants et les résultats inconnus.
- Basculez une opération métier vers un seul contrat à la fois.
Évitez de soumettre une même opération en parallèle à v1 et v2 : l’idempotence de v2 ne déduplique pas automatiquement un envoi v1. Les messages créés en v1 continuent d’être suivis avec leur contrat historique.
La collection Postman liée ci-dessus reste Legacy v1. La collection Postman SMS v2.0.1 couvre les sept opérations du contrat v2 en production. Consultez la référence v2 pour préparer votre clé privée, les variables et les reprises avec la même clé d’idempotence. Les requêtes Postman s’exécutent manuellement vers la production.