Integrações API — Tokens, Webhooks e OAuth

O que é o módulo Integrações API

O módulo Integrações API é o ponto central onde você conecta sistemas externos ao Bunto ERP. Ele gerencia tokens de API (para autenticação programática), webhooks (para receber eventos em tempo real) e aplicativos OAuth (para integrações com autorização de usuário). Também traz a documentação técnica da API REST do ERP.

É o caminho oficial para conectar o Bunto a automações, marketplaces próprios, e-commerces externos, ferramentas de BI, aplicativos mobile customizados e qualquer outro sistema que precise ler ou escrever dados do ERP.

Como acessar

No menu lateral, acesse Sistema → Integrações API. Rota: /integracoes-api.

A tela tem abas para Tokens de API, Aplicativos OAuth, Webhooks, Telegram e Documentação.

Tokens de API

Um token é a credencial que o sistema externo usa para falar com a API do ERP. Cada token pertence a um usuário e herda as permissões dele.

Listagem

Nome, prefixo público (bnt_...), criado por, data de criação, último uso, total de chamadas, status.

Criar token

• Nome — identifica o uso (ex.: "e-commerce XYZ").
• Descrição — para que o token serve.
• Após a criação, o token completo é exibido uma única vez. Guarde em local seguro.

Revogar

Tokens comprometidos podem ser revogados a qualquer momento. A partir da revogação, todas as chamadas com aquele token são rejeitadas.

Webhooks

Webhooks permitem que o Bunto notifique outro sistema automaticamente quando algo acontece. Você cadastra o evento, a URL de destino e o ERP envia um HTTP POST com os dados sempre que o evento ocorre.

Eventos disponíveis

• produto.criado, produto.atualizado, produto.excluido.
• cliente.criado, cliente.atualizado, cliente.excluido.
• venda.criada, venda.atualizada, venda.cancelada.
• estoque.atualizado.
• nfe.emitida, nfe.cancelada.

Outros eventos (compras, financeiro, CTE, MDFe) são adicionados continuamente conforme demanda.

Configuração

• URL do webhook — precisa ser HTTPS em produção.
• Evento — um webhook por tipo de evento.
• Secret — usado para assinar o payload (HMAC) e garantir autenticidade.
• Ativo — liga ou desliga sem excluir.

Retentativas

Em caso de falha (timeout ou resposta não-2xx), o sistema tenta novamente com backoff exponencial até cinco vezes. Depois de todas as tentativas, o webhook é marcado como com erro para análise manual.

Aplicativos OAuth

Aplicativos OAuth são usados quando um sistema externo precisa de autorização explícita de um usuário para acessar dados. É o padrão usado por integrações com Google, Meta e outros grandes fornecedores.

Cadastro

• Nome do aplicativo.
• Redirect URIs autorizados.
• Client ID e client secret gerados pelo sistema (o secret só é exibido uma vez).
• Escopos — o que o aplicativo pode fazer em nome do usuário.

Segurança

Os tokens e client secrets são criptografados em repouso usando Fernet. A API do ERP não expõe esses dados em chamadas de leitura. Todas as operações são auditadas no módulo Ocorrências, incluindo o uso de cada token.

Integrações com outros módulos

Todos os módulos

A API REST cobre praticamente todos os recursos do ERP — produtos, clientes, vendas, compras, finanças, estoque, documentos fiscais e mais.

Ocorrências

Uso de API e entregas de webhooks são registrados como eventos de auditoria.

CRM

O bot Telegram do CRM usa a infraestrutura deste módulo para autenticação.

Permissões

• Visualizar integrações API.
• Criar tokens.
• Revogar tokens.
• Gerenciar webhooks.
• Gerenciar aplicativos OAuth.

Perguntas frequentes

Perdi meu token de API. Como recupero?

Não é possível recuperar. O token é exibido uma única vez na criação. Se você perdeu, revogue o antigo e crie um novo.

Como testo um webhook antes de colocar em produção?

Use um serviço como webhook.site ou RequestBin para inspecionar o payload em desenvolvimento. Depois, substitua pela URL real.

Token versus OAuth: qual usar?

Use token para integrações servidor a servidor onde a aplicação é sua. Use OAuth quando um usuário precisa autorizar um aplicativo de terceiro a acessar os dados dele.

O que acontece se meu endpoint de webhook ficar fora do ar?

O Bunto tenta reenviar com backoff exponencial até cinco vezes. Depois disso, o webhook é marcado como com erro e você pode reprocessar manualmente.

Onde vejo a documentação da API?

A aba Documentação dentro do módulo mostra os endpoints disponíveis, parâmetros e exemplos de uso. A categoria Documentação da API da base de conhecimento tem artigos detalhados por recurso.