Relatório ISS Data

Endpoints da WebApiAlcance para o Relatório ISS Data - registros consolidados de NFS-e e do ISS (Imposto Sobre Serviços) apurados por prestador. Cada registro guarda dados fiscais da nota (número da NFS-e, RPS, prestador/tomador, valores de serviço e tributos como ISS, PIS, COFINS, INSS, IRPJ e CSLL). Os endpoints cobrem criação, busca por período de emissão, busca por número de NFS-e, detalhamento por ID, listagem geral, 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/relatorio-iss-data

Escopos necessários

relatorio_iss_data:read - busca por período, por número de NFS-e, detalhamento por ID e listagem
relatorio_iss_data:write - criação, atualização e exclusão

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

Endpoints

`POST /relatorio-iss-data/`

Cria um novo registro de relatório do ISS. Valores decimais aceitam formato brasileiro (ex.: "1.234,56"), normalizado automaticamente para Decimal.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (RelatorioIssDataCreate); ver Schema RelatorioIssData. Todos os campos são opcionais.

Request

{
  "cliente_id": 487,
  "numero_nfse": 9001,
  "cpfecnpj_prestador": "12.345.678/0001-99",
  "razao_social_prestador": "Empresa Prestadora LTDA",
  "valor_servico": "1.234,56",
  "aliquota": "5,00",
  "iss_devido": "61,73",
  "iss_retido": "N"
}

Response 201 Created

{
  "success": true,
  "message": "Registro criada com sucesso",
  "data": {
    "id": 3120,
    "cliente_id": 487,
    "numero_nfse": 9001,
    "cpfecnpj_prestador": "12.345.678/0001-99",
    "razao_social_prestador": "Empresa Prestadora LTDA",
    "valor_servico": "1234.56",
    "aliquota": "5.00",
    "iss_devido": "61.73",
    "iss_retido": "N"
  }
}

Escopo: relatorio_iss_data:write

`GET /relatorio-iss-data/periodo/`

Busca registros por período de emissão. O filtro usa a data efetiva COALESCE(data_emissao_rps, data_hora_nfe) - ou seja, a data de emissão do RPS com fallback para a data/hora da NFS-e. Se start_date for posterior a end_date, retorna 422 Unprocessable Entity com detail: "Intervalo de datas inválido: start_date posterior a end_date.".

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`start_date`	`datetime`	query	sim	Data inicial (inclusive). Aceita `YYYY-MM-DD` ou ISO 8601.
`end_date`	`datetime`	query	sim	Data final (inclusive). Quando enviado sem hora, cobre o dia inteiro até 23:59:59.
`cnpj`	`str`	query	não	CNPJ/CPF do prestador. Aceita formatado (`12.345.678/0001-99`) ou apenas dígitos.

Exemplo: GET /relatorio-iss-data/periodo/?start_date=2026-01-01&end_date=2026-01-31&cnpj=12345678000199.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registros encontrados com sucesso",
  "data": [
    {
      "id": 3120,
      "cliente_id": 487,
      "numero_nfse": 9001,
      "cpfecnpj_prestador": "12.345.678/0001-99",
      "razao_social_prestador": "Empresa Prestadora LTDA",
      "valor_servico": "1234.56",
      "aliquota": "5.00",
      "iss_devido": "61.73",
      "iss_retido": "N"
    }
  ]
}

Quando não há registros no período, retorna 200 OK com data: [] e a mensagem "Nenhum registro encontrado no período especificado.". Escopo: relatorio_iss_data:read

`GET /relatorio-iss-data/numero_nfse/{numero_nfse}`

Busca um registro pelo número da NFS-e.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`numero_nfse`	`int`	path	sim	Número da NFS-e (coluna inteira).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrada com sucesso",
  "data": {
    "id": 3120,
    "cliente_id": 487,
    "numero_nfse": 9001,
    "cpfecnpj_prestador": "12.345.678/0001-99",
    "razao_social_prestador": "Empresa Prestadora LTDA",
    "valor_servico": "1234.56",
    "aliquota": "5.00",
    "iss_devido": "61.73",
    "iss_retido": "N"
  }
}

Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrada.". Escopo: relatorio_iss_data:read

`GET /relatorio-iss-data/{entity_id}`

Detalha um registro pelo ID interno.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro encontrada com sucesso",
  "data": {
    "id": 3120,
    "cliente_id": 487,
    "numero_nfse": 9001,
    "cpfecnpj_prestador": "12.345.678/0001-99",
    "razao_social_prestador": "Empresa Prestadora LTDA",
    "valor_servico": "1234.56",
    "aliquota": "5.00",
    "iss_devido": "61.73",
    "iss_retido": "N"
  }
}

Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrada.". Escopo: relatorio_iss_data:read

`GET /relatorio-iss-data/`

Lista todos os registros cadastrados.

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": "Lista de atividades recuperada com sucesso",
  "data": [
    {
      "id": 3120,
      "cliente_id": 487,
      "numero_nfse": 9001,
      "cpfecnpj_prestador": "12.345.678/0001-99",
      "razao_social_prestador": "Empresa Prestadora LTDA",
      "valor_servico": "1234.56",
      "aliquota": "5.00",
      "iss_devido": "61.73",
      "iss_retido": "N"
    }
  ]
}

Quando não há registros, retorna 200 OK com data: [] e a mensagem "Nenhuma atividade encontrada.". Escopo: relatorio_iss_data:read

`PUT /relatorio-iss-data/{entity_id}`

Atualiza um registro existente. O body é um RelatorioIssDataUpdate com campos parciais - todos opcionais; apenas o que vier preenchido é alterado.

Parâmetros

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

Request (RelatorioIssDataUpdate - todos os campos opcionais; ver Schema RelatorioIssData)

{
  "aliquota": "3,50",
  "iss_devido": "43,21",
  "observacao": "Alíquota revisada conforme legislação municipal."
}

Response 200 OK

{
  "success": true,
  "message": "Registro atualizada com sucesso",
  "data": {
    "id": 3120,
    "cliente_id": 487,
    "numero_nfse": 9001,
    "cpfecnpj_prestador": "12.345.678/0001-99",
    "razao_social_prestador": "Empresa Prestadora LTDA",
    "valor_servico": "1234.56",
    "aliquota": "3.50",
    "iss_devido": "43.21",
    "iss_retido": "N",
    "observacao": "Alíquota revisada conforme legislação municipal."
  }
}

Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrada.". Escopo: relatorio_iss_data:write

`DELETE /relatorio-iss-data/{entity_id}`

Remove um registro pelo ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Registro deletada com sucesso",
  "data": null
}

Quando não encontrado, retorna o envelope de erro com message: "Registro não encontrada.". Escopo: relatorio_iss_data:write

Schemas

`RelatorioIssData`

Campos comuns aos schemas RelatorioIssDataCreate, RelatorioIssDataUpdate e RelatorioIssDataRead. Todos são opcionais. Os valores monetários e a alíquota aceitam formato brasileiro em string (ex.: "1.234,56"), normalizado para Decimal na entrada.

Campo	Tipo	Observações
`cliente_id`	`int?`	ID do cliente vinculado.
`atividade_id`	`int?`	ID da atividade relacionada.
`data_hora_registro`	`datetime?`	Data/hora do registro no sistema.
`tipo`	`str?`	Tipo do registro.
`numero_nfse`	`int?`	Número da NFS-e.
`data_hora_nfe`	`datetime?`	Data/hora da NFS-e.
`codigo_verificacao`	`str?`	Código de verificação da NFS-e.
`serie_rps`	`str?`	Série do RPS.
`numero_rps`	`str?`	Número do RPS.
`data_emissao_rps`	`datetime?`	Data de emissão do RPS.
`cpfecnpj_prestador`	`str?`	CPF/CNPJ do prestador.
`razao_social_prestador`	`str?`	Razão social do prestador.
`valor_servico`	`Decimal?`	Valor do serviço.
`codigo_servico_prestado`	`int?`	Código do serviço prestado.
`aliquota`	`Decimal?`	Alíquota do ISS.
`iss_devido`	`Decimal?`	Valor de ISS devido.
`iss_retido`	`str?`	Indicador de ISS retido.
`pis`	`Decimal?`	Valor de PIS.
`cofins`	`Decimal?`	Valor de COFINS.
`inss`	`Decimal?`	Valor de INSS.
`irpj`	`Decimal?`	Valor de IRPJ.
`csll`	`Decimal?`	Valor de CSLL.
`cpfecnpj_tomador`	`str?`	CPF/CNPJ do tomador.
`razao_social_tomador`	`str?`	Razão social do tomador.
`discriminacao_servico`	`str?`	Discriminação do serviço.
`observacao`	`str?`	Observação livre.

O schema de leitura RelatorioIssDataRead estende os campos acima com o id (int) do registro.

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
As rotas estáticas GET /periodo/ e GET /numero_nfse/{numero_nfse} são declaradas antes da rota dinâmica GET /{entity_id}, para que periodo e numero_nfse não sejam interpretados como um entity_id inteiro (o que causaria 422).
Os campos decimais (valor_servico, aliquota, iss_devido, pis, cofins, inss, irpj, csll) aceitam o formato brasileiro em string - pontos de milhar são removidos e a vírgula decimal vira ponto antes da conversão para Decimal.
A busca por período usa a data efetiva COALESCE(data_emissao_rps, data_hora_nfe).