Contas

Endpoints da WebApiAlcance para gerenciar contas contábeis - cada conta pertence a um plano de contas e representa uma linha do plano (analítica ou sintética), com código Domínio, código contábil, nome e status. Cobrem criação, listagem geral do usuário autenticado, listagem por usuário, listagem por plano de contas, detalhamento por ID, atualização e exclusão.

Todos os endpoints exigem autenticação. Veja Autenticação para o fluxo de API Key. O Swagger oficial está em api.contabilidadealcance.com.br/docs.

Base path

/api/v1/contas

Escopos necessários

contas:read - listagem, listagem por usuário, listagem por plano de contas e detalhamento
contas:write - criação, atualização e exclusão

O escopo é derivado da rota: o prefixo /contas vira o recurso contas, e o método HTTP define a ação (read para GET, write para POST/PUT/DELETE).

Endpoints

`POST /contas/`

Cria uma nova conta contábil vinculada a um plano de contas. O id_usuario_created é preenchido a partir do usuário autenticado - não é aceito no corpo.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ContasCreate): id_plano_contas, codigo_dominio e nome (obrigatórios); codigo_contabil, tipo e status (opcionais, status default "ativo").

Request

{
  "id_plano_contas": 3,
  "codigo_dominio": "1.1.01.001",
  "codigo_contabil": "110101001",
  "nome": "Caixa Geral",
  "tipo": "A",
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Conta criada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "codigo_dominio": "1.1.01.001",
    "codigo_contabil": "110101001",
    "nome": "Caixa Geral",
    "tipo": "A",
    "status": "ativo"
  }
}

Escopo: contas:write

`GET /contas/`

Lista todas as contas do usuário autenticado. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma conta encontrada.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contas recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "id_usuario_created": 7,
      "id_plano_contas": 3,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00",
      "codigo_dominio": "1.1.01.001",
      "codigo_contabil": "110101001",
      "nome": "Caixa Geral",
      "tipo": "A",
      "status": "ativo"
    }
  ]
}

Escopo: contas:read

`GET /contas/usuario/{usuario_id}`

Lista as contas de um usuário específico. O acesso é restrito ao próprio usuário - solicitar contas de outro usuário resulta em 403 Forbidden (detail contendo "acesso negado").

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`usuario_id`	`int`	path	sim	ID do usuário dono

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contas recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "id_usuario_created": 7,
      "id_plano_contas": 3,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00",
      "codigo_dominio": "1.1.01.001",
      "codigo_contabil": "110101001",
      "nome": "Caixa Geral",
      "tipo": "A",
      "status": "ativo"
    }
  ]
}

Escopo: contas:read

`GET /contas/plano-contas/{id_plano_contas}`

Lista as contas de um plano de contas específico (apenas as do usuário autenticado). Suporta typeahead opt-in: com q, faz busca por codigo_dominio/nome (LIKE), ordenada e limitada a limit; sem q, retorna a lista completa do plano (comportamento legado, preservando o fan-out existente).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_plano_contas`	`int`	path	sim	ID do plano de contas.
`q`	`str`	query	não	Termo de busca typeahead (1 a 100 caracteres): filtra por `codigo_dominio`/`nome` (LIKE). Omitido → lista completa.
`limit`	`int`	query	não	Máximo de resultados no modo typeahead (1 a 200, default `50`). Só tem efeito junto com `q`.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contas recuperadas com sucesso",
  "data": [
    {
      "id": 42,
      "id_usuario_created": 7,
      "id_plano_contas": 3,
      "data_hora_criacao": "2026-07-03T10:15:00-03:00",
      "codigo_dominio": "1.1.01.001",
      "codigo_contabil": "110101001",
      "nome": "Caixa Geral",
      "tipo": "A",
      "status": "ativo"
    }
  ]
}

Escopo: contas:read

`GET /contas/{conta_id}`

Detalha uma conta do usuário autenticado pelo ID inteiro. Quando não encontrada, retorna 404 Not Found com detail descrevendo o erro.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`conta_id`	`int`	path	sim	ID interno da conta

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Conta encontrada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "codigo_dominio": "1.1.01.001",
    "codigo_contabil": "110101001",
    "nome": "Caixa Geral",
    "tipo": "A",
    "status": "ativo"
  }
}

Escopo: contas:read

`PUT /contas/{conta_id}`

Atualiza uma conta existente do usuário autenticado. O corpo é um ContasUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`conta_id`	`int`	path	sim	ID da conta

Request (ContasUpdate - todos os campos opcionais)

{
  "nome": "Caixa Matriz",
  "status": "inativo"
}

Response 200 OK

{
  "success": true,
  "message": "Conta atualizada com sucesso",
  "data": {
    "id": 42,
    "id_usuario_created": 7,
    "id_plano_contas": 3,
    "data_hora_criacao": "2026-07-03T10:15:00-03:00",
    "codigo_dominio": "1.1.01.001",
    "codigo_contabil": "110101001",
    "nome": "Caixa Matriz",
    "tipo": "A",
    "status": "inativo"
  }
}

Escopo: contas:write

`DELETE /contas/{conta_id}`

Remove permanentemente uma conta contábil do usuário autenticado pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`conta_id`	`int`	path	sim	ID da conta

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta. Quando a conta não existe, retorna 404 Not Found.

Escopo: contas:write

Schemas

`ContasCreate`

Campo	Tipo	Obrigatório	Observações
`id_plano_contas`	`int`	sim	ID do plano de contas (`plano_contas.id`) ao qual a conta pertence.
`codigo_dominio`	`str`	sim	Código da conta no Domínio (único por plano de contas). 1-50 caracteres.
`codigo_contabil`	`str`	não	Código contábil da conta (origem: arquivo Domínio). Máx. 50 caracteres.
`nome`	`str`	sim	Nome/descrição da conta contábil. 1-300 caracteres.
`tipo`	`"A"` \| `"S"`	não	Tipo da conta: `A` (Analítica) ou `S` (Sintética).
`status`	`"ativo"` \| `"inativo"`	não	Status da conta. Default `"ativo"`.

`ContasUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados.

Campo	Tipo	Observações
`codigo_dominio`	`str`	Código da conta no Domínio. 1-50 caracteres.
`codigo_contabil`	`str`	Código contábil da conta. Máx. 50 caracteres.
`nome`	`str`	Nome/descrição da conta. 1-300 caracteres.
`tipo`	`"A"` \| `"S"`	Tipo da conta: `A` (Analítica) ou `S` (Sintética).
`status`	`"ativo"` \| `"inativo"`	Novo status.

`ContasRead`

Campo	Tipo	Notas
`id`	`int`	Identificador da conta.
`id_usuario_created`	`int`	Usuário que criou a conta.
`id_plano_contas`	`int`	Plano de contas ao qual a conta pertence.
`data_hora_criacao`	`datetime`	Data/hora da criação (fuso `America/Sao_Paulo`).
`codigo_dominio`	`str`	Código da conta no Domínio.
`codigo_contabil`	`str`	Código contábil (pode ser nulo).
`nome`	`str`	Nome/descrição da conta.
`tipo`	`str`	`A` (Analítica) ou `S` (Sintética); pode ser nulo.
`status`	`str`	`ativo` ou `inativo`.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
O campo data_hora_criacao é sempre devolvido no fuso de Brasília (America/Sao_Paulo).
As rotas estáticas GET /contas/usuario/{usuario_id} e GET /contas/plano-contas/{id_plano_contas} são declaradas antes da rota dinâmica GET /contas/{conta_id}, então são resolvidas corretamente sem conflito com o conta_id.
GET /contas/usuario/{usuario_id} só permite consultar as próprias contas - pedir dados de outro usuário retorna 403 Forbidden.
codigo_dominio é único por plano de contas; conflitos podem resultar em 409 Conflict.
Relaciona-se com o Plano de Contas, que agrupa as contas contábeis por cliente/estrutura.