Situação Fiscal

Gestão do Relatório de Situação Fiscal (SITFIS) da Receita Federal para os clientes da Alcance Contabilidade. Os endpoints cobrem o registro de emissões, consulta, atualização, exclusão, emissão via SERPRO (individual ou em lote a partir da lista interna de clientes), analytics consolidados, monitoramento por categoria de pendência e download do PDF gerado.

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

Todos os endpoints exigem header Authorization: Bearer <API_KEY> e a API Key emitida pela WebApiAlcance precisa carregar os escopos abaixo.

Escopos necessários

Escopo	Endpoints cobertos
`situacao_fiscal:read`	`GET /`, `GET /{id}`, `GET /{id}/pdf`, `GET /stats`, `GET /monitoring`, `GET /monitoring/list`
`situacao_fiscal:write`	`POST /`, `PUT /{id}`, `DELETE /{id}`, `POST /emitir`

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

Endpoints

`POST /situacao-fiscal/`

Registra uma nova emissão de situação fiscal. O body é um SituacaoFiscalCreate - ver Schema SituacaoFiscalCreate. Aceita pdf_base64 opcional no payload (necessário se você quiser baixar o PDF depois via /{id}/pdf).

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SituacaoFiscalCreate): id_usuario e id_cliente (obrigatórios), protocolo e status (obrigatórios), além de data_hora_emissao, pdf_base64 e observacao (opcionais).

Request

{
  "id_usuario": 12,
  "id_cliente": 487,
  "data_hora_emissao": "2026-05-15T08:14:22",
  "protocolo": "SITFIS-2026-000123",
  "status": "Concluido",
  "pdf_base64": "JVBERi0xLjcKJeLjz9MK...",
  "observacao": "Emissão automática via rotina diária"
}

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal registrada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "protocolo": "SITFIS-2026-000123",
    "status": "Concluido"
  }
}

Escopo: situacao_fiscal:write

`GET /situacao-fiscal/`

Lista todas as situações fiscais registradas. 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. O data retornado é um array de SituacaoFiscalRead (o campo pdf_base64 é excluído na listagem).

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Situações fiscais recuperadas com sucesso!",
  "data": [
    {
      "id": 9821,
      "id_usuario": 12,
      "id_cliente": 487,
      "data_hora_emissao": "2026-05-15T08:14:22",
      "protocolo": "SITFIS-2026-000123",
      "status": "Concluido",
      "observacao": null
    }
  ]
}

Escopo: situacao_fiscal:read

`PUT /situacao-fiscal/{id}`

Atualiza campos mutáveis de uma situação fiscal. O body é um SituacaoFiscalUpdate com campos parciais - somente o que vier preenchido é alterado.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID interno da situação fiscal

Request (SituacaoFiscalUpdate - todos os campos opcionais)

{
  "status": "Pendente",
  "observacao": "Reprocessado após revisão"
}

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal atualizada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_hora_emissao": "2026-05-15T08:14:22",
    "protocolo": "SITFIS-2026-000123",
    "status": "Pendente",
    "observacao": "Reprocessado após revisão"
  }
}

Escopo: situacao_fiscal:write

`DELETE /situacao-fiscal/{id}`

Remove uma situação fiscal pelo ID.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID interno da situação fiscal

Request

Sem corpo de requisição.

Response 200 OK

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

Escopo: situacao_fiscal:write

`POST /situacao-fiscal/emitir`

Emite o relatório SITFIS na Receita Federal via SERPRO, para um único CNPJ (contribuinte), para uma lista de CNPJs informada, ou para a lista interna de clientes (usar_lista_interna: true). O processamento é síncrono e itera CNPJ a CNPJ - o retorno consolida sucessos e falhas por CNPJ. A mensagem de resposta reflete que a operação pode concluir com falhas parciais.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query - os dados vão no corpo da requisição (SituacaoFiscalEmitirRequest, ver Schema SituacaoFiscalEmitirRequest). Todos os campos são opcionais e a combinação define o modo de emissão.

Request

{
  "contribuinte": { "tipo": 2, "numero": "12345678000199" },
  "usar_lista_interna": false,
  "cnpjs": null,
  "id_cliente": 487
}

Emissão em lote a partir da base interna:

{
  "usar_lista_interna": true
}

Response 200 OK (envelope com data = SituacaoFiscalEmitirResponse)

{
  "success": true,
  "message": "Processo de emissão concluído (com possíveis falhas por CNPJ).",
  "data": {
    "summary": { "total": 3, "sucesso": 2, "falha": 1 },
    "itens": [
      {
        "cnpj": "12345678000199",
        "id": 9821,
        "protocolo": "SITFIS-2026-000123",
        "status": "Concluido",
        "pdfPath": "situacao_fiscal/9821.pdf"
      }
    ],
    "erros": [
      { "cnpj": "98765432000155", "status": 504, "detail": "Timeout no SERPRO" }
    ]
  }
}

Em caso de exceção não tratada, retorna o envelope de erro { success: false, message: "Erro ao emitir situação fiscal.", details: [...] }.

Escopo: situacao_fiscal:write

`GET /situacao-fiscal/stats`

Retorna analytics consolidados da situação fiscal (totais e distribuição por status). Útil para dashboards executivos.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O data retornado é um objeto de estatísticas.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Estatísticas recuperadas com sucesso!",
  "data": {
    "total": 128,
    "concluidas": 94,
    "pendentes": 21,
    "falhas": 13
  }
}

Escopo: situacao_fiscal:read

`GET /situacao-fiscal/monitoring`

Retorna contadores agregados das categorias de monitoramento (sem listar registros). Pareie com /monitoring/list quando precisar dos itens.

Parâmetros

Este endpoint não recebe parâmetros de rota ou query. O data retornado é um objeto de contadores por categoria.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Contadores de monitoramento recuperados com sucesso!",
  "data": {
    "sem_situacao": 7,
    "com_pendencia": 21,
    "exigibilidade_suspensa": 4,
    "total_regular": 90,
    "total_concluidas": 94,
    "total_pendentes": 21,
    "total_falhas": 13
  }
}

Escopo: situacao_fiscal:read

`GET /situacao-fiscal/monitoring/list`

Retorna listas (não contadores) do monitoramento, segmentadas por categoria.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`categoria`	`string?`	query	não	Uma de: `sem_situacao`, `com_pendencia`, `exigibilidade_suspensa`, `total_regular`, `total_concluidas`, `total_pendentes`, `total_falhas`.
`limit`	`int?`	query	não	1-10000. Default `200`. Se `null`, retorna tudo (cuidado com volume).
`offset`	`int`	query	não	Default `0`.

Uma categoria fora da lista aceita retorna 400 Bad Request com detail indicando as categorias válidas. Exemplo: GET /situacao-fiscal/monitoring/list?categoria=com_pendencia&limit=50.

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Itens de monitoramento recuperados com sucesso!",
  "data": {
    "categoria": "com_pendencia",
    "total": 21,
    "itens": [
      {
        "id": 9821,
        "id_cliente": 487,
        "protocolo": "SITFIS-2026-000123",
        "status": "Pendente"
      }
    ]
  }
}

Escopo: situacao_fiscal:read

`GET /situacao-fiscal/{id}`

Detalha uma situação fiscal pelo ID inteiro. Retorna o SituacaoFiscalRead completo (inclui pdf_base64, quando presente).

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID interno da situação fiscal

Request

Sem corpo de requisição.

Response 200 OK

{
  "success": true,
  "message": "Situação fiscal encontrada com sucesso!",
  "data": {
    "id": 9821,
    "id_usuario": 12,
    "id_cliente": 487,
    "data_hora_emissao": "2026-05-15T08:14:22",
    "protocolo": "SITFIS-2026-000123",
    "status": "Concluido",
    "pdf_base64": "JVBERi0xLjcK...",
    "observacao": null
  }
}

Quando não encontrado, retorna 404 Not Found com detail: "Situação fiscal não encontrada.".

Escopo: situacao_fiscal:read

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

Retorna application/pdf com header Content-Disposition: inline; filename=situacao_fiscal_<id>.pdf. Decodifica o pdf_base64 armazenado (aceita data URI - usa o segmento após a vírgula). Forma recomendada para abrir o PDF no navegador ou anexar em pipelines.

Parâmetros

Parâmetro	Tipo	Local	Obrigatório	Descrição
`id`	`int`	path	sim	ID interno da situação fiscal

Request

Sem corpo de requisição.

Response 200 OK

Retorna o binário application/pdf (não um envelope JSON), com header Content-Disposition: inline; filename=situacao_fiscal_9821.pdf.

Se a situação fiscal não existir ou não tiver pdf_base64, retorna o envelope de erro { success: false, message: "PDF não encontrado!", details: [] }. Se o base64 for inválido, retorna { success: false, message: "Erro ao decodificar o PDF.", details: [] }.

Escopo: situacao_fiscal:read

Schemas

`SituacaoFiscalCreate`

Herda de SituacaoFiscalBase.

Campo	Tipo	Obrigatório	Observações
`id_usuario`	`int`	sim	Usuário Alcance que registrou a emissão.
`id_cliente`	`int`	sim	Cliente vinculado (FK `customers.id`).
`data_hora_emissao`	`datetime?`	não	Data/hora da emissão. Default `null`.
`protocolo`	`str`	sim	Número de protocolo da emissão SITFIS.
`status`	`str`	sim	Situação do registro (ex.: `Concluido`, `Pendente`, `Falha`).
`pdf_base64`	`str?`	não	PDF do relatório em base64. Excluído das listagens.
`observacao`	`str?`	não	Observação livre.

`SituacaoFiscalUpdate`

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

Campo	Tipo	Observações
`observacao`	`str?`	Nova observação.
`status`	`str?`	Novo status.
`pdf_base64`	`str?`	Atualiza o PDF armazenado.

`SituacaoFiscalRead`

Herda de SituacaoFiscalBase e adiciona id. Retornado em GET / e GET /{id}.

Campo	Tipo	Observações
`id`	`int`	Identificador único da situação fiscal.
`id_usuario`	`int`	Usuário Alcance que registrou a emissão.
`id_cliente`	`int`	Cliente vinculado.
`data_hora_emissao`	`datetime`	Quando o registro foi emitido.
`protocolo`	`str`	Número de protocolo SITFIS.
`status`	`str`	Situação do registro.
`pdf_base64`	`str?`	PDF em base64, quando disponível.
`observacao`	`str?`	Observação livre.

`SituacaoFiscalEmitirRequest`

Body do endpoint POST /emitir. Todos os campos são opcionais - a combinação define o modo de emissão (contribuinte único, lista de CNPJs ou lista interna).

Campo	Tipo	Obrigatório	Observações
`contribuinte`	`ParteIdentificacao?`	não	Contribuinte único a emitir. Ver abaixo.
`usar_lista_interna`	`bool`	não	Se `true`, emite para a base interna de clientes. Default `false`.
`cnpjs`	`List[str]?`	não	Lista de CNPJs para emissão em lote.
`id_cliente`	`int?`	não	Vincula a emissão a um cliente específico.

ParteIdentificacao (usado em contribuinte):

Campo	Tipo	Obrigatório	Observações
`tipo`	`int`	sim	`1` = PF (CPF) · `2` = PJ (CNPJ).
`numero`	`str`	sim	CPF ou CNPJ, preferencialmente só dígitos.

`SituacaoFiscalEmitirResponse`

Retornado em data por POST /emitir.

Campo	Tipo	Observações
`summary`	`Dict[str, int]`	Contadores agregados do processamento em lote.
`itens`	`List[SituacaoFiscalEmitirItem]`	Emissões bem-sucedidas.
`erros`	`List[SituacaoFiscalEmitirError]`	Falhas por CNPJ.

SituacaoFiscalEmitirItem:

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	sim	CNPJ processado.
`id`	`int`	sim	ID do registro de situação fiscal criado.
`protocolo`	`str`	sim	Protocolo SITFIS retornado.
`status`	`str`	sim	Status da emissão.
`pdfPath`	`str?`	não	Caminho/referência do PDF gerado.

SituacaoFiscalEmitirError:

Campo	Tipo	Obrigatório	Observações
`cnpj`	`str`	sim	CNPJ que falhou.
`status`	`int?`	não	Código de status/HTTP do erro.
`detail`	`Any`	não	Detalhe do erro (string ou objeto).

Categorias do monitoramento

Valores aceitos pelo query param categoria em /monitoring/list (e chaves retornadas em /monitoring):

Categoria	Significado
`sem_situacao`	Clientes que ainda não possuem situação fiscal emitida no período.
`com_pendencia`	Emissões com pendências identificadas.
`exigibilidade_suspensa`	Pendências cuja exigibilidade está suspensa (parcelamento, liminar).
`total_regular`	Situações regulares.
`total_concluidas`	Emissões concluídas no período.
`total_pendentes`	Emissões em aberto/pendentes.
`total_falhas`	Tentativas de emissão que falharam.

Notas

Emissão síncrona com falhas parciais

POST /situacao-fiscal/emitir processa os CNPJs de forma síncrona, um a um, e sempre retorna 200 OK mesmo quando algum CNPJ falha - as falhas vêm em data.erros. Sempre inspecione summary, itens e erros para saber o que de fato foi emitido. Para lotes grandes (usar_lista_interna: true), a requisição pode demorar.

PDF na listagem

GET /situacao-fiscal/ retorna o SituacaoFiscalRead, cujo campo pdf_base64 pode ser volumoso. Para obter apenas o binário do PDF de um registro específico, prefira GET /situacao-fiscal/{id}/pdf (retorna application/pdf com Content-Disposition).

Ordem das rotas

As rotas estáticas GET /stats, GET /monitoring e GET /monitoring/list são declaradas antes da rota dinâmica GET /{id}, então são resolvidas como rotas estáticas (e não interpretadas como um id).

Toda resposta segue o envelope { success, message, data } (ou { success: false, message, details } em erro).
Relaciona-se com o domínio de detalhamento da situação fiscal (situacao_fiscal_detalhamento), usado internamente pelo caso de uso de emissão para armazenar o detalhamento por pendência.