Análise fiscal para cancelamento

POST /v1/notas/{notaId}/analise-fiscal com o token de acesso e o mesmo corpo do cancelamento, { "motivo": "...", "cMotivo": "2" } (referência). A API transmite à Sefin Nacional, de forma assíncrona, o evento 101103 (Solicitação de Análise Fiscal para Cancelamento de NFS-e), que pede ao município emissor que analise e decida o cancelamento. É a saída quando o cancelamento direto não é mais aceito.

Quando pedir

A API não decide por você: não conhece o prazo de cancelamento do município nem consulta as manifestações do tomador. Peça a análise quando o cancelamento direto for recusado (tipicamente cancelamento_rejeitado com E0822, fora do prazo) ou quando souber que ele não é mais aceito.

Pelas regras de eventos da Sefin Nacional, o pedido é aceito em nota autorizada sem outro evento e em nota confirmada tacitamente, e é recusado (E0848) quando a nota já tem confirmação expressa do prestador, do tomador ou do intermediário, cancelamento, substituição, análise fiscal anterior, decisão do município ou cancelamento de ofício. Nota confirmada expressamente pelo tomador não tem saída pela análise fiscal: procure a administração tributária do município.

Regras do pedido

• Só nota autorizada pode ter análise fiscal pedida.
• motivo (obrigatório): as mesmas regras do cancelamento, de 15 a 255 caracteres depois de remover os espaços das pontas, só com caracteres de U+0020 a U+00FF. É o texto que o agente municipal lê: descreva o caso.
• cMotivo (opcional): a mesma classificação do cancelamento, 1 erro na emissão, 2 serviço não prestado, 9 outros; sem o campo, vale 9; outro valor é recusado com 400 VALIDACAO_CAMPO, no campo cMotivo. Não confunda com resultado.codigoMotivo, que é o código da decisão do município.
• A nota continua autorizada durante a análise, porque continua válida na Sefin Nacional até o deferimento. O pedido aparece no grupo analiseFiscal da nota; não há status novo.
• Idempotência: repetir o pedido de uma nota com pedido ativo (solicitado ou registrado, inclusive já decidido) devolve 202 com o pedido existente, com o motivo e o cMotivo do primeiro, sem novo evento na Sefin Nacional. Depois de um pedido rejeitado, um novo pedido pode ser feito.

Requisição

POST /v1/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/analise-fiscal HTTP/1.1
Host: hml.nfse.lideraweb.com
Authorization: Bearer <seu-token>
Content-Type: application/json

{
  "motivo": "Serviço não prestado conforme o contrato",
  "cMotivo": "2"
}

curl -X POST "$BASE_URL/notas/3f8b2c1a-6d4e-4b7f-9a21-0c5e8d7f6a10/analise-fiscal" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "motivo": "Serviço não prestado conforme o contrato",
  "cMotivo": "2"
}'

Resposta 202:

{
  "status": "solicitado",
  "motivo": "Serviço não prestado conforme o contrato",
  "cMotivo": "2",
  "solicitadoEm": "2026-11-10T14:03:12.345Z"
}

status é solicitado, registrado ou rejeitado; cMotivo vem sempre preenchido. Quando houver, a resposta traz registradoEm (registro do pedido na Sefin Nacional), erro (só em rejeitado), resultado (a decisão do município) e acompanhamentoEncerradoEm (fim do acompanhamento sem decisão, abaixo). O resultado traz evento (105104 deferido ou 105105 indeferido), decisao (deferido ou indeferido), codigoMotivo, motivo (justificativa do município), processoAdministrativo (se o município informou) e decididoEm.

Desfecho, em duas etapas

1. Registro do pedido na Sefin Nacional (segundos): evento analise_fiscal_registrada, com analiseFiscal.status registrado, ou analise_fiscal_rejeitada, com analiseFiscal.erro; nos dois casos a nota continua autorizada.
2. Decisão do município (dias ou semanas): deferido, evento cancelada, e a nota passa a cancelada, com XML, links e DANFSe com a marca "CANCELADA"; indeferido, evento analise_fiscal_indeferida, e a nota continua autorizada com analiseFiscal.resultado.

A LideraNota consulta a decisão do município sozinha, com intervalos crescentes (1 hora, 2 horas, 4 horas, até uma vez por dia), por até 90 dias. Sem decisão nesse prazo, as consultas automáticas param e a consulta da nota passa a trazer analiseFiscal.acompanhamentoEncerradoEm. Isso não é decisão e não gera evento: a nota continua autorizada, o pedido continua registrado e o município ainda pode decidir.

Se a decisão demorar, peça a retomada do acompanhamento da análise fiscal, informando o id da nota. A LideraNota executa este passo: pedir pelo WhatsApp.

Efeitos na nota

Respostas de erro

Rejeições da Sefin Nacional ao pedido chegam em analiseFiscal.erro, com o evento analise_fiscal_rejeitada: por exemplo E0848 (a nota já tem um evento que impede o pedido), E1831 (NFS-e inexistente no Ambiente de Dados Nacional) e E0831 (ambiente diferente do que gerou a nota).