Cadastrar o app
No portal, abra a organização, vá em Apps e crie o app com um nome e um slug.
O slug é o identificador permanente do app: ^[a-z][a-z0-9]{2,30}$ (minúsculas e números,
começando por letra). Ele aparece nas URLs do Botzetta (/apps/<slug>/…) e na audiência do token de
usuário (app:<slug>), e não muda depois de criado.
O app tem cinco abas: Configuração, Credenciais, Versões, Webhooks e logs e Instalações.
Configuração › Cadastro
O cadastro vale na hora, sem publicar versão. Só dono e admin editam.
| Campo | Regra |
|---|---|
| URLs de redirecionamento | Uma por linha, https:. O redirect_uri da instalação tem de ser igual a uma delas, sem curinga |
| URL de instalação do app | Endpoint do seu backend que inicia a instalação (gera PKCE e state e redireciona para o Botzetta). Ex.: https://meuapp.exemplo.com/botzetta/instalar |
| URL do webhook | Onde os eventos chegam (https:). Na primeira vez que você salva, o portal mostra o segredo do webhook (whsec_…) uma única vez: guarde-o |
| E-mail de suporte | Aparece no consentimento e na tela de erro do iframe |
| URL da política de privacidade | Aparece no consentimento. Precisa responder |
| Categoria | Opcional |
O botão Testar na sandbox abre a sua URL de instala ção: é o mesmo link que você vai passar aos clientes.
URLs do app (redirect, webhook, iframe, itens de menu) são sempre https:, sem usuário/senha, sem
IP privado e sem redirecionamento. http://localhost só é aceito em ambientes locais de
desenvolvimento do Botzetta, não na sandbox de produção: para testar do seu computador, exponha o
servidor com um túnel https (ngrok, Cloudflare Tunnel ou parecido).
Configuração › Rascunho da próxima versão
O rascunho descreve o que muda a cada versão do app. Ele só vale para os clientes depois de publicado e ativado (ver Publicar).
| Seção | Campos |
|---|---|
| Geral | Nome e descrição (como o cliente vê), ícone da lista ou PNG próprio |
| Interface (iframe) | URL base do app: onde a sua página está. Sem ela o app é "só de API" (sem tela e sem itens embutidos no menu) |
| Itens de menu | Título, rota ou URL externa, ícone, visibilidade. Ver Menu do Botzetta |
| Extensões | Botão nas ações do ticket, que abre uma página sua num diálogo. Ver Tela em iframe |
| Acessos GBAC | Permissões próprias do app (<slug>.<recurso>.<acao>). GBAC é o controle de acesso por grupos do Botzetta: o admin da empresa marca, em cada grupo de usuários, quais acessos ele tem |
| Escopos | Escopos da API, cada um com uma justificativa. Ver Conceitos |
| Eventos | Eventos de webhook que o app quer receber. Cada um exige o escopo de leitura correspondente. Ver Webhooks |
O portal mostra os problemas do rascunho (campo faltando, URL recusada, evento sem escopo) antes de publicar. Quem prefere JSON pode exportar e importar o manifesto do rascunho; o formulário é a forma recomendada.
Credenciais
| Credencial | Uso |
|---|---|
client_id (bzt_<slug>_…) | Fixo. Identifica o app no OAuth |
client_secret (bzcs_…) | Mostrado uma vez ao gerar. Até 2 ativos ao mesmo tempo |
Segredo do webhook (whsec_…) | Assina as entregas de webhook |
- Gerar um novo
client_secretmantém o anterior válido por 7 dias, para você trocar sem parar o app. Revogar corta na hora. O único segredo ativo não pode ser revogado. - Rotacionar o segredo do webhook também dá 7 dias ao anterior: nesse período as entregas levam duas assinaturas (ver Webhooks).
- Gerar, revogar e rotacionar exigem 2FA e papel dono ou admin.
client_secret, refresh tokens e o segredo do webhook ficam só no seu backend, de preferência
cifrados. Nunca no navegador, no aplicativo móvel ou no repositório.