Apuração de Resultado

Endpoints da WebApiAlcance para gerenciar apurações de resultado - o cálculo do resultado (lucro/prejuízo) do período e do tributo devido por cliente (PIS, COFINS, ISS, IRPJ, CSLL). Cada apuração registra base de cálculo, alíquota aplicada, valor apurado, retenções e valor a recolher para um período (mensal, trimestral ou anual). Cobrem criação, fechamento (transição aberto → fechado), listagem por usuário autenticado, listagem por cliente, 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/apuracao-resultado

Escopos necessários

apuracao_resultado:read - listagem por usuário, listagem por cliente e detalhamento
apuracao_resultado:write - criação, fechamento, atualização e exclusão

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

Endpoints

`POST /apuracao-resultado/`

Cria uma nova apuração de resultado vinculada ao usuário autenticado. O id_usuario_created vem do usuário logado e o campo status não é aceito no corpo - toda apuração nasce "aberto".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ApuracaoResultadoCreate): id_customer, tributo, periodo, tipo_periodo, base_calculo, aliquota_aplicada, valor_apurado e valor_a_recolher obrigatórios; regime_apuracao, valor_retido, houve_majoracao, detalhes e status_conferencia opcionais.

Request

{
  "id_customer": 1,
  "tributo": "IRPJ",
  "periodo": "2026-Q2",
  "tipo_periodo": "trimestral",
  "regime_apuracao": "presumido",
  "base_calculo": "100000.00",
  "aliquota_aplicada": "1.6500",
  "valor_apurado": "1650.00",
  "valor_retido": "0",
  "valor_a_recolher": "1650.00",
  "houve_majoracao": false
}

Response 201 Created

{
  "success": true,
  "message": "Apuração criada com sucesso!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "tributo": "IRPJ",
    "periodo": "2026-Q2",
    "tipo_periodo": "trimestral",
    "regime_apuracao": "presumido",
    "base_calculo": "100000.00",
    "aliquota_aplicada": "1.6500",
    "valor_apurado": "1650.00",
    "valor_retido": "0",
    "valor_a_recolher": "1650.00",
    "houve_majoracao": false,
    "detalhes": null,
    "status_conferencia": null,
    "status": "aberto",
    "data_fechamento": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-08T09:15:00-03:00",
    "updated_at": "2026-07-08T09:15:00-03:00"
  }
}

Cliente inexistente retorna 404 Not Found; combinação (cliente, tributo, período, tipo_periodo) já existente retorna 409 Conflict; validações de campo retornam 422 Unprocessable Entity. Escopo: apuracao_resultado:write

`POST /apuracao-resultado/fechar/{apuracao_id}`

Fecha a apuração, setando status='fechado' e preenchendo data_fechamento. É a única porta para transitar status de "aberto" para "fechado". Após fechada, a apuração fica imutável: PUT e DELETE passam a devolver 422, e fechar novamente também retorna 422.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Apuração fechada com sucesso!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "tributo": "IRPJ",
    "periodo": "2026-Q2",
    "tipo_periodo": "trimestral",
    "regime_apuracao": "presumido",
    "base_calculo": "100000.00",
    "aliquota_aplicada": "1.6500",
    "valor_apurado": "1650.00",
    "valor_retido": "0",
    "valor_a_recolher": "1650.00",
    "houve_majoracao": false,
    "detalhes": null,
    "status_conferencia": null,
    "status": "fechado",
    "data_fechamento": "2026-07-08T14:30:00-03:00",
    "id_usuario_created": 42,
    "created_at": "2026-07-08T09:15:00-03:00",
    "updated_at": "2026-07-08T14:30:00-03:00"
  }
}

Escopo: apuracao_resultado:write

`GET /apuracao-resultado/by-user`

Lista todas as apurações do usuário autenticado, com filtros opcionais e paginação. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma apuração encontrada.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`periodo`	`str`	query	não	Filtro por período exato (formato depende de `tipo_periodo`)
`tipo_periodo`	`str`	query	não	Filtro por tipo de período: `mensal`, `trimestral`, `anual`
`status`	`str`	query	não	Filtro por status: `aberto`, `fechado`
`page`	`int >= 1`	query	não	Página (1-based)
`per_page`	`int 1..500`	query	não	Itens por página

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Apurações recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "tributo": "IRPJ",
      "periodo": "2026-Q2",
      "tipo_periodo": "trimestral",
      "regime_apuracao": "presumido",
      "base_calculo": "100000.00",
      "aliquota_aplicada": "1.6500",
      "valor_apurado": "1650.00",
      "valor_retido": "0",
      "valor_a_recolher": "1650.00",
      "houve_majoracao": false,
      "detalhes": null,
      "status_conferencia": null,
      "status": "aberto",
      "data_fechamento": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-08T09:15:00-03:00",
      "updated_at": "2026-07-08T09:15:00-03:00"
    }
  ]
}

Escopo: apuracao_resultado:read

`GET /apuracao-resultado/by-customer/{customer_id}`

Lista as apurações de um cliente, opcionalmente filtradas por tributo, período, tipo de período e status, com paginação. É o caso de uso primário do front. Quando o cliente não é acessível, o service devolve erro mapeado (403/404).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`customer_id`	`int`	path	sim	ID interno do cliente
`tributo`	`str`	query	não	Filtro por tributo: `PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`
`periodo`	`str`	query	não	Filtro por período exato
`tipo_periodo`	`str`	query	não	Filtro por tipo de período: `mensal`, `trimestral`, `anual`
`status`	`str`	query	não	Filtro por status: `aberto`, `fechado`
`page`	`int >= 1`	query	não	Página (1-based)
`per_page`	`int 1..500`	query	não	Itens por página

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Apurações recuperadas com sucesso!",
  "data": [
    {
      "id": 1,
      "id_customer": 1,
      "tributo": "IRPJ",
      "periodo": "2026-Q2",
      "tipo_periodo": "trimestral",
      "regime_apuracao": "presumido",
      "base_calculo": "100000.00",
      "aliquota_aplicada": "1.6500",
      "valor_apurado": "1650.00",
      "valor_retido": "0",
      "valor_a_recolher": "1650.00",
      "houve_majoracao": false,
      "detalhes": null,
      "status_conferencia": null,
      "status": "aberto",
      "data_fechamento": null,
      "id_usuario_created": 42,
      "created_at": "2026-07-08T09:15:00-03:00",
      "updated_at": "2026-07-08T09:15:00-03:00"
    }
  ]
}

Escopo: apuracao_resultado:read

`GET /apuracao-resultado/{apuracao_id}`

Detalha uma apuração pelo ID inteiro. Quando não encontrada, retorna 404 Not Found.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Apuração encontrada!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "tributo": "IRPJ",
    "periodo": "2026-Q2",
    "tipo_periodo": "trimestral",
    "regime_apuracao": "presumido",
    "base_calculo": "100000.00",
    "aliquota_aplicada": "1.6500",
    "valor_apurado": "1650.00",
    "valor_retido": "0",
    "valor_a_recolher": "1650.00",
    "houve_majoracao": false,
    "detalhes": null,
    "status_conferencia": null,
    "status": "aberto",
    "data_fechamento": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-08T09:15:00-03:00",
    "updated_at": "2026-07-08T09:15:00-03:00"
  }
}

Escopo: apuracao_resultado:read

`PUT /apuracao-resultado/{apuracao_id}`

Atualiza uma apuração existente. O body é um ApuracaoResultadoUpdate com campos parciais - somente o que vier preenchido é alterado. Só é permitido quando status='aberto'; apurações fechadas devolvem 422. Campos como id_customer, id, status, data_fechamento e timestamps são imutáveis e não são aceitos.

Parâmetros

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

Request (ApuracaoResultadoUpdate - todos os campos opcionais)

{
  "valor_retido": "150.00",
  "valor_a_recolher": "1500.00",
  "status_conferencia": "em_andamento"
}

Response 200 OK

{
  "success": true,
  "message": "Apuração atualizada!",
  "data": {
    "id": 1,
    "id_customer": 1,
    "tributo": "IRPJ",
    "periodo": "2026-Q2",
    "tipo_periodo": "trimestral",
    "regime_apuracao": "presumido",
    "base_calculo": "100000.00",
    "aliquota_aplicada": "1.6500",
    "valor_apurado": "1650.00",
    "valor_retido": "150.00",
    "valor_a_recolher": "1500.00",
    "houve_majoracao": false,
    "detalhes": null,
    "status_conferencia": "em_andamento",
    "status": "aberto",
    "data_fechamento": null,
    "id_usuario_created": 42,
    "created_at": "2026-07-08T09:15:00-03:00",
    "updated_at": "2026-07-08T11:42:00-03:00"
  }
}

Escopo: apuracao_resultado:write

`DELETE /apuracao-resultado/{apuracao_id}`

Remove uma apuração pelo ID. Só é permitido quando status='aberto'; apurações fechadas devolvem 422.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Apuração removida!",
  "data": null
}

Escopo: apuracao_resultado:write

Schemas

`ApuracaoResultadoCreate`

Herda todos os campos de ApuracaoResultadoBase. status não é exposto - toda apuração nasce "aberto".

Campo	Tipo	Obrigatório	Observações
`id_customer`	`int`	sim	ID do cliente (`customer.id`) ao qual a apuração pertence.
`tributo`	`str` (enum)	sim	Tributo apurado. Valores: `PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`.
`periodo`	`str`	sim	Período de apuração. Formato depende de `tipo_periodo` (ver notas). 4 a 10 caracteres.
`tipo_periodo`	`str` (enum)	sim	Granularidade: `mensal`, `trimestral` ou `anual`.
`regime_apuracao`	`str` (enum)	não	Regime aplicado: `presumido`, `real` ou `simples`. Default `null`.
`base_calculo`	`Decimal`	sim	Base de cálculo (R$) sobre a qual o tributo incide. `>= 0` e `< 10.000.000.000.000`.
`aliquota_aplicada`	`Decimal`	sim	Alíquota efetiva aplicada (em %, ex.: `1.6500` = 1,65%). `>= 0` e `< 1000`.
`valor_apurado`	`Decimal`	sim	Valor apurado (R$) = `base_calculo × aliquota_aplicada / 100`. `>= 0`.
`valor_retido`	`Decimal`	não	Retenções na fonte (R$). Default `0`. `>= 0`.
`valor_a_recolher`	`Decimal`	sim	Valor líquido a recolher (R$) = `valor_apurado − valor_retido`. `>= 0`.
`houve_majoracao`	`bool`	não	`true` quando a majoração 2026 foi aplicada na `aliquota_aplicada`. Default `false`.
`detalhes`	`dict` (JSON)	não	Breakdown completo da apuração (NFS-e usadas, lançamentos manuais, fórmulas). Útil para auditoria.
`status_conferencia`	`str` (enum)	não	Status da conferência (revisão humana): `pendente`, `em_andamento`, `finalizado`. Default `null`.

`ApuracaoResultadoUpdate`

Todos os campos são opcionais; apenas os enviados são atualizados (exclude_unset). id_customer, id, status, data_fechamento, created_at e updated_at são imutáveis e não aparecem aqui.

Campo	Tipo	Observações
`tributo`	`str` (enum)	`PIS`, `COFINS`, `ISS`, `IRPJ`, `CSLL`.
`periodo`	`str`	4 a 10 caracteres. Consistência com `tipo_periodo` validada quando ambos enviados.
`tipo_periodo`	`str` (enum)	`mensal`, `trimestral`, `anual`.
`regime_apuracao`	`str` (enum)	`presumido`, `real`, `simples`.
`base_calculo`	`Decimal`	`>= 0` e `< 10.000.000.000.000`.
`aliquota_aplicada`	`Decimal`	`>= 0` e `< 1000`.
`valor_apurado`	`Decimal`	`>= 0`.
`valor_retido`	`Decimal`	`>= 0`.
`valor_a_recolher`	`Decimal`	`>= 0`.
`houve_majoracao`	`bool`	Marca aplicação da majoração 2026.
`detalhes`	`dict` (JSON)	Breakdown da apuração.
`status_conferencia`	`str` (enum)	`pendente`, `em_andamento`, `finalizado`. Combinável com qualquer outro campo.

`ApuracaoResultadoRead`

Estende ApuracaoResultadoBase com os campos gerenciados pelo servidor.

Campo	Tipo	Notas
`id`	`int`	Identificador da apuração.
`id_customer`	`int`	Cliente ao qual a apuração pertence.
`tributo`	`str`	Tributo apurado.
`periodo`	`str`	Período de apuração.
`tipo_periodo`	`str`	Granularidade do período.
`regime_apuracao`	`str \| null`	Regime aplicado.
`base_calculo`	`Decimal`	Base de cálculo (R$).
`aliquota_aplicada`	`Decimal`	Alíquota efetiva (%).
`valor_apurado`	`Decimal`	Valor apurado (R$).
`valor_retido`	`Decimal`	Retenções na fonte (R$).
`valor_a_recolher`	`Decimal`	Valor líquido a recolher (R$).
`houve_majoracao`	`bool`	Indica aplicação da majoração 2026.
`detalhes`	`dict \| null`	Breakdown da apuração (JSON).
`status_conferencia`	`str \| null`	Status da conferência humana.
`status`	`str`	Ciclo de vida: `aberto` ou `fechado`.
`data_fechamento`	`datetime \| null`	Timestamp do fechamento (`null` quando `aberto`).
`id_usuario_created`	`int`	Usuário que criou a apuração (multi-tenant).
`created_at`	`datetime`	Timestamp de criação (server-side).
`updated_at`	`datetime`	Timestamp da última atualização (server-side).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Formato de periodo × tipo_periodo (validado no schema):
- mensal: YYYY-MM (ex.: 2026-05)
- trimestral: YYYY-Qn com n = 1..4 (ex.: 2026-Q2)
- anual: YYYY (ex.: 2026)
As rotas estáticas POST /fechar/{apuracao_id}, GET /by-user e GET /by-customer/{customer_id} são declaradas antes da rota dinâmica GET /{apuracao_id}, para que o FastAPI as resolva corretamente (e não interprete fechar/by-user/by-customer como um apuracao_id).
Imutabilidade após fechamento: POST /fechar/{apuracao_id} é a única transição para status='fechado'. Depois disso, PUT e DELETE retornam 422.
Valores monetários são Decimal (Numeric(15,2) no banco); aliquota_aplicada é Numeric(7,4).