Resumo Impostos Calculados

Endpoints da WebApiAlcance para o resumo consolidado de impostos calculados por cliente e competência (mês/ano). Cada registro agrega os tributos apurados no período - pis, cofins, irpj, csll, iss - e o total_geral. Os endpoints cobrem criação manual, importação automática a partir de um PDF contábil, listagem geral, listagem por cliente, detalhamento por ID, atualização parcial 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/resumo-impostos-calculados

Escopos necessários

resumo_impostos_calculados:read - listagem geral, listagem por cliente e detalhamento por ID
resumo_impostos_calculados:write - criação, importação por PDF, atualização e exclusão

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

Endpoints

`POST /resumo-impostos-calculados/`

Cria um novo resumo de impostos calculados. O usuário responsável (id_user_created) é derivado do usuário autenticado - não é aceito no payload (proteção contra mass-assignment).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (ResumoImpostosCalculadosCreate): id_cliente (obrigatório), competencia (obrigatório, formato MM/YYYY) e os tributos pis, cofins, irpj, csll, iss, total_geral (opcionais, default 0.00).

Request

{
  "id_cliente": 1,
  "competencia": "06/2026",
  "pis": 1500.00,
  "cofins": 3450.00,
  "irpj": 2000.00,
  "csll": 1800.00,
  "iss": 500.00,
  "total_geral": 9250.00
}

Response 201 Created

{
  "success": true,
  "message": "Resumo de impostos calculados criado com sucesso",
  "data": {
    "id": 340,
    "id_cliente": 1,
    "id_user_created": 12,
    "competencia": "06/2026",
    "pis": 1500.00,
    "cofins": 3450.00,
    "irpj": 2000.00,
    "csll": 1800.00,
    "iss": 500.00,
    "total_geral": 9250.00,
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": null
  }
}

Escopo: resumo_impostos_calculados:write

`POST /resumo-impostos-calculados/importar-impostos`

Cria um resumo de impostos a partir de um PDF contábil. O arquivo é enviado como multipart/form-data no campo arquivo; o CNPJ, a competência e os valores dos tributos são extraídos automaticamente do documento e o cliente é resolvido pelo CNPJ.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`arquivo`	`UploadFile`	form	sim	PDF do resumo de impostos calculados a ser importado.

Request

POST /api/v1/resumo-impostos-calculados/importar-impostos
Content-Type: multipart/form-data
 
arquivo=@resumo_impostos_06-2026.pdf

Response 201 Created

{
  "success": true,
  "message": "Resumo de impostos calculados criado a partir do PDF com sucesso",
  "data": {
    "id": 341,
    "id_cliente": 1,
    "id_user_created": 12,
    "competencia": "06/2026",
    "pis": 1500.00,
    "cofins": 3450.00,
    "irpj": 2000.00,
    "csll": 1800.00,
    "iss": 500.00,
    "total_geral": 9250.00,
    "data_hora_criacao": "2026-07-03T09:20:10",
    "data_hora_edicao": null
  }
}

Erros de entrada retornam status HTTP dedicados: 400 Bad Request para PDF inválido ou CNPJ/competência não extraídos, e 404 Not Found quando o cliente não é encontrado pelo CNPJ (detail iniciando com "Cliente nao encontrado"). Escopo: resumo_impostos_calculados:write

`GET /resumo-impostos-calculados/`

Lista todos os resumos de impostos calculados cadastrados. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhum resumo de impostos calculados encontrado.".

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. A resposta traz data como array de ResumoImpostosCalculadosRead.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Resumos de impostos calculados recuperados com sucesso",
  "data": [
    {
      "id": 340,
      "id_cliente": 1,
      "id_user_created": 12,
      "competencia": "06/2026",
      "pis": 1500.00,
      "cofins": 3450.00,
      "irpj": 2000.00,
      "csll": 1800.00,
      "iss": 500.00,
      "total_geral": 9250.00,
      "data_hora_criacao": "2026-07-03T09:12:44",
      "data_hora_edicao": null
    }
  ]
}

Escopo: resumo_impostos_calculados:read

`GET /resumo-impostos-calculados/by-cliente/{id_cliente}`

Lista os resumos de impostos de um cliente específico. Sem registros, retorna 200 OK com data: [] e a mensagem "Nenhum resumo encontrado para este cliente.".

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": "Resumos do cliente recuperados com sucesso",
  "data": [
    {
      "id": 340,
      "id_cliente": 1,
      "id_user_created": 12,
      "competencia": "06/2026",
      "pis": 1500.00,
      "cofins": 3450.00,
      "irpj": 2000.00,
      "csll": 1800.00,
      "iss": 500.00,
      "total_geral": 9250.00,
      "data_hora_criacao": "2026-07-03T09:12:44",
      "data_hora_edicao": null
    }
  ]
}

Escopo: resumo_impostos_calculados:read

`GET /resumo-impostos-calculados/{resumo_id}`

Detalha um resumo pelo ID inteiro. Quando não encontrado, retorna o envelope de erro com message: "Resumo de impostos calculados nao encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`resumo_id`	`int`	path	sim	ID interno do resumo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Resumo de impostos calculados encontrado com sucesso",
  "data": {
    "id": 340,
    "id_cliente": 1,
    "id_user_created": 12,
    "competencia": "06/2026",
    "pis": 1500.00,
    "cofins": 3450.00,
    "irpj": 2000.00,
    "csll": 1800.00,
    "iss": 500.00,
    "total_geral": 9250.00,
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": null
  }
}

Escopo: resumo_impostos_calculados:read

`PUT /resumo-impostos-calculados/{resumo_id}`

Atualiza um resumo existente. O body é um ResumoImpostosCalculadosUpdate com campos parciais - somente o que vier preenchido é alterado. id_cliente e id_user_created são imutáveis após a criação.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`resumo_id`	`int`	path	sim	ID do resumo.

Request (ResumoImpostosCalculadosUpdate - todos os campos opcionais)

{
  "competencia": "06/2026",
  "iss": 620.00,
  "total_geral": 9370.00
}

Response 200 OK

{
  "success": true,
  "message": "Resumo de impostos calculados atualizado com sucesso",
  "data": {
    "id": 340,
    "id_cliente": 1,
    "id_user_created": 12,
    "competencia": "06/2026",
    "pis": 1500.00,
    "cofins": 3450.00,
    "irpj": 2000.00,
    "csll": 1800.00,
    "iss": 620.00,
    "total_geral": 9370.00,
    "data_hora_criacao": "2026-07-03T09:12:44",
    "data_hora_edicao": "2026-07-03T11:42:00"
  }
}

Escopo: resumo_impostos_calculados:write

`DELETE /resumo-impostos-calculados/{resumo_id}`

Remove um resumo de impostos calculados pelo ID. Quando não encontrado, retorna o envelope de erro com message: "Resumo de impostos calculados nao encontrado.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`resumo_id`	`int`	path	sim	ID do resumo.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Resumo de impostos calculados deletado com sucesso",
  "data": null
}

Escopo: resumo_impostos_calculados:write

Schemas

`ResumoImpostosCalculadosCreate`

Campo	Tipo	Obrigatório	Observações
`id_cliente`	`int`	sim	ID do cliente. Deve ser `> 0`.
`competencia`	`str`	sim	Competência no formato `MM/YYYY` (ex.: `06/2026`). Máx. 7 caracteres.
`pis`	`decimal`	não	Valor do PIS. Default `0.00`; deve ser `>= 0`.
`cofins`	`decimal`	não	Valor da COFINS. Default `0.00`; deve ser `>= 0`.
`irpj`	`decimal`	não	Valor do IRPJ. Default `0.00`; deve ser `>= 0`.
`csll`	`decimal`	não	Valor da CSLL. Default `0.00`; deve ser `>= 0`.
`iss`	`decimal`	não	Valor do ISS. Default `0.00`; deve ser `>= 0`.
`total_geral`	`decimal`	não	Total geral dos tributos. Default `0.00`; deve ser `>= 0`.

`ResumoImpostosCalculadosUpdate`

Atualização parcial; apenas os campos enviados são alterados. id_cliente e id_user_created são imutáveis pós-criação.

Campo	Tipo	Observações
`competencia`	`str`	Nova competência no formato `MM/YYYY`.
`pis`	`decimal`	Novo valor do PIS. Deve ser `>= 0`.
`cofins`	`decimal`	Novo valor da COFINS. Deve ser `>= 0`.
`irpj`	`decimal`	Novo valor do IRPJ. Deve ser `>= 0`.
`csll`	`decimal`	Novo valor da CSLL. Deve ser `>= 0`.
`iss`	`decimal`	Novo valor do ISS. Deve ser `>= 0`.
`total_geral`	`decimal`	Novo total geral. Deve ser `>= 0`.

`ResumoImpostosCalculadosRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do resumo.
`id_cliente`	`int`	Cliente vinculado.
`id_user_created`	`int`	Usuário Alcance que registrou o resumo.
`competencia`	`str`	Competência no formato `MM/YYYY`.
`pis`	`decimal`	Valor do PIS.
`cofins`	`decimal`	Valor da COFINS.
`irpj`	`decimal`	Valor do IRPJ.
`csll`	`decimal`	Valor da CSLL.
`iss`	`decimal`	Valor do ISS.
`total_geral`	`decimal`	Total geral dos tributos.
`data_hora_criacao`	`datetime?`	Quando o registro foi criado.
`data_hora_edicao`	`datetime?`	Quando o registro foi editado pela última vez.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
competencia é validada pelo padrão MM/YYYY (mês de 01 a 12); valores fora do formato retornam erro de validação (422 Unprocessable Entity).
Os campos de tributos são valores monetários (decimal) e nunca podem ser negativos (>= 0).
GET /resumo-impostos-calculados/by-cliente/{id_cliente} é declarado antes da rota dinâmica GET /resumo-impostos-calculados/{resumo_id}, então by-cliente é resolvido como rota estática (e não interpretado como um resumo_id).
O endpoint POST /importar-impostos extrai automaticamente CNPJ, competência e valores do PDF contábil e resolve o cliente pelo CNPJ - dispensando a digitação manual dos tributos.