Eventos de NFS-e

Tutorial para registro de eventos em NFS-e através do Sistema Nacional (ADN), incluindo cancelamento e substituição.

Visão Geral

Os eventos permitem modificar o status de uma NFS-e emitida. Os principais tipos de eventos são:

Tipo	Código	Descrição
Cancelamento	e101101	Cancela a NFS-e
Substituição	e105102	Substitui a NFS-e por outra
Confirmação de Prestação	e201101	Confirma que o serviço foi prestado
Rejeição do Serviço	e202101	Tomador rejeita o serviço

Estrutura do Pedido de Registro de Evento

from abstra.connectors import run_connection_action

params = {
    "inf_ped_reg": {
        "id": "EVTXXX...",  # ID do evento (será computado)
        "tp_evento": "e101101",  # Tipo do evento
        "chave_acesso": "33251212345678000199550010000000011234567890",
        "n_seq_evento": "1",  # Sequência do evento (1 para primeiro)
        "dh_evento": "2025-12-11T14:00:00-03:00",  # Data/hora do evento
        "det_evento": {
            # Detalhes específicos do evento
        }
    },
    "versao": "1.01"
}

result = run_connection_action(
    "adn-nfse",
    "post_nfse_by_chave_acesso_eventos",
    params
)

Cancelamento de NFS-e

O cancelamento anula a NFS-e emitida. Só é permitido dentro do prazo estabelecido pelo município.

def cancelar_nfse(chave_acesso: str, justificativa: str, codigo_cancelamento: str = "1"):
    """
    Cancela uma NFS-e emitida.

    Args:
        chave_acesso: Chave de acesso da NFS-e (50 caracteres)
        justificativa: Motivo do cancelamento (mínimo 15 caracteres)
        codigo_cancelamento: Código do motivo (1=erro emissão, 2=serviço não prestado, etc.)
    """
    from datetime import datetime

    # Data/hora atual no formato ISO
    dh_evento = datetime.now().strftime("%Y-%m-%dT%H:%M:%S-03:00")

    params = {
        "inf_ped_reg": {
            "tp_evento": "e101101",  # Cancelamento
            "chave_acesso": chave_acesso,
            "n_seq_evento": "1",
            "dh_evento": dh_evento,
            "det_evento": {
                "e101101": {
                    "x_desc": justificativa,
                    "c_motivo": codigo_cancelamento
                }
            }
        },
        "versao": "1.01"
    }

    return run_connection_action(
        "adn-nfse",
        "post_nfse_by_chave_acesso_eventos",
        params
    )


# Uso
result = cancelar_nfse(
    chave_acesso="33251212345678000199550010000000011234567890",
    justificativa="Cancelamento devido a erro na emissão - serviço será refaturado",
    codigo_cancelamento="1"
)

if result.get("status") == "success":
    print("NFS-e cancelada com sucesso!")
else:
    print(f"Erro: {result.get('message')}")

Códigos de Motivo de Cancelamento

Código	Descrição
1	Erro na emissão
2	Serviço não prestado
3	Erro de preenchimento
4	Duplicidade de NFS-e
9	Outros

Substituição de NFS-e

A substituição cancela a NFS-e original e emite uma nova no lugar.

def substituir_nfse(
    chave_acesso_original: str,
    justificativa: str,
    nova_dps: dict
):
    """
    Substitui uma NFS-e por uma nova.

    Args:
        chave_acesso_original: Chave de acesso da NFS-e a ser substituída
        justificativa: Motivo da substituição
        nova_dps: Dados da nova DPS
    """
    from datetime import datetime

    dh_evento = datetime.now().strftime("%Y-%m-%dT%H:%M:%S-03:00")

    params = {
        "inf_ped_reg": {
            "tp_evento": "e105102",  # Substituição
            "chave_acesso": chave_acesso_original,
            "n_seq_evento": "1",
            "dh_evento": dh_evento,
            "det_evento": {
                "e105102": {
                    "x_desc": justificativa,
                    "dps_sub": nova_dps  # Nova DPS que substituirá
                }
            }
        },
        "versao": "1.01"
    }

    return run_connection_action(
        "adn-nfse",
        "post_nfse_by_chave_acesso_eventos",
        params
    )

Consultar Eventos de uma NFS-e

Todos os Eventos

result = run_connection_action(
    "adn-nfse",
    "get_nfse_by_chave_acesso_eventos",
    {"chaveAcesso": "33251212345678000199550010000000011234567890"}
)

if result.get("status") == "success":
    eventos = result["data"].get("eventos", [])
    for evento in eventos:
        print(f"Evento: {evento['tipo']}")
        print(f"Data: {evento['data_hora']}")

Por Tipo de Evento

result = run_connection_action(
    "adn-nfse",
    "get_nfse_by_chave_acesso_eventos_by_tipoevento",
    {
        "chaveAcesso": "33251212345678000199550010000000011234567890",
        "tipoEvento": "e101101"  # Cancelamento
    }
)

Evento Específico

result = run_connection_action(
    "adn-nfse",
    "get_nfse_by_chave_acesso_eventos_by_tipo_evento_by_num_seq_evento",
    {
        "chaveAcesso": "33251212345678000199550010000000011234567890",
        "tipoEvento": "e101101",
        "numSeqEvento": "1"
    }
)

Tratamento de Respostas

Resposta de Sucesso

{
    "status": "success",
    "data": {
        "tipo_ambiente": 2,
        "versao_aplicativo": "SefinNac_Pre_1.4.0",
        "data_hora_processamento": "2025-12-11T14:30:00-03:00",
        "evento": {
            "tipo_evento": "e101101",
            "n_seq_evento": "1",
            "chave_acesso": "33251212345678000199550010000000011234567890",
            "c_stat": "135",  # Evento registrado
            "x_motivo": "Evento registrado com sucesso"
        },
        "evento_xml_g_zip_b64": "H4sIAAAAAAAA...",
        "evento_xml": "<evento>...</evento>"
    }
}

Códigos de Status

Código	Descrição
135	Evento registrado com sucesso
494	NFS-e já cancelada
501	Prazo para cancelamento expirado
573	Chave de acesso inválida
574	Evento duplicado

Prazos para Eventos

Os prazos variam por município. Consulte o parâmetro do convênio:

result = run_connection_action(
    "adn-nfse",
    "get_by_codigo_municipio_convenio",
    {"codigoMunicipio": "3304557"}
)

# Os prazos estão nos parâmetros do convênio
params = result["data"]["parametros_convenio"]

Erros Comuns

E494 - NFS-e já cancelada

Causa: Tentativa de cancelar uma NFS-e que já foi cancelada.

Solução: Verifique o status da NFS-e antes de tentar cancelar.

E501 - Prazo expirado

Causa: Tentativa de cancelar após o prazo permitido pelo município.

Solução: Entre em contato com a prefeitura para solicitar cancelamento administrativo.

E574 - Evento duplicado

Causa: Já existe um evento com mesmo tipo e sequência.

Solução: Use um número de sequência diferente (n_seq_evento).

Exemplo Completo: Fluxo de Cancelamento

def cancelar_com_verificacao(chave_acesso: str, justificativa: str):
    """
    Cancela uma NFS-e após verificar se está elegível.
    """
    # 1. Consultar NFS-e para verificar status
    result = run_connection_action(
        "adn-nfse",
        "get_nfse_by_chave_acesso",
        {"chaveAcesso": chave_acesso}
    )

    if result.get("status") != "success":
        return {"sucesso": False, "erro": "NFS-e não encontrada"}

    # 2. Verificar se já existe evento de cancelamento
    result_eventos = run_connection_action(
        "adn-nfse",
        "get_nfse_by_chave_acesso_eventos_by_tipoevento",
        {
            "chaveAcesso": chave_acesso,
            "tipoEvento": "e101101"
        }
    )

    if result_eventos.get("status") == "success":
        eventos = result_eventos["data"].get("eventos", [])
        if eventos:
            return {"sucesso": False, "erro": "NFS-e já possui evento de cancelamento"}

    # 3. Executar cancelamento
    result_cancel = cancelar_nfse(chave_acesso, justificativa)

    if result_cancel.get("status") == "success":
        return {
            "sucesso": True,
            "protocolo": result_cancel["data"].get("evento", {}).get("protocolo")
        }
    else:
        return {
            "sucesso": False,
            "erro": result_cancel.get("message")
        }


# Uso
resultado = cancelar_com_verificacao(
    "33251212345678000199550010000000011234567890",
    "Cancelamento por erro de digitação no valor do serviço"
)

if resultado["sucesso"]:
    print(f"Cancelamento realizado! Protocolo: {resultado['protocolo']}")
else:
    print(f"Falha: {resultado['erro']}")