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

Códigos de evento — XSD vs CSV

No NFS-e Inbound existem dois conjuntos distintos de códigos numéricos chamados eventCode, com origens e contextos diferentes. Confundi-los é uma armadilha comum — esta página separa explicitamente.

Não são intercambiáveis

Os dois conjuntos representam fatos do mundo real que se sobrepõem (uma NFS-e cancelada gera ambos), mas vivem em sistemas diferentes:

  • XSD tpEvento é o código canônico do SEFIN Nacional (definido no schema oficial tiposEventos_v1.01.xsd).
  • CSV EventCode é o catálogo interno da NFE.io usado apenas no bulk export analítico para identificar o tipo da linha agregada.

Filtrar por um quando o contexto exige o outro retorna conjunto vazio.

Sumário​

Quando você verá cada um​

CenárioConjunto aplicávelOnde aparece
Implementar handler do webhook inbound.serviceInvoice.event.receivedXSD tpEventoCampo body.document.eventCode
Submeter manifestação (Ciência/Rejeição) via APIXSD tpEventoQuery param eventCode em POST .../manifestations
Filtrar por status no callback inbound.manifestation.submittedXSD tpEventoCampo body.manifestation.eventCode
Ler coluna EventCode do CSV analítico de bulk exportCSV NFE.ioColuna 7 (ou conforme cabeçalho do CSV)
Filtrar linhas do CSV por tipo de eventoCSV NFE.ioApenas dentro do CSV — não tente bater com payload de webhook

Tabela 1 — XSD tpEvento (canônico SEFIN)​

Fonte: schema tiposEventos_v1.01.xsd do padrão nacional NFS-e (Lei Complementar 214/2025).

Aparece no payload do webhook inbound.serviceInvoice.event.received. O endpoint de manifestação (POST .../manifestations?eventCode=...) só aceita os dois códigos de manifestação do tomador: 203202 (Confirmação) e 203206 (Rejeição). Para Rejeição (203206), o reasonCode é obrigatório e deve ∈ {1, 2, 3, 4, 5, 9}. Os demais códigos desta tabela aparecem apenas como eventos recebidos no webhook — não são aceitos pelo endpoint de manifestação.

eventCodeeventTypeDescrição
101101CancellationNFS-e cancelada pelo prestador
105102CancellationBySubstitutionCancelamento por substituição
203202BorrowerConfirmationTomador confirmou (Ciência)
203206BorrowerRejectionTomador rejeitou
205204TacitConfirmationConfirmação tácita (prazo expirado)
305101OfficialCancellationCancelamento por ofício

Outros códigos do XSD (202201 Provider Confirmation — prestador, 204203 Intermediary Confirmation — intermediário, etc.) podem aparecer no payload do webhook de recebimento, mas não são aceitos pelo endpoint de manifestação (que expõe apenas eventos do tomador). Códigos novos podem chegar com eventType=null — a NFE.io propaga o eventCode raw sem traduzir.

Tabela 2 — CSV EventCode (catálogo NFE.io)​

Fonte: catálogo interno da NFE.io para identificar o evento primário de cada linha no CSV analítico gerado por bulk export (company-nfse-inbound-analytical-csv).

Uma NFS-e pode acumular múltiplos eventos ao longo do ciclo de vida (Ciência → Cancelamento, Confirmação → Substituição, etc.). A coluna EventCode do CSV identifica o evento primário da linha agregada, usando a regra de prioridade:

Substituição (310611) > Cancelamento (310610) > evento mais recente

EventCode (CSV)DescriçãoMapeia para XSD
310610Linha representa NFS-e cancelada101101
310611Linha representa NFS-e substituída105102
Por que códigos diferentes?

O catálogo CSV foi desenhado antes do padrão nacional estabilizar, e o intervalo 310xxx segue convenção interna da NFE.io para evitar colisão com tpEvento do SEFIN. Mudanças de padronização estão no roadmap, mas exigem coordenação com clientes que já consomem o CSV — não há prazo confirmado.

Mapeamento entre os dois​

Quando precisar correlacionar um evento de webhook com uma linha do CSV:

Webhook (eventCode XSD)CSV (EventCode NFE.io)Significado
101101310610Cancelamento direto
105102310611Cancelamento por substituição
203202, 203206, 205204, 305101(sem coluna específica)Outros eventos não geram linha primária no CSV — aparecem em colunas de contagem agregada

Para cancelamentos por ofício (305101) e confirmações tácitas (205204), a NFS-e segue como linha primária e o evento aparece apenas em colunas auxiliares do CSV (hasOfficialCancellation, tacitConfirmationDate etc., conforme cabeçalho da época).

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.