Passer de /api à /v1
L’API historique (/api) continue de fonctionner : vous pouvez passer à la v1 route par route. La v1 apporte de vrais codes HTTP, des webhooks signés, un mode test et des identifiants stables.
Route par route
Section intitulée « Route par route »Avec /api |
Avec /v1 |
|---|---|
POST /api/visio, en formulaire : number, reference_id |
POST /sessions, en JSON : channel, to, reference |
Réponse {"ok": 1, "id": …, "link": …} |
Réponse 201 : la session, avec id (ses_…), legacy_id, advisor_url et join_url |
GET /api/visio/{id}/pictures |
GET /sessions/{session_id}/photos |
GET /api/interventions?number=33612345678 |
GET /sessions?to=%2B33612345678 |
Filtres custom_field_1 et custom_field_2 |
GET /sessions?reference=… et GET /sessions?metadata[custom_field_2]=… |
/api/interventions/{id}/report |
GET /sessions/{session_id}/report, au même contenu (schema_version 1), en JSON ou en PDF |
| Fin d’appel : l’événement de l’iframe, puis une lecture | Le webhook session.ended, puis report.ready |
Erreurs en 200 avec "ok": 0 |
Un vrai code HTTP et un corps RFC 9457 |
| Clé dans l’en-tête ou dans le corps | Clé dans l’en-tête Authorization: Bearer <clé> seulement |
Ce qui demande une attention
Section intitulée « Ce qui demande une attention »Les numéros sont au format E.164. /api acceptait 0612345678 et le normalisait. La v1 attend +33612345678, et répond 422 invalid_phone sinon. Dans une URL, encodez le + : ?to=%2B33612345678. Non encodé, il devient une espace et la recherche répond 400 invalid_request.
Les identifiants sont des chaînes. Une session v1 a un identifiant ses_… ; son legacy_id est l’identifiant numérique que renvoyait /api. Les sessions créées par /api se lisent aussi par la v1 : leur custom_field_1 y devient reference, et leur custom_field_2 la donnée metadata.custom_field_2.
Le lien du conseiller s’appelle advisor_url. C’est l’ancien link : le poste conseiller de la session, à ouvrir depuis votre outil, en iframe comme avant. Traitez-le comme un secret.
Un même destinataire relancé dans l’heure rouvre sa session, comme avec /api. La v1 le dit : la réponse est 200 avec reopened: true, au lieu de 201.
Les erreurs se testent sur le statut et sur code. Le champ ok n’existe plus ; title et detail sont faits pour être lus et peuvent changer (Erreurs).