Bunto
Developers/Changelog/Changelog - API v1

Changelog - API v1

Histórico de mudanças e lançamentos da API pública do Bunto ERP.

13/02/202613 min de leitura87 visualizaçõesv4

Histórico de mudanças da API pública do Bunto ERP.

v1.6.0 - 7 de agosto de 2026

Quem tem várias empresas na mesma conta passa a abrir empresa e emitir chave pela API.

Empresas

  • POST /v1/empresas/ abre uma empresa nova na mesma conta. Ela nasce com o pacote de recursos e uma cópia dos perfis de acesso do cadastro principal — não é preciso remontar permissão a permissão. Enviando gerar_chave: true, a chave de API da empresa nova volta na própria resposta.
  • POST /v1/empresas/{id}/chaves/ emite chave para qualquer empresa ou filial da conta. O texto da chave aparece uma única vez, na resposta.
  • GET /v1/empresas/limite/ informa quantas empresas a conta já usa e quantas ainda cabem no contrato. Consulte antes de abrir.
  • GET /v1/empresas/escopos/ lista as permissões que uma chave pode receber, já filtradas pelo plano da empresa. Pedir um módulo fora do plano na emissão é recusado com 400 em vez de aceito em silêncio — uma chave com permissão inexercível só produziria um 403 inexplicável depois.
  • A emissão aceita escopos e ips_permitidos: a chave nasce limitada aos módulos e ações que a integração usa, em vez de acesso total. Quem emite não concede o que não tem — chave restrita não gera chave mais ampla que ela.
  • GET /v1/empresas/da-conta/ lista tudo que a conta administra — empresas e filiais — com ocupa_limite separando quem consome vaga de quem não consome (filial divide o CNPJ raiz da matriz).
  • Só a chave do cadastro principal comanda. A chave de uma empresa criada por esse caminho lê e edita apenas a si mesma; se tentar abrir outra empresa ou emitir chave, recebe 403.
  • O contrato passa a valer de verdade. Alcançado o total de empresas contratado, a abertura responde 400 com a mensagem pronta para exibir. O mesmo teto agora vale na tela.

Usuários

  • O total de usuários contratado passou a ser aplicado em POST /v1/usuarios/ e na reativação de um acesso excluído (PATCH com is_active: true). Alcançado o limite, a resposta é 400. Contador e terceiro são acessos externos e não ocupam vaga.

Tokens de API no painel

  • Quem responde pela conta passa a ver e gerar chaves de qualquer empresa dela na mesma tela, sem trocar de empresa. Cada chave mostra a que empresa pertence.
  • A geração passou a permitir limitar o que a chave acessa, módulo a módulo. O padrão continua acesso total — chave de API costuma servir à integração da própria empresa —, mas quem precisa de uma chave restrita não depende mais de gerá-la pela API. A lista oferecida é a mesma que a verificação usa: o que o plano da empresa libera.
  • Escopo de chave não é editável depois de criada: para mudar o alcance, gere outra e revogue a anterior. Só a restrição por IP continua ajustável.

Escopos

  • Dois escopos novos no módulo empresas: criar_empresa e gerar_chave. Eles não vêm junto do write — precisam ser marcados um a um na criação do aplicativo, porque abrir empresa mexe no que a conta paga e emitir chave dá acesso total aos dados daquela empresa. Nenhum token existente perdeu acesso a algo que já tinha.

v1.5.0 - 7 de agosto de 2026

A Atendente IA passa a responder com o material da sua empresa, e você alimenta essa base pela API.

CRM — Conhecimento da IA

  • GET /v1/crm/conhecimento/ lista o material publicado; POST publica por arquivo (PDF, Word, texto, Markdown) ou por texto direto. O envio entra numa fila: a resposta volta com situacao: "na_fila" e você consulta depois o resultado.
  • Reenviar o mesmo conteúdo não duplica. Texto idêntico ao de um material já publicado devolve 200 com o item existente, o que torna seguro rodar a sincronização quantas vezes quiser.
  • PATCH /v1/crm/conhecimento/{id}/ liga, desliga, renomeia ou manda processar de novo. DELETE remove o registro, os trechos indexados e o arquivo.
  • GET /v1/crm/conhecimento/testar/?termo=... devolve exatamente os trechos que a atendente receberia para aquela pergunta — dá para conferir se o material responde antes do cliente perguntar.
  • PDF digitalizado é recusado, com o motivo em erro. Sem texto dentro do arquivo, a atendente nunca conseguiria usar o material; recusar é mais honesto que aceitar.
  • Limites: 10 MB e 200 páginas por arquivo. Material maior deve ser dividido.
  • O conteúdo é isolado por empresa: não entra na base pública, não é indexado e nenhuma outra empresa enxerga.

Nomenclatura

  • A "Vendedora IA" passou a se chamar Atendente IA em toda a interface e na documentação. Nenhum campo ou rota mudou de nome.

v1.4.1 - 25 de julho de 2026

Rotação do refresh token: integração ativa deixa de cair sozinha, e token copiado é detectado.

OAuth 2.0

  • O refresh_token agora é rotacionado. Cada renovação devolve um refresh novo e invalida o anterior. A resposta de grant_type=refresh_token passou a incluir os campos refresh_token e refresh_expires_in.
  • Janela deslizante: o prazo de 30 dias passa a contar da última renovação, não da autorização original. Antes, um aplicativo que renovava todos os dias mesmo assim perdia o acesso no trigésimo dia e obrigava o usuário a autorizar de novo.
  • Detecção de reuso: apresentar um refresh que já foi trocado devolve invalid_grant e encerra a sessão inteira. Um token usado duas vezes indica cópia — ou que o cliente perdeu a resposta de uma renovação. Nos dois casos, a reautorização é o caminho seguro.
  • O que muda para quem integra: guarde o refresh_token novo a cada renovação, em armazenamento durável, antes de dar a renovação por concluída. Não renove em paralelo a partir de duas instâncias com o mesmo token. Os exemplos em Python e JavaScript do guia de OAuth foram atualizados com a persistência.

v1.4.0 - 25 de julho de 2026

O inbox do CRM passa a funcionar nos dois sentidos: abrir conversa, responder, enviar anexo e recuperar o que passou.

CRM — conversas e mensagens

  • POST /v1/crm/conversas/ abre conversa por e-mail, SMS ou WhatsApp não oficial. Idempotente por canal: devolve a conversa já aberta em vez de duplicar o histórico.
  • POST /v1/crm/mensagens/ envia texto pelo canal da conversa; POST /v1/crm/mensagens/anexo/ envia imagem, documento, áudio ou vídeo (multipart). Mensagens enviadas por integração ficam com remetente_tipo: "integracao".
  • Cursor de recuperação: GET /v1/crm/mensagens/?apos_id={id} e ?desde={ISO} percorrem a empresa inteira, para reconciliar o que se perdeu enquanto o seu sistema esteve fora do ar. Do lado das conversas, ?atualizadas_desde={ISO}. Sem nenhum recorte, a listagem devolve vazio de propósito.
  • Arquivar e desarquivar conversa (/arquivar/, /desarquivar/): sai do inbox sem apagar nada, e mensagem nova do contato traz de volta sozinha. Não existe rota para excluir conversa.
  • Marcar como lida, pausar e retomar a Atendente IA na conversa, e registrar anotação interna.
  • A resposta de mensagem passou a trazer os mesmos campos que o webhook entrega: canal, contato_id, midia, resposta_a_id, mensagem_id_externo, entregue, enviada_em, entregue_em, lida_em. Adição de campos, sem quebra.

CRM — canais, modelos e contatos

  • GET /v1/crm/canais/ diz por onde a empresa pode falar e o que cada canal permite (pode_iniciar_texto_livre, exige_modelo_aprovado).
  • GET /v1/crm/whatsapp/modelos/ lista os modelos aprovados; POST /v1/crm/whatsapp/modelos/{id}/enviar/ dispara um deles — o único caminho para puxar assunto no WhatsApp oficial.
  • POST /v1/crm/contatos/casar/ descobre a qual contato pertence um telefone ou e-mail, devolvendo apenas o identificador.

Escopos

  • Novo escopo crm: whatsapp_modelo, exigido para disparar modelo de WhatsApp. Ele não vem junto do write: o disparo consome saldo na plataforma e afeta a reputação do número, então precisa ser liberado de propósito no token. Nenhum token existente perdeu acesso — a rota é nova.

Webhooks

  • Cinco eventos novos: conversa.atribuida, conversa.aguardando_atendente, mensagem.entregue, mensagem.lida e mensagem.falhou. Os três de mensagem hoje valem para o WhatsApp.
  • Payload mais completo (adição de campos, sem quebra): os eventos de conversa e mensagem passam a trazer o contato identificado, o canal, a mídia, o resposta_a_id e o mensagem_id_externo da plataforma de origem. Antes era preciso fazer duas chamadas de volta só para saber de quem era a mensagem.
  • conversa.atualizada mudou de significado: agora indica mudança de estado (situação, dono, arquivamento). Alteração que só mexe em carimbo de hora não gera mais evento — isso dobrava o volume entregue sem informação nova. Para acompanhar tráfego, use mensagem.recebida e mensagem.enviada.
  • Correção: mensagem.recebida não disparava nas mensagens que entravam pelo chat do site, Telegram, formulário e e-mail. Agora vale para todos os canais.

v1.3.0 - 26 de junho de 2026

API de CRM ampliada, novos eventos de webhook e renomeação dos headers de webhook.

CRM

  • Novos recursos na API de CRM: contatos (com mascaramento de dados pessoais na leitura — LGPD), atividades, itens de negócio, conversas e mensagens, etiquetas, funis e motivos de perda
  • Ações de negócio: mover-etapa, ganhar e perder (mudança de estado leve, desacoplada do ERP)
  • 14 eventos de webhook do CRM: contato.criado/atualizado/arquivado/etiqueta_alterada, negocio.criado/atualizado/etapa_alterada/ganho/perdido, conversa.criada/atualizada/concluida, mensagem.recebida/enviada

Webhooks

  • Breaking: os headers de entrega foram renomeados de X-Bunto-* para X-Webhook-* (X-Webhook-Signature, X-Webhook-Evento, X-Webhook-Id, X-Webhook-Timestamp, X-Webhook-Idempotency-Key). Atualize a verificação da assinatura do seu endpoint para ler X-Webhook-Signature.

v1.2.0 - 13 de fevereiro de 2026

OAuth 2.0 Authorization Code para integrações de terceiros.

OAuth 2.0

  • Fluxo completo OAuth 2.0 Authorization Code Grant (RFC 6749)
  • Registro de aplicativos com client_id e client_secret (prefixos bnt_app_ e bnt_secret_)
  • Tela de consentimento para o usuário autorizar acesso granular
  • Endpoint de autorização: GET /integracoes/oauth/authorize/
  • Endpoint de token: POST /integracoes/oauth/token/
  • Endpoint de revogação: POST /integracoes/oauth/revoke/ (RFC 7009)
  • Access tokens OAuth (bnt_oat_) com validade de 4 horas
  • Refresh tokens (bnt_ort_) com validade de 30 dias
  • Escopos granulares por módulo e ação (produtos:read, vendas:write, etc.)
  • Tokens criptografados com Fernet (nunca armazenados em texto puro)
  • Código de autorização de uso único com expiração de 10 minutos
  • Proteção CSRF via parâmetro state
  • Validação exata de redirect_uri (sem wildcards)
  • Comparação constant-time com hmac.compare_digest
  • Limite de 5 aplicativos por empresa e 5 redirect URIs por aplicativo
  • Documentação completa com exemplos em Python, JavaScript, PHP, Java, C# e Go

Remoções

  • Removido endpoint /v1/chat-ia/ por questões de conformidade LGPD (mensagens do chat podem conter dados sensíveis)

v1.1.0 - 13 de fevereiro de 2026

Webhooks em tempo real para todos os módulos principais.

Webhooks

  • Sistema completo de webhooks com notificações via HTTP POST
  • 12 eventos disponíveis: produto, cliente, venda, estoque e NF-e
  • Assinatura HMAC-SHA256 em cada requisição (header X-Bunto-Signature, renomeado para X-Webhook-Signature na v1.3.0)
  • Backoff exponencial com até 10 tentativas configuráveis
  • Headers de idempotência para evitar processamento duplicado
  • Conformidade LGPD: dados sensíveis de clientes (CPF/CNPJ, e-mail, telefone) mascarados automaticamente
  • Validação SSRF: bloqueio de IPs privados, localhost e metadata endpoints
  • Funciona para operações via painel do ERP e via API externa
  • Documentação completa com exemplos em Python, JavaScript, PHP, Java, C# e Go
  • Retenção de logs de entrega: 30 dias (limpeza automática diária)

Eventos disponíveis

EventoDescrição
produto.criadoNovo produto cadastrado
produto.atualizadoDados do produto alterados
produto.excluidoProduto removido
cliente.criadoNovo cliente cadastrado
cliente.atualizadoDados do cliente alterados
cliente.excluidoCliente removido
venda.criadaNova venda/pedido registrado
venda.atualizadaDados da venda alterados
venda.canceladaVenda cancelada
estoque.atualizadoMovimentação de estoque
nfe.emitidaNF-e autorizada pela SEFAZ
nfe.canceladaNF-e cancelada

Auditoria

  • Criação, revogação e exclusão de tokens API auditadas automaticamente
  • Criação e exclusão de webhooks auditadas
  • Criação, desativação e exclusão de aplicativos OAuth auditadas
  • Integração com módulo de Ocorrências (IP e User Agent registrados)

v1.0.0 - 13 de fevereiro de 2026

Lançamento inicial da API pública do Bunto ERP.

Novos Endpoints (33 total)

E-commerce e Catálogo

  • GET/POST/PUT/PATCH/DELETE /v1/produtos/ - CRUD completo de produtos
  • GET/POST/PUT/PATCH/DELETE /v1/categorias/ - Gerenciar categorias de produtos
  • GET/POST/PUT/PATCH/DELETE /v1/marcadores/ - Tags coloridas para organização
  • GET/POST/PUT/PATCH/DELETE /v1/embalagens/ - Cadastro de embalagens personalizadas
  • GET/POST/PUT/PATCH/DELETE /v1/servicos/ - CRUD de serviços prestados

Vendas e Estoque

  • GET/POST/PUT/PATCH/DELETE /v1/vendas/ - Pedidos de venda com itens
  • GET/POST /v1/estoque/ - Consulta e lançamentos de movimentação
  • GET/POST/PUT/PATCH/DELETE /v1/pdv/ - Vendas do ponto de venda
  • GET/POST/PUT/PATCH/DELETE /v1/propostas/ - Orçamentos e propostas comerciais
  • GET/POST/PUT/PATCH/DELETE /v1/devolucoes/ - Devoluções de mercadorias
  • GET/POST/PUT/PATCH/DELETE /v1/vale-troca/ - Vales de troca emitidos

Clientes e CRM

  • GET/POST/PUT/PATCH/DELETE /v1/clientes/ - Cadastros com conformidade LGPD
  • GET/POST/PUT/PATCH/DELETE /v1/crm/ - Oportunidades e pipeline de vendas

Finanças

  • GET/POST/PUT/PATCH/DELETE /v1/financas/ - Contas a pagar e receber
  • GET /v1/contas/ - Contas bancárias (somente leitura)
  • GET/POST/PUT/PATCH/DELETE /v1/cobrancas-bancarias/ - Boletos e cobranças
  • GET/POST/PUT/PATCH/DELETE /v1/naturezas/ - Naturezas de receita/despesa

Compras e Fiscal

  • GET/POST/PUT/PATCH/DELETE /v1/compras/ - Pedidos de compra com itens
  • GET /v1/nf/ - Notas fiscais NFe/NFCe (somente leitura)
  • GET /v1/nfse/ - Notas fiscais de serviço (somente leitura)
  • GET/POST/PUT/PATCH/DELETE /v1/regras-tributarias/ - Regras de tributação
  • GET/POST/PUT/PATCH/DELETE /v1/distribuicao-dfe/ - Distribuição de DF-e

Logística

  • GET/POST/PUT/PATCH/DELETE /v1/logistica/ - Formas de envio
  • GET/POST/PUT/PATCH/DELETE /v1/expedicao/ - Agrupamentos de expedição

Marketing e Operacional

  • GET/POST/PUT/PATCH/DELETE /v1/marketing/ - Conversões offline (Google/Meta Ads)
  • GET/POST/PUT/PATCH/DELETE /v1/ocorrencias/ - Registros de ocorrências
  • GET/POST/PUT/PATCH/DELETE /v1/agenda/ - Compromissos e tarefas

Sistema

  • GET/POST/PUT/PATCH/DELETE /v1/arquivos/ - Upload e gerenciamento de arquivos
  • GET/PUT/PATCH /v1/configuracoes/ - Configurações da empresa
  • GET/POST/PUT/PATCH/DELETE /v1/usuarios/ - Gerenciar usuários
  • GET/PUT/PATCH /v1/empresas/ - Dados da empresa (atualização apenas)
  • GET /v1/dashboard/ - Estatísticas e indicadores

Autenticação e Segurança

  • Autenticação via Bearer Token (Authorization: Bearer bnt_xxx...)
  • Tokens com prefixo bnt_ identificam APIs do Bunto ERP
  • Sistema de escopos granulares: read, write, delete por módulo
  • Multi-tenancy com isolamento total por empresa
  • Rate limiting inteligente:
    • 120 requisições/min para leitura (GET)
    • 30 requisições/min para escrita (POST/PUT/PATCH)
    • 10 requisições/min para exclusão (DELETE)
  • Headers informativos: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Formato de Respostas

Todas as respostas seguem envelope padronizado:

Sucesso (listagem):

json
{
  "success": true,
  "message": "42 registros encontrados",
  "data": {
    "resultados": [...],
    "paginacao": {
      "pagina_atual": 1,
      "total_paginas": 5,
      "total_registros": 42,
      "por_pagina": 10,
      "proxima": "https://...",
      "anterior": null
    }
  }
}

Sucesso (criação/atualização):

json
{
  "success": true,
  "message": "Produto criado com sucesso",
  "data": { ... }
}

Erro:

json
{
  "success": false,
  "message": "Este campo é obrigatório.",
  "errors": {
    "nome": ["Este campo é obrigatório."],
    "preco": ["Informe um número válido."]
  }
}

Recursos da API

  • Paginação automática: Query params ?pagina=1&por_pagina=25 (máx: 100)
  • Busca: Filtro ?busca=termo em endpoints de listagem
  • Ordenação: ?ordenar=campo&direcao=asc|desc
  • Filtros contextuais: Por status, tipo, período, categoria, etc.
  • Soft delete: Maioria dos endpoints usa exclusão lógica
  • LGPD: Campos sensíveis de clientes são criptografados
  • Respostas consistentes: Mesmo formato em todos os endpoints

Documentação

  • Guia de Início Rápido com exemplos em curl, Python e JavaScript
  • 33 endpoints documentados com exemplos reais
  • Códigos de erro e troubleshooting
  • Classes prontas: BuntoAPI (Python) e BuntoClient (JavaScript)

Base URLs

  • Produção: https://api-backend.bunto.com.br/v1/
  • Staging: https://api-staging.bunto.com.br/v1/

Casos de Uso

Esta versão inicial suporta:

  • Integração com e-commerces (Wix, VTEX, Shopify, ML, etc.)
  • Sincronização bidirecional de produtos e estoque
  • Importação de pedidos de marketplaces
  • Conversões offline para Google Ads e Meta Ads
  • Dashboards externos consumindo dados do ERP
  • Automações via Zapier, Make, n8n
  • Apps mobile personalizados
  • Relatórios e BI externos

Próximas Versões

Planejado para v1.2 (Q2 2026):

  • Suporte a uploads multipart/form-data
  • Expansão de endpoints fiscais (emissão de NF-e)
  • Filtros avançados com operadores (gt, lt, in, contains)

Feedback e sugestões: developers@bunto.com.br

APIChangelogReleasesVersao
Recursos para IA
Voltar para a documentação