Situação Fiscal - Detalhamento

Endpoints da WebApiAlcance para o detalhamento item-a-item da situação fiscal de um cliente. Enquanto a Situação Fiscal representa a consulta consolidada, este domínio registra cada item de diagnóstico vinculado a ela - o resultado da Receita Federal e da Procuradoria-Geral (PGFN), com status e observação. Os endpoints cobrem registro, consulta por ID, listagem geral, atualização, exclusão por ID e exclusão pelo vínculo com a situação fiscal de origem.

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/situacao-fiscal-detalhamento

Escopos necessários

situacao_fiscal_detalhamento:read - consulta por ID e listagem geral
situacao_fiscal_detalhamento:write - registro, atualização e exclusões

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

Endpoints

`POST /situacao-fiscal-detalhamento/`

Registra um novo item de detalhamento da situação fiscal, vinculado a uma situação fiscal existente via id_situacao_fiscal.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SituacaoFiscalDetalhamentoCreate): id_situacao_fiscal, diagnostico_receita_federal, diagnostico_procuradoria_geral e status são obrigatórios; observacao é opcional.

Request

{
  "id_situacao_fiscal": 4821,
  "diagnostico_receita_federal": "Sem pendências",
  "diagnostico_procuradoria_geral": "Sem débitos inscritos em Dívida Ativa",
  "status": "Concluido",
  "observacao": "Diagnóstico automático via rotina diária"
}

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal registrada com sucesso!",
  "data": {
    "id": 173,
    "id_situacao_fiscal": 4821,
    "diagnostico_receita_federal": "Sem pendências",
    "diagnostico_procuradoria_geral": "Sem débitos inscritos em Dívida Ativa",
    "status": "Concluido",
    "observacao": "Diagnóstico automático via rotina diária"
  }
}

Escopo: situacao_fiscal_detalhamento:write

`GET /situacao-fiscal-detalhamento/{id}`

Busca um item de detalhamento pelo ID inteiro. Quando não encontrado, retorna 404 Not Found com detail: "Situação fiscal não encontrada.".

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal encontrada com sucesso!",
  "data": {
    "id": 173,
    "id_situacao_fiscal": 4821,
    "diagnostico_receita_federal": "Sem pendências",
    "diagnostico_procuradoria_geral": "Sem débitos inscritos em Dívida Ativa",
    "status": "Concluido",
    "observacao": null
  }
}

Escopo: situacao_fiscal_detalhamento:read

`GET /situacao-fiscal-detalhamento/`

Lista todos os itens de detalhamento registrados. Lista vazia é um estado válido - sempre retorna 200 OK, inclusive com data: [] e a mensagem "Nenhuma situação fiscal encontrada!".

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": "Situações fiscais recuperadas com sucesso!",
  "data": [
    {
      "id": 173,
      "id_situacao_fiscal": 4821,
      "diagnostico_receita_federal": "Sem pendências",
      "diagnostico_procuradoria_geral": "Sem débitos inscritos em Dívida Ativa",
      "status": "Concluido",
      "observacao": null
    }
  ]
}

Escopo: situacao_fiscal_detalhamento:read

`PUT /situacao-fiscal-detalhamento/{id}`

Atualiza um item de detalhamento existente. O body é um SituacaoFiscalDetalhamentoUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

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

Request (SituacaoFiscalDetalhamentoUpdate - todos os campos opcionais)

{
  "status": "Pendente",
  "diagnostico_procuradoria_geral": "Débito inscrito em Dívida Ativa",
  "observacao": "Reprocessado após indisponibilidade do portal"
}

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal atualizada com sucesso!",
  "data": {
    "id": 173,
    "id_situacao_fiscal": 4821,
    "diagnostico_receita_federal": "Sem pendências",
    "diagnostico_procuradoria_geral": "Débito inscrito em Dívida Ativa",
    "status": "Pendente",
    "observacao": "Reprocessado após indisponibilidade do portal"
  }
}

Escopo: situacao_fiscal_detalhamento:write

`DELETE /situacao-fiscal-detalhamento/{id}`

Remove um item de detalhamento pelo seu ID.

Parâmetros

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

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal deletada com sucesso!",
  "data": null
}

Escopo: situacao_fiscal_detalhamento:write

`DELETE /situacao-fiscal-detalhamento/situacao-fiscal/{id}`

Remove o detalhamento pelo ID da situação fiscal de origem (id_situacao_fiscal), e não pelo ID do próprio item. Útil para limpar o detalhamento associado a uma situação fiscal específica.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID da situação fiscal de origem (`id_situacao_fiscal`)

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal deletada com sucesso!",
  "data": null
}

Escopo: situacao_fiscal_detalhamento:write

Schemas

`SituacaoFiscalDetalhamentoCreate`

Campo	Tipo	Obrigatório	Observações
`id_situacao_fiscal`	`int`	sim	ID da situação fiscal de origem à qual o detalhamento pertence.
`diagnostico_receita_federal`	`str`	sim	Resultado do diagnóstico junto à Receita Federal.
`diagnostico_procuradoria_geral`	`str`	sim	Resultado do diagnóstico junto à Procuradoria-Geral (PGFN).
`status`	`str`	sim	Situação do detalhamento (ex.: `Concluido`, `Pendente`).
`observacao`	`str?`	não	Observação livre. Default `null`.

`SituacaoFiscalDetalhamentoUpdate`

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

Campo	Tipo	Observações
`diagnostico_receita_federal`	`str`	Novo diagnóstico da Receita Federal.
`diagnostico_procuradoria_geral`	`str`	Novo diagnóstico da Procuradoria-Geral (PGFN).
`status`	`str`	Nova situação do detalhamento.
`observacao`	`str`	Nova observação.

`SituacaoFiscalDetalhamentoRead`

Campo	Tipo	Notas
`id`	`int`	Identificador do detalhamento.
`id_situacao_fiscal`	`int`	Situação fiscal de origem vinculada.
`diagnostico_receita_federal`	`str`	Diagnóstico da Receita Federal.
`diagnostico_procuradoria_geral`	`str`	Diagnóstico da Procuradoria-Geral (PGFN).
`status`	`str`	Situação do detalhamento.
`observacao`	`str?`	Observação livre (pode ser `null`).

Notas

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Este domínio é o detalhamento item-a-item da Situação Fiscal: cada registro se vincula a uma situação fiscal de origem por id_situacao_fiscal.
Existem duas rotas de exclusão distintas: DELETE /{id} remove pelo ID do próprio item de detalhamento, enquanto DELETE /situacao-fiscal/{id} remove pelo id_situacao_fiscal (a situação fiscal de origem).