Permissões

O bitERP usa um modelo de permissões granular por recurso e ação. Cada API Key ou usuário OAuth tem permissões específicas que controlam o que pode ser acessado.

Modelo de permissões

Cada permissão é composta por:

Campo	Descrição	Exemplo
`resource_code`	Código do recurso	`products`, `customers`
`can_create`	Permissão para criar	`true` / `false`
`can_read`	Permissão para listar e buscar	`true` / `false`
`can_update`	Permissão para atualizar	`true` / `false`
`can_delete`	Permissão para remover	`true` / `false`

Como funciona

Com API Keys

As permissões são definidas na criação da API Key e são imutáveis — não podem ser alteradas depois. Para mudar permissões, crie uma nova key.

Exemplo: uma API Key com permissão products:read e products:create pode listar e criar produtos, mas não pode atualizar ou deletar.

Com OAuth2

O comportamento depende da role do usuário:

Role	Comportamento
`admin`	Acesso completo (bypass de permissões)
`member`	Permissões granulares por recurso, idênticas ao modelo de API Keys

Respostas de erro

Quando uma operação é negada por falta de permissão, a API retorna:

{
    "status_code": 403,
    "message": "Forbidden",
    "error": "You do not have permission to perform this action"
}

Estes são os resource_code aceitos na criação de uma API Key, com as ações que cada um expõe na API de Integrações. Conceder uma ação que o recurso não expõe (por exemplo can_create em um catálogo de referência) não habilita nada.

Os códigos usam hífen, não underscore — é financial-accounts, nunca financial_accounts. Um código inexistente não gera erro na criação da key: ele simplesmente não concede permissão nenhuma, e as chamadas passam a responder 403.

Cadastros

Código	Recurso	Ações
`products`	Produtos	`create`, `read`, `update`, `delete`
`customers`	Clientes	`create`, `read`, `update`, `delete`
`suppliers`	Fornecedores	`create`, `read`, `update`, `delete`

Financeiro

Código	Recurso	Ações
`financial-accounts`	Contas financeiras	`create`, `read`, `update`, `delete`
`financial-categories`	Categorias financeiras	`create`, `read`, `update`, `delete`
`financial-transactions`	Transações financeiras	`read`, `delete`
`receivables`	Contas a receber	`create`, `read`, `update`, `delete`
`payables`	Contas a pagar	`create`, `read`, `update`, `delete`

Vendas, faturamento e compras

Código	Recurso	Ações
`quotes`	Orçamentos	`create`, `read`, `update`, `delete`
`sales-orders`	Pedidos de venda	`create`, `read`, `update`, `delete`
`invoices`	Notas / faturas	`create`, `read`, `update`, `delete`
`purchase-invoices`	Notas de compra	`create`, `read`, `update`, `delete`

Dados de referência (somente leitura)

Código	Recurso	Ações
`banks`	Bancos	`read`
`payment-methods`	Formas de pagamento	`read`
`units-of-measurement`	Unidades de medida	`read`
`countries`	Países	`read`
`states`	Estados	`read`
`cities`	Cidades	`read`

Integração

Código	Recurso	Ações
`integration-mappings`	Mapeamento de entidades	`create`, `read`, `update`, `delete`

⚠️ O código de permissão é integration-mappings, mas o caminho da URL é /integration-entity-mappings. É a única divergência entre código e rota na API — ver o guia do recurso.

Sem permissão específica

GET /tenant e GET /health não exigem permissão de recurso: qualquer credencial válida acessa o próprio tenant, e o health check é público.

Boas práticas

Princípio do menor privilégio: conceda apenas as permissões necessárias para a integração
Keys separadas por integração: crie uma API Key diferente para cada sistema que integra com o bitERP
Expiração: configure expires_at sempre que possível
Revogação: revogue keys que não são mais necessárias