Reliez Loonext aux autres outils de votre entreprise.
Une petite API REST et des webhooks sortants signés permettent à votre outil de planification, à votre comptabilité ou à un Zap de travailler avec les mêmes conversations que votre équipe. Les clés ont une portée limitée, peuvent être révoquées et ne peuvent jamais faire plus que la personne qui les a créées.
Chemin de base /public/v1. Créez une clé dans Réglages → Clés d'API.
L'authentification et ce qu'une clé peut atteindre.
Envoyez la clé sous la forme Authorization: Bearer lnx_…. Elle n'est affichée qu'une fois, au moment de sa création; nous conservons un condensat et les douze premiers caractères, sans aucun moyen de la consulter ensuite.
Une clé agit comme la personne qui l'a créée, dans les limites des portées choisies. Deux conséquences sont importantes : une clé ne survit jamais à l'accès de sa créatrice ou de son créateur. Si cette personne quitte l'espace de travail, la clé cesse de fonctionner dès la requête suivante. De plus, une clé créée par une personne qui ne voit pas un numéro donné ne peut pas voir les conversations de ce numéro.
Toute la surface.
Elle est courte exprès. C'est l'ensemble dont une intégration a réellement besoin, pas notre API interne munie d'une deuxième porte.
GET /me
—
Indique l'espace de travail atteint par la clé et ce qu'elle peut faire. Commencez ici.
GET /contacts
contacts:read
La liste des clients, du plus récent au plus ancien.
POST /contacts
contacts:write
Ajoute un client. Renvoyer un client déjà transmis le met à jour au lieu de le dupliquer.
GET /conversations
conversations:read
La liste des fils de discussion.
GET /conversations/:id/messages
messages:read
Les messages d'un fil de discussion.
POST /messages
messages:send
Envoie un texto dans un fil existant. L'en-tête Idempotency-Key est obligatoire.
GET /tasks
tasks:read
La liste des travaux.
POST /tasks
tasks:write
Transforme un message en travail.
POST /webhooks
webhooks:manage
S'abonne aux événements. C'est le point REST-hook utilisé par Zapier et Make.
DELETE /webhooks/:id
webhooks:manage
Se désabonne. Une clé peut seulement retirer un abonnement qu'elle a créé.
Des webhooks pour éviter l'interrogation répétée.
Donnez-nous une adresse https et nous publions dès qu'un événement survient. Chaque livraison est signée avec HMAC-SHA256 sur timestamp.body, envoyée sous la forme Loonext-Signature: t=…,v1=…, et comprend l'identifiant de livraison pour qu'une nouvelle tentative soit reconnaissable comme le même événement. Une adresse en échec est réessayée 6 fois, avec des délais croissants. Une adresse qui refuse toujours est désactivée afin qu'elle ne vous coûte plus des livraisons que vous ne recevez pas.
Ce que v1 promet.
Une API est une promesse. Voici la nôtre, pour que vous puissiez décider jusqu'où bâtir dessus.
Tant que v1 existe
- Un champ publié ne sera ni retiré ni changé de sens. De nouveaux champs peuvent être ajoutés : analysez donc les réponses avec souplesse, car un champ inconnu n'est pas une erreur.
- Une route ne sera pas retirée, et sa méthode comme son chemin ne changeront pas.
- Un nom d'événement ne sera ni retiré ni réaffecté. De nouveaux noms peuvent être ajoutés; ignorez ceux que vous ne connaissez pas.
- Le mécanisme de signature des webhooks ne changera pas sous v1=. Une signature v2= pourra apparaître à côté, sans empêcher un destinataire qui vérifie v1= de fonctionner.
- Les codes d'erreur et leurs états HTTP ne changeront pas.
Ce que nous ne promettons pas
- L'ordre au-delà de ce que documente une route. Les listes vont du plus récent au plus ancien; rien d'autre sur leur ordre n'est stable.
- Les limites de débit. Aujourd'hui, une clé peut faire 60 requêtes par minute. Traitez l'état 429.
- Le moment exact. Les webhooks sont livrés au mieux avec de nouvelles tentatives; rien n'est synchrone avec l'événement qui les déclenche.
- Notre API interne. Les points utilisés par l'application ne font pas partie de cette API et changent avec le produit.
Si nous devons un jour briser la compatibilité
Une modification incompatible exige un nouveau chemin de version : /public/v2 , servi à côté de v1, sans jamais le remplacer sous une intégration en marche. Chaque réponse porte déjà Loonext-Api-Version, de sorte que même un client qui n'épingle rien sait quelle version lui a répondu.
Si v1 doit un jour être retirée, nous l'annonçons puis attendons au moins douze mois, en écrivant après six mois puis après onze mois aux espaces de travail dont les clés l'appellent encore. Nous savons lesquels joindre puisque nous enregistrons la dernière utilisation de chaque clé. Douze mois dépassent volontairement le délai entre la fin du mandat d'une personne qui intègre un système et son retour éventuel. Une politique mesurée en semaines finit par briser l'entreprise de quelqu'un un mardi.