Workspace
Una chiave appartiene esattamente a un workspace. Cosa significa per le app multi-tenant e in cosa un portale Bitrix24 differisce da un workspace standalone.
Un workspace possiede connessioni WhatsApp. Una API key viene emessa per un solo workspace e tutto ciò che la chiave può vedere o fare è limitato a esso: non c'è modo di interrogarne un altro.
Una chiave, un workspace, molte connessioni
Per un'applicazione multi-tenant questa è la struttura ideale:
- Una sola API key, non una per tenant. Non create una chiave per ogni cliente.
- Una
POST /connectionsper tenant, compresa la primissima, ciascuna con una propriaIdempotency-Keynuova. - Instradate gli eventi in entrata tramite
connection_id: un cuid stabile che compare in ogni risposta REST e in ogni payload dei webhook. Associatelo al vostro record cliente: l'id lo generiamo noi, l'associazione la fate voi. - Le nuove connessioni sono utilizzabili subito. L'elenco delle connessioni della chiave viene risolto in tempo reale a ogni richiesta, quindi dopo una creazione non c'è nulla da aggiornare.
Due tipi di workspace
Workspace standalone
Creato quando vi registrate su developers.wasync.app. L'API è l'intero prodotto: create le connessioni tramite REST e ogni connessione ha una propria licenza.
Portale Bitrix24
Creato quando WASync viene installato su un portale Bitrix24. Le connessioni sono create dall'amministratore del portale all'interno di WASync e l'accesso API a un numero è un componente aggiuntivo a pagamento.
La differenza emerge in due soli punti ed è bene conoscerli prima di scrivere codice per il tipo sbagliato:
Creazione delle connessioni. POST /connections è disponibile solo per i workspace standalone. Su un portale
Bitrix24 risponde 403 forbidden_portal_kind: l'amministratore del portale crea
le connessioni nell'interfaccia di WASync. Tutti gli altri endpoint si comportano
in modo identico in entrambi i casi.
Cosa rende raggiungibile una connessione. In un workspace standalone è la
licenza della connessione stessa (trial o a pagamento). Su un portale Bitrix24 l'abbonamento del portale
paga il numero nel CRM, mentre per raggiungere lo stesso numero
tramite l'API serve inoltre il componente aggiuntivo API, a 12 $ per numero al
mese. Senza di esso la connessione semplicemente non compare in GET /connections.
Bootstrap
Con una API key non esiste alcun passaggio di bootstrap: la chiave viene emessa direttamente per il vostro
workspace, quindi POST /connections crea la prima connessione con la stessa
facilità della decima.
Una concessione OAuth è diversa per costruzione: viene emessa solo su connessioni già esistenti, quindi un'integrazione solo OAuth non può creare la prima connessione di un workspace. Per questo ogni guida rapida di questa documentazione parte con una chiave.