Espaces de travail
Une clé appartient à un seul espace de travail. Ce que cela implique pour les applications multi-tenant, et en quoi un portail Bitrix24 diffère d'un espace de travail autonome.
Un espace de travail possède des connexions WhatsApp. Une API key est émise pour un seul espace de travail, et tout ce que la clé peut voir ou faire y est limité : il n'est pas possible d'interroger un autre espace.
Une clé, un espace de travail, plusieurs connexions
Pour une application multi-tenant, voici la structure qu'il vous faut :
- Une seule API key, pas une par tenant. Ne créez pas une clé par client.
- Un
POST /connectionspar tenant, y compris le tout premier, chacun avec sa propreIdempotency-Keyneuve. - Routez les événements entrants par
connection_id— un cuid stable qui apparaît dans chaque réponse REST et chaque payload de webhook. Associez-le à votre propre fiche client : nous créons l'identifiant, vous l'associez. - Les nouvelles connexions sont utilisables immédiatement. La liste des connexions de la clé est résolue en direct à chaque requête : il n'y a donc rien à actualiser après une création.
Deux types d'espace de travail
Espace de travail autonome
Créé lorsque vous vous inscrivez sur developers.wasync.app. L'API est tout le produit : vous créez les connexions via REST et chaque connexion porte sa propre licence.
Portail Bitrix24
Créé lorsque WASync est installé sur un portail Bitrix24. Les connexions sont créées par l'administrateur du portail dans WASync, et l'accès API à un numéro est un module complémentaire payant.
La différence se manifeste à deux endroits seulement, et mieux vaut les connaître avant d'écrire du code pour le mauvais type :
Création des connexions. POST /connections est réservé aux espaces autonomes. Sur un portail
Bitrix24, il répond 403 forbidden_portal_kind — l'administrateur du portail crée
les connexions dans l'interface de WASync. Tous les autres endpoints se comportent
de la même façon dans les deux cas.
Ce qui rend une connexion accessible. Dans un espace de travail autonome, c'est la
licence propre à la connexion (essai ou payante). Sur un portail Bitrix24, l'abonnement du portail
paie le numéro dans le CRM, et pour atteindre ce même numéro
via l'API, il faut en plus le module complémentaire API, à 12 $ par numéro et par
mois. Sans lui, la connexion n'apparaît tout simplement pas dans GET /connections.
Démarrage
Avec une API key, il n'y a aucune étape d'amorçage : la clé est émise directement pour votre
espace de travail, et POST /connections crée la première connexion aussi
facilement que la dixième.
Un accès OAuth est différent par construction : il n'est émis que sur des connexions déjà existantes, si bien qu'une intégration uniquement OAuth ne peut pas créer la première connexion d'un espace de travail. C'est la raison pour laquelle tous les guides de démarrage rapide ici commencent par une clé.