---
title: "Códigos de evento — XSD vs CSV"
description: "Distinção entre os dois contextos de eventCode no NFS-e Inbound: XSD tpEvento (webhook) vs EventCode do CSV de bulk export analítico."
source_url: https://nfe.io/docs/distribuicao-nfse-inbound-codigos-evento/
last_updated: 2026-07-30
---

# 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.

:::warning 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](#quando-você-verá-cada-um)
- [Tabela 1 — XSD `tpEvento` (canônico SEFIN)](#tabela-1--xsd-tpevento-canônico-sefin)
- [Tabela 2 — CSV `EventCode` (catálogo NFE.io)](#tabela-2--csv-eventcode-catálogo-nfeio)
- [Mapeamento entre os dois](#mapeamento-entre-os-dois)

## Quando você verá cada um

| Cenário | Conjunto aplicável | Onde aparece |
|---|---|---|
| Implementar handler do webhook `inbound.serviceInvoice.event.received` | **XSD `tpEvento`** | Campo `body.document.eventCode` |
| Submeter manifestação (Ciência/Rejeição) via API | **XSD `tpEvento`** | Query param `eventCode` em `POST .../manifestations` |
| Filtrar por status no callback `inbound.manifestation.submitted` | **XSD `tpEvento`** | Campo `body.manifestation.eventCode` |
| Ler coluna `EventCode` do CSV analítico de bulk export | **CSV NFE.io** | Coluna 7 (ou conforme cabeçalho do CSV) |
| Filtrar linhas do CSV por tipo de evento | **CSV NFE.io** | Apenas 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.

| `eventCode` | `eventType` | Descrição |
|---|---|---|
| `101101` | `Cancellation` | NFS-e cancelada pelo prestador |
| `105102` | `CancellationBySubstitution` | Cancelamento por substituição |
| `203202` | `BorrowerConfirmation` | Tomador confirmou (Ciência) |
| `203206` | `BorrowerRejection` | Tomador rejeitou |
| `205204` | `TacitConfirmation` | Confirmação tácita (prazo expirado) |
| `305101` | `OfficialCancellation` | Cancelamento 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ção | Mapeia para XSD |
|---|---|---|
| `310610` | Linha representa NFS-e cancelada | `101101` |
| `310611` | Linha representa NFS-e substituída | `105102` |

:::note 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 |
|---|---|---|
| `101101` | `310610` | Cancelamento direto |
| `105102` | `310611` | Cancelamento 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

- [Catálogo do webhook](webhook-events.md) — onde `eventCode` XSD aparece no payload
- [Receita — Manifestação do tomador](../how-to/manifestacao-tomador.md) — submeter `eventCode=203202` ou `203206`
- [Receita — Bulk Export](../how-to/bulk-export.md) — onde `EventCode` CSV aparece
- [Troubleshooting](troubleshooting.md) — `cStat` SEFIN no callback de manifestação