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.

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, status (opcionais, status default "ativo") e id_qsa_cliente (sócio vinculado à conta, opcional). O sócio deve ser do mesmo cliente do plano de contas e estar ativo: sócio inexistente retorna 404; de outro cliente ou inativo, 422.

Request

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

Response 201 Created

{
  "status": "success",
  "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",
    "id_qsa_cliente": 10,
    "nome_socio": "João da Silva"
  }
}

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

{
  "status": "success",
  "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",
      "id_qsa_cliente": null,
      "nome_socio": null
    }
  ]
}

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âmetroTipoLocalObrigatórioDescrição
usuario_idintpathsimID do usuário dono

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "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",
      "id_qsa_cliente": null,
      "nome_socio": null
    }
  ]
}

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âmetroTipoLocalObrigatórioDescrição
id_plano_contasintpathsimID do plano de contas.
qstrquerynãoTermo de busca typeahead (até 100 caracteres): filtra por codigo_dominio/nome (LIKE). Vazio (?q=) não filtra o texto, mas limita a limit. Omitido → lista completa.
limitintquerynãoMáximo de resultados no modo typeahead (1 a 200, default 50). Só tem efeito junto com q (inclusive vazio).

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "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",
      "id_qsa_cliente": null,
      "nome_socio": null
    }
  ]
}

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âmetroTipoLocalObrigatórioDescrição
conta_idintpathsimID interno da conta

Request

Sem corpo de requisição.

Response 200 OK

{
  "status": "success",
  "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âmetroTipoLocalObrigatórioDescrição
conta_idintpathsimID da conta

Request (ContasUpdate - todos os campos opcionais)

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

Response 200 OK

{
  "status": "success",
  "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",
    "id_qsa_cliente": null,
    "nome_socio": null
  }
}

Escopo: contas:write

DELETE /contas/{conta_id}

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

Parâmetros

ParâmetroTipoLocalObrigatórioDescrição
conta_idintpathsimID 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

CampoTipoObrigatórioObservações
id_plano_contasintsimID do plano de contas ao qual a conta pertence.
codigo_dominiostrsimCódigo da conta no Domínio (único por plano de contas). 1-50 caracteres.
codigo_contabilstrnãoCódigo contábil da conta (origem: arquivo Domínio). Máx. 50 caracteres.
nomestrsimNome/descrição da conta contábil. 1-300 caracteres.
tipo"A" | "S"nãoTipo da conta: A (Analítica) ou S (Sintética).
status"ativo" | "inativo"nãoStatus da conta. Default "ativo".
id_qsa_clienteintnãoSócio (customer_qsa.id) vinculado à conta. Deve ser do mesmo cliente do plano e estar ativo. null = sem sócio.

ContasUpdate

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

CampoTipoObservações
codigo_dominiostrCódigo da conta no Domínio. 1-50 caracteres.
codigo_contabilstrCódigo contábil da conta. Máx. 50 caracteres.
nomestrNome/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.
id_qsa_clienteintSócio vinculado. Omitido mantém; null explícito desvincula.

ContasRead

CampoTipoNotas
idintIdentificador da conta.
id_usuario_createdintUsuário que criou a conta.
id_plano_contasintPlano de contas ao qual a conta pertence.
data_hora_criacaodatetimeData/hora da criação (fuso America/Sao_Paulo).
codigo_dominiostrCódigo da conta no Domínio.
codigo_contabilstrCódigo contábil (pode ser nulo).
nomestrNome/descrição da conta.
tipostrA (Analítica) ou S (Sintética); pode ser nulo.
statusstrativo ou inativo.
id_qsa_clienteint | nullSócio vinculado à conta.
nome_sociostr | nullNome do sócio vinculado (somente leitura).

Notas

  • Toda resposta segue o envelope { status, message, data } (erros de negócio vêm como { "message": ... } e a validação de entrada como 422 com { "detail": [...] }).
  • 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.