Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Como manifestar uma NFS-e recebida

Manifestação é o registro formal do tomador sobre uma NFS-e recebida — usado para auditoria fiscal, conformidade tributária, e (em caso de rejeição) sinalização ao prestador de que a nota tem inconsistência. O padrão nacional aceita apenas dois tipos: Ciência (203202) e Rejeição (203206). Esta receita mostra o fluxo completo de ponta a ponta, incluindo o callback assíncrono e os códigos cStat retornados pelo SEFIN Nacional.

Sumário​

Pré-requisitos​

  • Empresa com NFS-e Inbound ativo — veja Integração REST.
  • accessKey da NFS-e (50 dígitos) — obtenha listando documentos ou recebendo o webhook inbound.serviceInvoice.received.
  • Decisão informada: Ciência confirma conhecimento da nota; Rejeição contesta formalmente (pode bloquear créditos tributários do tomador).
  • Endpoint de webhook configurado (recomendado) — para receber o callback inbound.manifestation.submitted assincronamente.

Fluxo​

Solução​

A submissão de manifestação é assíncrona: o POST retorna 202 Accepted com status: "Pending" imediatamente. O worker da NFE.io processa em background, dialoga com o SEFIN Nacional e transita o status para Accepted, Rejected ou Failed. Você acompanha por polling em GET /manifestations/{id} ou pelo callback webhook inbound.manifestation.submitted.

Etapa 1: Decidir Ciência ou Rejeição​

Use Ciência (203202) quando concorda com a nota e quer apenas registrar conhecimento — caso padrão para a maioria dos serviços recebidos legitimamente. Pode ser automatizado ativando isAutomaticManifestationEnabled na empresa.

Use Rejeição (203206) quando a nota tem inconsistência fiscal ou foi emitida indevidamente. Exige um reasonCode codificado e, opcionalmente, um texto livre em justification (≤ 255 caracteres pelo XSD do SEFIN).

reasonCodeDescrição
1Duplicata
2Já emitida pelo tomador
3Sem fato gerador
4Erro de responsabilidade tributária
5Erro de valor, serviço ou data
9Outros (use o justification para descrever)

Etapa 2: Submeter a manifestação​

# Ciência — sem body (reasonCode/justification não se aplicam)
curl -X POST \
  "$BASE/v2/companies/$COMPANY_ID/inbound/nfse/by-access-key/$ACCESS_KEY/manifestations?eventCode=203202" \
  -H "Authorization: $NFEIO_API_KEY"

# Rejeição — body obrigatório com reasonCode
curl -X POST \
  "$BASE/v2/companies/$COMPANY_ID/inbound/nfse/by-access-key/$ACCESS_KEY/manifestations?eventCode=203206" \
  -H "Authorization: $NFEIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reasonCode": 1,
    "justification": "Nota duplicada da NFS-e 35250612345..."
  }'

Resposta esperada 202 Accepted com o NFSeManifestationEventResource inicial:

{
  "id": "69e193685b7241b5c4fe8e3c",
  "companyId": "5f9b1c2d3e4f5a6b7c8d9e0f",
  "accessKey": "35503081223301943000745000000002734526036434454892",
  "eventCode": 203202,
  "reasonCode": null,
  "justification": null,
  "status": "Pending",
  "environment": "Production",
  "createdAt": "2026-05-27T13:42:11Z",
  "submittedAt": null,
  "acceptedAt": null,
  "errorCode": null,
  "errorMessage": null
}

O header Location aponta para GET /v2/companies/{companyId}/inbound/nfse/manifestations/{id} — use para polling.

Etapa 3: Acompanhar o estado terminal​

Via webhook (preferido): ao concluir, a NFE.io dispara inbound.manifestation.submitted com manifestation.status igual a Accepted, Rejected ou Failed. Veja o catálogo de eventos do webhook para o payload completo.

Via polling:

curl "$BASE/v2/companies/$COMPANY_ID/inbound/nfse/manifestations/$MANIFEST_ID" \
  -H "Authorization: $NFEIO_API_KEY"

O detalhe inclui os XMLs de request e response do SEFIN em GZip+Base64 (requestXmlGZipB64, responseXmlGZipB64) — úteis para auditoria fiscal e investigação de rejeições. Códigos cStat mais comuns:

errorCodeSignificadoAção
135Evento registrado e vinculadoSucesso.
136Evento registrado, não vinculado à NFS-eSucesso parcial — chave pode estar incorreta.
217NFS-e não consta na base SEFINAguarde latência ADN (alguns minutos) e tente novamente.
573Duplicidade de eventoJá existe evento do mesmo tipo — consulte GET /manifestations por accessKey.
999Erro interno SEFINRetentar após 5–10 minutos.

Variações​

  • Automação total da Ciência: ative isAutomaticManifestationEnabled: true com automaticManifestationDelaySeconds (ex.: 3600 = 1 hora) na empresa via PUT /v2/companies/{companyId}/inbound/nfse/details. A NFE.io envia Ciência sozinha após o delay. Rejeição nunca é automatizada — sempre exige decisão humana.
  • Manifestação em lote: itere sobre GET /v2/companies/{companyId}/inbound/nfse?type=Nfse&status=Processed e dispare uma manifestação por documento. Respeite rate limits internos do SEFIN — não paralelize além de 5 chamadas simultâneas.
  • Auditoria fiscal: decode o responseXmlGZipB64 para obter o XML literal da resposta SEFIN (com cStat, xMotivo, dhRegEvento e o protocolo gerado). Útil em fiscalizações que exigem comprovante de tentativa.
  • Listar manifestações já submetidas: GET /v2/companies/{companyId}/inbound/nfse/by-access-key/{accessKey}/manifestations retorna o histórico para uma NFS-e específica.

Armadilhas comuns​

  • 409 Conflict ao submeter: já existe uma manifestação Pending para o par (accessKey, eventCode). Consulte GET /manifestations antes de re-submeter — provavelmente a primeira ainda está em processamento.
  • 422 Unprocessable Entity: corpo ausente para eventCode=203206 ou reasonCode inválido (fora de 1/2/3/4/5/9). Sempre inclua o body em rejeições.
  • justification truncada: o XSD do SEFIN Nacional limita o campo a 255 caracteres. Mensagens maiores são truncadas silenciosamente — encurte antes de enviar.
  • cStat=217 logo após receber a NFS-e: o SEFIN tem latência entre publicar no ADN e indexar para consulta de evento. Aguarde alguns minutos antes de manifestar uma nota recém-capturada.
  • Rejeição não cancela a NFS-e: a nota permanece válida no ADN; a rejeição apenas a marca como contestada. Cancelamento efetivo é responsabilidade do prestador (evento 101101).
  • automaticManifestationDelaySeconds máximo: o valor é validado contra 604800 segundos (7 dias). Valores maiores são rejeitados na ativação.

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.