Workspaces
Uma chave pertence a exatamente um workspace. O que isso significa para aplicativos multi-tenant e como um portal Bitrix24 difere de um workspace independente.
Um workspace é dono de conexões WhatsApp. Uma API key é emitida para exatamente um workspace, e tudo o que a chave pode ver ou fazer fica restrito a ele — não há como consultar outro.
Uma chave, um workspace, várias conexões
Para um aplicativo multi-tenant, este é o formato ideal:
- Uma única API key, não uma por tenant. Não crie uma chave para cada cliente.
- Um
POST /connectionspor tenant, inclusive o primeiro, cada um com seu próprioIdempotency-Keynovo. - Direcione os eventos recebidos por
connection_id— um cuid estável que aparece em toda resposta REST e em todo payload de webhook. Associe-o ao registro do seu próprio cliente: nós geramos o id, você faz o mapeamento. - Novas conexões podem ser usadas imediatamente. A lista de conexões da chave é resolvida na hora, a cada requisição, então não há nada para atualizar depois de criar uma.
Dois tipos de workspace
Workspace independente
Criado quando você se cadastra em developers.wasync.app. A API é o produto inteiro: você cria conexões por REST e cada conexão tem a própria licença.
Portal Bitrix24
Criado quando o WASync é instalado em um portal Bitrix24. As conexões são criadas pelo administrador do portal dentro do WASync, e o acesso de API a um número é um complemento pago.
A diferença aparece em exatamente dois pontos, e vale conhecê-los antes de escrever código para o tipo errado:
Criação de conexões. POST /connections só funciona em workspaces
independentes. Em um portal Bitrix24, ele responde 403 forbidden_portal_kind —
o administrador do portal cria as conexões na interface do WASync. Todos os
outros endpoints se comportam de forma idêntica nos dois tipos.
O que torna uma conexão acessível. Em um workspace independente, é a licença
da própria conexão (teste ou paga). Em um portal Bitrix24, a assinatura do portal
paga pelo número no CRM, e acessar esse mesmo número pela API exige, além
disso, o complemento de API, a $12 por número por mês. Sem ele, a conexão
simplesmente não aparece em GET /connections.
Primeiros passos
Com uma API key não há etapa de bootstrap: a chave é emitida diretamente para o
seu workspace, então POST /connections cria a primeira conexão com a mesma
facilidade que a décima.
Uma concessão OAuth é diferente por construção — ela só é emitida sobre conexões que já existem, portanto uma integração apenas com OAuth não consegue criar a primeira conexão de um workspace. É por isso que todo guia de início rápido aqui começa com uma chave.