Choisir sa version d’API
Livstick expose deux API client en parallèle : la v3 et la 2.1. Cette page répond à une seule question — par laquelle commencer, et pourquoi — afin que le reste de la rubrique Développer puisse considérer ce choix comme fait.
Commencer par la v3
Si vous démarrez une nouvelle intégration, construisez-la sur la v3. C’est l’API actuelle, celle que cette documentation présente en premier. Elle offre une liste paginée des conteneurs et des messages, un accès direct aux messages, les groupes de codes en lecture, un unlock distinct de notify, le mode galerie, et des contacts expéditeur et destinataire typés avec un choix de canal explicite — rien de tout cela n’existe en 2.1.
- Référence API v3
- La référence complète de la v3 — conteneurs, messages, groupes de codes et erreurs.
Quand la 2.1 reste pertinente
La 2.1 reste le bon choix dans deux cas précis, et seulement ceux-là.
- Votre intégration appelle retarget — pour réaffecter le contact, la langue, le groupe de codes ou les données additionnelles d’un conteneur après sa création.
- Votre intégration s’appuie sur l’envoi de webhooks (messageUnlockEvent) pour être avertie du déverrouillage d’un message.
- 2.1 : retarget
- Réaffecter le contact, la langue, le groupe de codes ou les données additionnelles d’un conteneur après sa création.
- 2.1 : webhooks
- L’envoi de messageUnlockEvent, pour être averti du déverrouillage d’un message.
- Référence API 2.1
- La référence complète de la 2.1, pour tout ce qui reste sur cette API.
- Migrer de 2.1 vers v3
- Pour une intégration déjà en 2.1 : ce qui a un équivalent en v3, et ce qui n’en a pas.
La v3 comparée à la 2.1
Les deux API ne sont pas superposées — chacune offre des fonctionnalités que l’autre n’a pas.
| Fonctionnalité | v3 | 2.1 |
|---|---|---|
| Liste paginée des conteneurs et des messages | Oui | Non |
| Accès direct aux messages (lecture et écriture) | Oui | Non |
| Groupes de codes en lecture | Oui | Non |
| unlock distinct de notify | Oui | Non |
| Mode galerie (plusieurs messages par conteneur) | Oui | Non |
| Contacts expéditeur / destinataire typés, avec choix du canal | Oui | Non |
| retarget | Non | Oui |
| Webhooks (messageUnlockEvent) | Non | Oui |
Un seul système de clés, quelle que soit la version
Choisir une version n’est pas une décision d’infrastructure. La v3 et la 2.1 s’authentifient auprès du même système de gestion des clés : ce sont les clés émises par ce système qui appellent les deux API, et non deux configurations distinctes à provisionner et à renouveler.