Conceitos
App de parceiro
Um app de parceiro é construído e hospedado por você. Uma empresa cliente do Botzetta o instala, e o administrador dela consente com o que o app pede. A partir daí o app pode:
- chamar a API da Plataforma com um token daquela empresa;
- receber webhooks quando algo acontece na empresa (uma pessoa criada, um ticket fechado…);
- mostrar telas dentro do Botzetta, num iframe com a sua página;
- aparecer no menu do Botzetta, com ícone e itens próprios.
Nada disso exige alguma mudança no Botzetta: você cadastra e publica tudo no portal do parceiro.
Um app pode usar só uma parte. Um app "só de API" não tem tela nem menu: sincroniza dados com o seu sistema, por exemplo.
O código de um parceiro nunca roda com os privilégios do Botzetta. A sua página abre num iframe com
sandbox, na sua origem, e conversa com o Botzetta só por mensagens (postMessage). Ela não lê
cookies, armazenamento nem a página do Botzetta.
Instalação
Cada empresa que instala o app gera uma instalação. Ela é a unidade de tudo:
- os tokens são por instalação (um par de tokens para cada empresa);
- os escopos consentidos são por instalação;
- os webhooks chegam com o
companyIdda empresa.
O fluxo de instalação é o OAuth 2.0 authorization code com PKCE: o admin da empresa abre um link do seu app, vê a tela de consentimento do Botzetta, autoriza e volta para o seu backend com um código, que vira os tokens. Detalhes em Instalação e OAuth.
Quem instala precisa ser administrador da empresa (ou ter os acessos de instalar apps), e o plano da
empresa precisa incluir apps de parceiros. Desinstalar acontece no Botzetta, a qualquer momento: os
tokens deixam de valer na hora e o app recebe o evento app.desinstalado.
Escopos
O escopo diz o que o app pode fazer na API. O app declara a lista no cadastro, cada uma com uma justificativa que o admin da empresa vê. Na instalação o consentimento é tudo ou nada: o admin autoriza todos os escopos da versão ativa ou cancela.
| Escopo | Permite | Risco |
|---|---|---|
pessoas:ler | Listar e ler pessoas (clientes) e tags | médio |
pessoas:escrever | Criar e alterar pessoas, tags, campos e opt-out | médio |
contatos:ler | Ler contatos do atendimento, inclusive grupos | médio |
crm:ler / crm:escrever | Pipelines, estágios e oportunidades | médio |
tickets:ler / tickets:escrever | Tickets do atendimento; notas, transferência e fechamento | médio |
mensagens:ler | Histórico de conversas | alto |
mensagens:enviar | Enviar mensagens de WhatsApp | alto |
midias:ler / midias:escrever | Ler e enviar arquivos | médio |
whatsapps:ler, filas:ler, templates:ler, usuarios:ler | Cadastros de apoio (conexões, filas, templates, usuários) | baixo |
realtime:emitir | Avisar a tela do app que algo mudou | baixo |
notificacoes:enviar | Notificar os usuários da empresa | baixo |
O rótulo e o risco exatos de cada escopo aparecem no portal, ao escolher os escopos do app, e são os mesmos da tela de consentimento. Escopo de risco alto passa por revisão antes de valer para empresas reais.
Peça só o necessário. Os escopos efetivos de cada chamada são os do token, limitados aos da versão ativa do app e aos que a empresa consentiu. Por isso:
- uma versão nova com escopo a mais só vale para a empresa depois que o admin aceitar o novo
consentimento (o app recebe
app.escopos-alterados) e o app renovar o token; - um escopo removido numa versão nova deixa de valer na hora.
Tokens
| Token | Para quê | Validade |
|---|---|---|
| access token da instalação | Chamar a API em nome de uma empresa | 1 hora |
refresh token (bzr_…) | Renovar o access token daquela empresa. Rotativo: cada uso devolve um novo | 90 dias |
código de autorização (bzc_…) | Trocar pelos tokens no fim da instalação. Uso único | 10 minutos |
| token de usuário | Identificar quem está usando a tela em iframe | 10 minutos (renovado pelo Botzetta) |
Os tokens do Botzetta são JWT RS256, verificáveis pelas chaves públicas em
GET /plataforma/v1/.well-known/jwks.json. Só o token de usuário precisa ser verificado pelo seu
backend; os outros você só repassa.
Sandbox
Toda organização do portal ganha uma empresa sandbox no Botzetta: uma empresa de teste, com os membros da organização como usuários. Instale e teste o seu app nela à vontade, inclusive com escopos de risco alto ainda não revisados. Ela não conta no limite de empresas de um app privado.