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

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

GET /tenant retorna o tenant atual, GET /health é o health check e POST /oauth/token faz parte do fluxo de autenticação.

A maioria dos recursos de negócio suporta as operações padrões: listar (GET), buscar por ID (GET /:id), criar (POST), atualizar (PATCH /:id) e remover (DELETE /:id), além de endpoints específicos descritos em cada guia.

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

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": "desc" }
  }
}

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 e inteiros continuam como number. Alíquotas e taxas (rate, discount_rate) são percentuais de 0 a 100 (18 = 18%) — exceto o discount_rate de notas, que é uma fração de 0 a 1. Contadores e índices (installment_count, position, display_order, limit) são inteiros. Não envie nenhum deles 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