Referência da API

A API da Plataforma (/plataforma/v1) é como o seu app conversa com o Botzetta: lê e grava dados das empresas que o instalaram, dentro dos escopos que cada empresa autorizou.

Endereço

https://api.botzetta.com/plataforma/v1

Todos os caminhos da referência são relativos a esse endereço. Exemplo: GET /filas é GET https://api.botzetta.com/plataforma/v1/filas.

Convenções

Item	Padrão
Formato	JSON (Content-Type: application/json). Upload de mídia em multipart/form-data
Nomes	Recursos no plural, em português e minúsculos (/pessoas, /oportunidades); campos em camelCase (pessoaId)
Datas	ISO 8601 em UTC (2026-10-27T12:14:00.000Z)
Autenticação	Authorization: Bearer <token>. Veja Autenticação
Empresa	Vem sempre do token, nunca do corpo nem da URL. Um token vale para uma empresa
Erros	{ "error": "ERR_CODIGO", "message": "texto" }. Veja Erros
Listas	Paginação por página ou por cursor. Veja Paginação
Idempotência	POST que cria registro ou envia mensagem exige o cabeçalho Idempotency-Key. Veja Limites e idempotência
Rastreio	Envie X-Request-Id para correlacionar chamadas nos seus logs; ele volta na resposta

Como esta referência é mantida

A especificação OpenAPI 3.1 é gerada do código da API e publicada pela própria API em GET /plataforma/v1/openapi.json (rota pública). Esta referência é sincronizada todo dia com produção: ela nunca descreve um endpoint que ainda não está no ar. Cada mudança entra no Changelog da API.

Você pode baixar a especificação para gerar um cliente na sua linguagem:

curl -s https://api.botzetta.com/plataforma/v1/openapi.json -o plataforma-v1.json

Versões e compatibilidade

• A v1 evolui só de forma aditiva: endpoints, campos opcionais e valores novos. Seu código deve ignorar campos que não conhece.
• Mudança incompatível vira /plataforma/v2. A v1 continua no ar por no mínimo 6 meses depois que a v2 for lançada.
• O número da versão do contrato (ex.: 1.10.0) aparece no info.version da especificação e no Changelog.

Por onde começar

1. Crie a conta e o app no Portal do parceiro.
2. Siga o guia Criar Apps para instalar o app numa empresa de teste (sandbox).
3. Troque o código da instalação por um token (Autenticação) e chame os endpoints da seção Endpoints.

Testar pela documentação

Cada página de endpoint tem o painel Testar, que chama a API de produção direto do navegador:

• Use só o token de um app instalado na empresa de sandbox da sua organização. As chamadas são reais: escritas alteram dados.
• O token colado fica só na aba (sessionStorage), não vai para localStorage nem cookie, e a chamada sai sem cookie.
• Não cole chave de integração (bzk_live_…) nem client_secret. O POST /oauth/token não tem Testar: ele é chamado só pelo seu backend.