API de Integrações

A API de Integrações do bitERP permite que sistemas externos realizem operações CRUD em recursos do ERP via endpoints REST.

Base URL

https://api.biterp.ai

Características

• Autenticação dupla: API Keys (machine-to-machine) ou OAuth2 Authorization Code (Zapier, Make, n8n)
• Permissões granulares: controle por recurso e ação (create, read, update, delete)
• Paginação por cursor: navegação eficiente em listas grandes
• Filtros estilo Stripe: query params planos com bracket notation para operadores
• Versionamento por header: header api-version para compatibilidade futura
• OpenAPI spec: especificação gerada automaticamente para referência de endpoints
• Webhooks de saída: notificações assinadas enviadas ao seu servidor quando um recurso muda, sem polling

Recursos disponíveis

Para cada recurso há um guia narrativo (o que é, ciclo de vida, fluxos) e a referência endpoint a endpoint — veja, por exemplo, o guia de Produtos. Os recursos estão organizados por domínio:

Cadastros

Financeiro

Vendas e faturamento

O guia Fluxo de vendas costura orçamento → pedido → nota → contas a receber.

Compras

Dados de referência (somente leitura)

Bancos (/banks), formas de pagamento (/payment-methods), unidades de medida (/units-of-measurement), países (/countries), estados (/states) e cidades (/cities) são catálogos consultados nos cadastros. Ver o guia Dados de referência.

Integração

Utilitários

Consulte a referência OpenAPI para health, tenant e oauth/token. O fluxo de autenticação está em Autenticação.

A maioria dos recursos de negócio expõe operações padrão de listagem, busca por ID, criação, atualização e remoção — veja a referência OpenAPI de cada recurso e os guias narrativos para endpoints específicos.

A referência completa de endpoints é gerada automaticamente a partir da especificação OpenAPI. Veja a Referência da API.

DELETE é de mão única

DELETE /:id faz soft delete: o registro sai das listagens e das buscas, mas continua no banco para preservar histórico e referências.

Não existe endpoint de restauração nesta API — em nenhum recurso. Não é uma lacuna a ser preenchida: desfazer uma exclusão é uma operação de usuário, feita no painel do bitERP por alguém autenticado, e não por um sistema externo. Do ponto de vista da sua integração, trate todo DELETE como definitivo e confirme antes de chamar.

Webhooks

Além de consultar a API, você pode ser notificado quando algo muda no ERP. Um administrador registra uma URL HTTPS no painel do bitERP, escolhe os eventos e passa a receber um POST assinado a cada criação, atualização, exclusão ou restauração de recurso.

O payload identifica o recurso que mudou; os dados completos você busca com o GET /:id correspondente. Ver Webhooks.

Formato de resposta

Todas as respostas usam JSON. Listagens retornam dados paginados, com os metadados de navegação em pagination:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "has_next_page": true,
    "has_previous_page": false,
    "next_cursor": "eyJmIjoiY3JlYXRlZF9hdCIsInYiOi...",
    "previous_cursor": null
  },
  "meta": {
    "sort": { "field": "created_at", "order": "asc" }
  }
}

Recursos individuais retornam o objeto diretamente:

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Notebook Dell",
    "sale_price": "4500.000000",
    "is_active": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
}

Valores decimais são strings

Todo campo decimal ou monetário trafega como string, no formato numeric(18,6) — sempre com 6 casas decimais —, tanto na requisição quanto na resposta. O motivo é precisão: o number do JSON é um float de ponto flutuante (IEEE 754) e arredonda valores financeiros de forma silenciosa. A string preserva o valor exato.

{
    "amount": "1250.000000",
    "quantity": "2.000000",
    "unit_price": "450.000000"
}

Isso vale para campos como amount, total_amount, allocated_amount, discount_amount, surcharge_amount, unit_price, sale_price, cost_price, quantity, initial_balance, subtotal, total, base_amount, entre outros. Campos que aceitam sinal (como o amount de uma transação financeira e o initial_balance) usam o - na própria string: "-250.500000".

Percentuais também são strings. Alíquotas e taxas (rate, discount_rate) usam a escala de 0 a 100 e trafegam como decimal numeric(9,6) em string — "18.000000" é 18%. Isso vale para todos os recursos, inclusive notas. Já contadores e índices (installment_count, position, display_order, limit) são inteiros e seguem como number — esses, sim, nunca envie como string.

Ao consumir a API, não converta os decimais para float na sua linguagem: use um tipo decimal (BigDecimal, decimal.Decimal, Decimal.js) ou mantenha a string.

Próximos passos