Autenticação

Toda chamada leva um token no cabeçalho Authorization:

GET /plataforma/v1/filas HTTP/1.1
Host: api.botzetta.com
Authorization: Bearer <token>

Há dois tipos de credencial. Use a que corresponde a quem está integrando:

	Token de instalação (OAuth)	Chave de integração
Para quem	Parceiro que publica um app para várias empresas	A própria empresa integrando o seu ERP, n8n, Make, Zapier etc.
Como obtém	A empresa instala o app e autoriza os escopos; seu backend troca o código por tokens	O administrador da empresa cria a chave no Botzetta (Configurações › Chaves de integração)
Formato	JWT, válido por 1 hora, renovado com um refresh token	bzk_live_ + 40 caracteres, sem expiração ou até a data escolhida
Empresa	A da instalação (vem no token)	A dona da chave
Escopos	Os do manifesto do app, consentidos pela empresa	Os escolhidos na criação da chave
Webhooks	Sim	Não

Na referência de cada endpoint, os dois aparecem como esquemas de segurança: bearer (token de instalação) e chaveIntegracao.

Token de instalação (apps de parceiro)

O fluxo é OAuth 2.0 authorization code com PKCE (S256), um par de tokens por empresa que instalou o app. O passo a passo da instalação (montar a URL, tela de consentimento e callback) está no guia Criar Apps. Aqui fica o que a API espera.

Trocar o código por tokens

Depois do consentimento, a empresa volta para a sua redirect_uri com ?code=…&state=…. Confira o state e, no seu backend, chame POST /oauth/token:

curl -s https://api.botzetta.com/plataforma/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "client_id": "bzt_meuapp_…",
    "client_secret": "bzcs_…",
    "code": "bzc_…",
    "redirect_uri": "https://app.exemplo.com/botzetta/callback",
    "code_verifier": "<o verifier guardado na sessão>"
  }'

{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "bzr_…",
  "escopos": ["pessoas:ler", "crm:ler"],
  "companyId": 88,
  "instalacaoId": 412
}

• O código vale 10 minutos e só uma vez. PKCE ou redirect_uri diferentes da autorização invalidam o código.
• Guarde refresh_token cifrado, associado ao companyId. Ele vale 90 dias.

Renovar

curl -s https://api.botzetta.com/plataforma/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{ "grant_type": "refresh_token", "client_id": "bzt_meuapp_…", "client_secret": "bzcs_…", "refresh_token": "bzr_…" }'

O refresh é rotativo: cada renovação devolve um par novo e o anterior deixa de valer.

• Salve o refresh novo antes de usar o access token novo.
• Reusar um refresh já usado revoga todos os tokens daquela instalação (a empresa precisa reinstalar). Exceção: duas renovações concorrentes em até 30 s recebem recusa sem revogar; releia o par salvo.
• Renove quando faltar pouco para expires_in acabar ou ao receber 401 ERR_TOKEN_INVALIDO.

Revogar

POST /oauth/revogar com client_id, client_secret e token (o refresh) revoga a família de tokens daquela instalação. Responde sempre 200.

O que muda o acesso

Os escopos efetivos são recalculados a cada requisição: escopos do token ∩ escopos do manifesto ativo ∩ escopos consentidos pela empresa.

• Uma versão nova do app que pede escopo a mais só ganha o escopo depois que a empresa consentir de novo e o app renovar o token.
• Escopo removido do manifesto deixa de valer na hora.
• Se a empresa desinstalar o app, os refresh tokens são revogados e a próxima chamada recebe 403 ERR_APP_NAO_HABILITADO. Tokens emitidos antes da desinstalação não voltam a valer, mesmo que a empresa reinstale.

Credenciais do app

O client_id (bzt_<slug>_…) é fixo. O app pode ter até 2 segredos (bzcs_…) válidos ao mesmo tempo, para trocar sem parar: gere o novo no portal, publique no seu servidor e revogue o antigo (ou deixe expirar em 7 dias). Segredos e refresh tokens ficam só no servidor, nunca no navegador nem no app móvel.

Chave de integração (integrações da empresa)

A chave é da empresa, não de um parceiro. Serve para a empresa ligar o Botzetta aos próprios sistemas sem publicar um app.

curl -s https://api.botzetta.com/plataforma/v1/pessoas?busca=maria \
  -H "Authorization: Bearer bzk_live_…"

• Disponível em planos pagos. Sem o recurso no plano: 403 ERR_PLANO_SEM_RECURSO.
• Revogada, expirada ou inexistente: 401 ERR_TOKEN_INVALIDO, já na requisição seguinte. Regenerar troca o segredo e o anterior para na hora.
• Escopos possíveis: todos os de dados (pessoas, contatos, CRM, tickets, mensagens, mídias e cadastros de apoio). realtime:emitir e notificacoes:enviar não estão disponíveis para chave.
• O cabeçalho X-Botzetta-Empresa, se enviado, precisa ser a empresa da chave (senão 400 ERR_EMPRESA_DIVERGENTE).

Escopos

Cada endpoint informa o escopo exigido. Sem ele, a resposta é 403 ERR_ESCOPO_INSUFICIENTE. Peça só os escopos de que o app precisa: escopos de risco alto passam por revisão da Botzetta antes de o app ser instalado por empresas reais.

Escopo	O que permite	Risco
pessoas:ler	Ver pessoas e seus contatos	médio
pessoas:escrever	Criar e editar pessoas, tags, campos personalizados e opt-out	médio
contatos:ler	Ver contatos do atendimento (inclusive grupos)	médio
crm:ler	Ver pipelines, etapas e oportunidades	médio
crm:escrever	Criar, mover e encerrar oportunidades	médio
tickets:ler	Ver os atendimentos (tickets)	médio
tickets:escrever	Anotar, transferir e fechar atendimentos	médio
mensagens:ler	Ler o histórico das conversas	alto
mensagens:enviar	Enviar mensagens de WhatsApp em nome da empresa	alto
midias:ler	Ver arquivos e mídias	médio
midias:escrever	Enviar e apagar arquivos e mídias do app	médio
whatsapps:ler	Ver as conexões de WhatsApp	baixo
filas:ler	Ver as filas de atendimento	baixo
templates:ler	Ver os templates de mensagem	baixo
usuarios:ler	Ver nome e perfil dos usuários	baixo
realtime:emitir	Atualizar as telas em tempo real	baixo
notificacoes:enviar	Enviar notificações aos usuários	baixo

A lista oficial, com os rótulos exibidos na tela de consentimento, também está na especificação, na extensão x-botzetta-escopos.