Changelog - API v1

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

---

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)
• 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

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