Plano de Contas

Endpoints da WebApiAlcance para gerenciar planos de contas - cada plano pertence a um cliente e agrupa as contas contábeis usadas nos lançamentos. Cobrem criação, listagem geral, listagem por usuário, listagem por cliente, detalhamento por ID, atualização, exclusão e a importação de contas a partir de um arquivo TXT exportado do sistema Domínio.

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/plano-contas

Escopos necessários

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

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

Endpoints

`POST /plano-contas/`

Cria um novo plano de contas vinculado a um cliente. 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 (PlanoContasCreate): id_cliente (obrigatório), codigo_dominio (obrigatório), nome (obrigatório) e status (opcional, default "ativo").

Request

{
  "id_cliente": 128,
  "codigo_dominio": "PC-2026",
  "nome": "Plano de Contas Padrão 2026",
  "status": "ativo"
}

Response 201 Created

{
  "success": true,
  "message": "Plano de contas criado com sucesso",
  "data": {
    "id": 34,
    "id_usuario_created": 7,
    "id_cliente": 128,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "codigo_dominio": "PC-2026",
    "nome": "Plano de Contas Padrão 2026",
    "status": "ativo"
  }
}

Conflitos (codigo_dominio duplicado para o cliente) retornam 409 Conflict; validações de negócio retornam 422 Unprocessable Entity.

Escopo: plano_contas:write

`GET /plano-contas/`

Lista todos os planos de contas do usuário autenticado. Lista vazia é um estado válido - retorna 200 OK com data: [] e a mensagem "Nenhum plano de contas encontrado.".

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": "Planos de contas recuperados com sucesso",
  "data": [
    {
      "id": 34,
      "id_usuario_created": 7,
      "id_cliente": 128,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "codigo_dominio": "PC-2026",
      "nome": "Plano de Contas Padrão 2026",
      "status": "ativo"
    }
  ]
}

Escopo: plano_contas:read

`GET /plano-contas/usuario/{usuario_id}`

Lista os planos de contas de um usuário específico. Apenas o próprio usuário pode consultar seus planos - outro usuario_id resulta em acesso negado (403 Forbidden).

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Planos de contas recuperados com sucesso",
  "data": [
    {
      "id": 34,
      "id_usuario_created": 7,
      "id_cliente": 128,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "codigo_dominio": "PC-2026",
      "nome": "Plano de Contas Padrão 2026",
      "status": "ativo"
    }
  ]
}

Escopo: plano_contas:read

`GET /plano-contas/cliente/{id_cliente}`

Lista os planos de contas de um cliente específico, restritos ao usuário autenticado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_cliente`	`int`	path	sim	ID interno do cliente

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Planos de contas recuperados com sucesso",
  "data": [
    {
      "id": 34,
      "id_usuario_created": 7,
      "id_cliente": 128,
      "data_hora_criacao": "2026-07-03T09:15:00-03:00",
      "codigo_dominio": "PC-2026",
      "nome": "Plano de Contas Padrão 2026",
      "status": "ativo"
    }
  ]
}

Escopo: plano_contas:read

`GET /plano-contas/{plano_id}`

Detalha um plano de contas pelo ID inteiro. Quando não encontrado (ou pertencente a outro usuário), retorna 404 Not Found.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID interno do plano

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Plano de contas encontrado com sucesso",
  "data": {
    "id": 34,
    "id_usuario_created": 7,
    "id_cliente": 128,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "codigo_dominio": "PC-2026",
    "nome": "Plano de Contas Padrão 2026",
    "status": "ativo"
  }
}

Escopo: plano_contas:read

`PUT /plano-contas/{plano_id}`

Atualiza um plano de contas existente do usuário autenticado. O corpo é um PlanoContasUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID do plano

Request (PlanoContasUpdate - todos os campos opcionais)

{
  "nome": "Plano de Contas Revisado 2026",
  "status": "ativo"
}

Response 200 OK

{
  "success": true,
  "message": "Plano de contas atualizado com sucesso",
  "data": {
    "id": 34,
    "id_usuario_created": 7,
    "id_cliente": 128,
    "data_hora_criacao": "2026-07-03T09:15:00-03:00",
    "codigo_dominio": "PC-2026",
    "nome": "Plano de Contas Revisado 2026",
    "status": "ativo"
  }
}

Escopo: plano_contas:write

`DELETE /plano-contas/{plano_id}`

Remove permanentemente um plano de contas pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`plano_id`	`int`	path	sim	ID do plano

Request

Sem corpo de requisição.

Response 204 No Content

Sem corpo de resposta.

Quando há registros vinculados que impedem a exclusão, retorna 409 Conflict.

Escopo: plano_contas:write

`POST /plano-contas/{id_plano_contas}/importar-contas/`

Importa contas a partir de um arquivo TXT exportado do sistema Domínio, fazendo upsert por codigo_dominio. O envio é multipart/form-data com o campo arquivo.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id_plano_contas`	`int`	path	sim	ID do plano de contas que receberá as contas
`arquivo`	`UploadFile`	form	sim	Arquivo `.txt` do Domínio (encoding latin-1, separador `\|`)

Formato esperado de cada linha (sem cabeçalho): {codigo_dominio}|{codigo_contabil}|{nome}|{tipo}, onde tipo é A (Analítica) ou S (Sintética). Linhas inválidas não interrompem o lote - voltam no campo erros. Limite de upload: 10 MB. Arquivos com extensão diferente de .txt retornam 400 Bad Request; arquivos acima do limite, 413 Request Entity Too Large.

Request

Envio multipart/form-data com o campo arquivo (o .txt do Domínio). Sem corpo JSON.

Response 201 Created

{
  "success": true,
  "message": "Importação concluída com sucesso",
  "data": {
    "criadas": 120,
    "atualizadas": 15,
    "erros": [],
    "importacao_id": 88
  }
}

O registro no histórico de importações é best-effort: se a auditoria falhar, a importação das contas não é revertida e importacao_id volta como null.

Escopo: plano_contas:write

Schemas

`PlanoContasCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente (`customer.id`) ao qual o plano pertence.
`codigo_dominio`	`str`	sim	Código do plano no Domínio (único por cliente). 1-50 caracteres.
`nome`	`str`	sim	Nome/descrição do plano de contas. 1-300 caracteres.
`status`	`"ativo"` \| `"inativo"`	não	Status do plano. Default `"ativo"`.

`PlanoContasUpdate`

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

Campo	Tipo	Observações
`codigo_dominio`	`str`	Código do plano no Domínio (único por cliente). 1-50 caracteres.
`nome`	`str`	Nome/descrição do plano de contas. 1-300 caracteres.
`status`	`"ativo"` \| `"inativo"`	Novo status do plano.

`PlanoContasRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do plano.
`id_usuario_created`	`int`	Usuário que criou o plano.
`id_cliente`	`int`	Cliente ao qual o plano pertence.
`data_hora_criacao`	`datetime`	Data/hora de criação, no fuso `America/Sao_Paulo`.
`codigo_dominio`	`str`	Código do plano no Domínio.
`nome`	`str`	Nome/descrição do plano.
`status`	`str`	Situação (`"ativo"` ou `"inativo"`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
status aceita somente os valores "ativo" e "inativo"; qualquer outro valor é rejeitado na validação.
GET /plano-contas/usuario/{usuario_id} e GET /plano-contas/cliente/{id_cliente} são declarados antes da rota dinâmica GET /plano-contas/{plano_id}, garantindo que usuario e cliente sejam resolvidos como rotas estáticas.
A importação de contas (POST /plano-contas/{id_plano_contas}/importar-contas/) faz upsert por codigo_dominio e registra o evento no Histórico de Importações (campo importacao_id no retorno).