Cancelamentos e Eventos¶

Objetivo¶

Documentar os fluxos de cancelamento de NF-e, NFC-e, NFS-e, Carta de Correção (CCe) e demais eventos relacionados, com mapeamento técnico e de configuração.

Cancelamento de NF-e¶

Método: `action_cancelar_nfe()` (linha 7027)¶

Aspecto	Detalhe
Endpoint	`GET /ManagerAPIWeb/nfe/cancela`
Parâmetros URL	`Grupo`, `CNPJ`, `ChaveNota`, `Justificativa`
Autenticação	HTTP Basic Auth
Pré-requisito	NF-e autorizada com `l10n_br_chave_nf` preenchido

Parâmetros de URL¶

Parâmetro	Origem	Observação
`Grupo`	`l10n_br_documento_id.l10n_br_grupo`	Grupo do integrador
`CNPJ`	`company_id.l10n_br_cnpj`	Sem formatação
`ChaveNota`	`l10n_br_chave_nf`	44 dígitos
`Justificativa`	`l10n_br_motivo`	Mínimo 15 caracteres (exigência SEFAZ)

Fluxo¶

flowchart TD
    A["action_cancelar_nfe()"] --> B["POST nfe/cancela"]
    B --> C{"Resposta?"}
    C -->|"Evento registrado"| D["situacao = cancelado"]
    D --> E["Gera XML + DANFE cancelamento"]
    C -->|"Cancelamento fora prazo"| D
    C -->|Outro erro| F["situacao = excecao_cancelado"]

Campos atualizados após cancelamento¶

Campo	Valor
`l10n_br_cstat_nf`	Código status SEFAZ
`l10n_br_xmotivo_nf`	Mensagem da SEFAZ
`l10n_br_situacao_nf`	`cancelado`

Cancelamento de NFC-e¶

Método: `action_cancelar_nfce()` (linha 7121)¶

Status: return no início — método não implementado (TODO: NFC-e).

O cancelamento de NFC-e segue a mesma estrutura da NF-e mas usa o endpoint nfe/cancela (modelo 65 compartilha o endpoint no ManagerSaaS).

Cancelamento de NFS-e¶

Método: `action_cancelar_nfse()` (linha 5755)¶

Aspecto	Detalhe
Endpoint	`POST /ManagerAPIWeb/nfse/cancela`
Autenticação	HTTP Basic Auth
Pré-requisito	NFS-e emitida com handle ou número RPS

Fluxo do Cancelamento NFS-e¶

O cancelamento NFS-e é mais complexo que o da NF-e, pois depende do município. Há dois fluxos possíveis:

Via Handle: municipalidades que registram handle na emissão
Via NumeroRPS + Serie: fallback quando handle não disponível

Dados enviados¶

Campo	Origem	Observação
`NomeCidade`	`company_id.l10n_br_municipio_id.name`	Município do emitente
`Handle`	`l10n_br_nfse_handle`	Identificador no integrador
`Justificativa`	`l10n_br_motivo`	Motivo do cancelamento

Carta de Correção Eletrônica (CCe)¶

Método: `action_gerar_cce_nfe()` (linha 7248)¶

A CCe é enviada como um TX2 de evento ao mesmo endpoint nfe/envia.

TX2 gerado por `_gerar_cce_nfe_tx2()` (linha 3884)¶

Campo TX2	Origem	Observação
`Documento`	Fixo	`CCE`
`ChaveNota`	Fatura	`l10n_br_chave_nf` (44 dígitos)
`dhEvento`	Calculado	`datetime.now(tz=SP)` formato ISO
`Orgao`	Empresa → Estado	`l10n_br_codigo_ibge` da UF
`SeqEvento`	Fatura	`l10n_br_sequencia_evento + 1`
`Correcao`	Fatura	`l10n_br_correcao` (texto da correção)
`Lote`	Fixo	`1`
`Fuso`	Calculado	Fuso horário de São Paulo

Regras da CCe¶

Regra funcional: - Máximo de 20 CCe por NF-e - Não é permitido alterar: valores, quantidades, CFOP, CST, alíquotas - Permitido alterar: razão social, endereço, condição de pagamento, datas de saída, transportadora

Fluxo CCe¶

flowchart TD
    A["action_gerar_cce_nfe()"] --> B["_gerar_cce_nfe_tx2()"]
    B --> C["POST nfe/envia"]
    C --> D{"Resposta AUTORIZADA?"}
    D -->|Sim| E["Incrementa sequencia_evento"]
    E --> F["situacao = cce"]
    F --> G["Gera XML + DANFE CCe"]
    D -->|Não| H["situacao = excecao_cce"]

Campos atualizados¶

Campo	Valor
`l10n_br_sequencia_evento`	Incrementado +1
`l10n_br_situacao_nf`	`cce`
`l10n_br_cstat_nf`	Código SEFAZ
`l10n_br_xmotivo_nf`	Mensagem SEFAZ

Resolver NF-e (Pendências)¶

Método: `action_resolver_nfe()` (linha 6263)¶

Chamado quando a NF-e foi enviada mas a resposta não foi conclusiva (ex: timeout, exceção já existente).

Aspecto	Detalhe
Endpoint	`POST /ManagerAPIWeb/nfe/resolve`
Dados	`Grupo`, `CNPJ`, `ChaveNota`
Retorno	Resolve o status final da NF-e (autorizada, rejeitada, etc.)

Consulta de NFS-e¶

Método: `action_resolver_nfse()` (região linha 6447)¶

Usa dois fluxos: 1. Consulta: GET /ManagerAPIWeb/nfse/consulta?Filtro=handle={handle} ou Filtro=nrps={rps} 2. Resolve: GET /ManagerAPIWeb/nfse/resolve?Handle={handle} ou NumRPS={rps}&SerieRPS={serie}&TipoRPS={tipo}

Geração de XMLs e DANFEs¶

Métodos de download de artefatos do integrador:

Método	Endpoint	Artefato
`action_gerar_xml_nfe()`	`nfe/xml?ChaveNota=`	XML autorização
`action_gerar_danfe_nfe()`	`nfe/imprime?ChaveNota=`	PDF DANFE
`action_gerar_xml_cancelado_nfe()`	`nfe/xml?Documento=Cancelamento`	XML cancelamento
`action_gerar_danfe_cancelado_nfe()`	`nfe/imprime?ChaveNota=` (após cancel)	DANFE cancelado
`action_gerar_xml_cce_nfe()`	`nfe/xml?Documento=CCe`	XML CCe
`action_gerar_danfe_cce_nfe()`	`nfe/imprime?Documento=CCe`	PDF CCe
`action_gerar_xml_nfse()`	`nfse/xml?Handle=`	XML NFS-e
`action_gerar_rps_nfse()`	`nfse/imprime?Handle=`	PDF RPS
`action_gerar_xml_nfce()`	`nfce/xml?ChaveNota=`	XML NFC-e
`action_gerar_danfe_nfce()`	`nfce/imprime?ChaveNota=`	PDF NFC-e

Inutilização de Numeração¶

Investigação: Não foi encontrado método de inutilização no account.py. A API TecnoSpeed suporta via nfe/inutiliza (conforme Postman collection), mas não há implementação no módulo.

Descarte de RPS NFS-e¶

Método: `action_descartar_rps_nfse()` (linha 5135)¶

Aspecto	Detalhe
Endpoint	`GET /ManagerAPIWeb/nfse/descarta`
Parâmetros	`Grupo`, `CNPJ`, `NomeCidade`, `Handle`
Função	Descarta RPS no integrador sem emitir NFS-e

Tabela de Status¶

`l10n_br_situacao_nf`	Significado	Ações disponíveis
(vazio)	Não transmitido	Gerar NF-e/NFS-e
`autorizado`	NF-e autorizada	Cancelar, CCe, Gerar XMLs
`cancelado`	Cancelado na SEFAZ	Gerar XMLs cancelamento
`cce`	CCe registrada	Gerar XMLs CCe
`excecao_autorizado`	Erro na autorização	Resolver, Reprocessar
`excecao_cancelado`	Erro no cancelamento	Reprocessar cancelamento

Como Configurar para Cancelamento¶

Justificativa obrigatória: Preencher campo l10n_br_motivo na fatura (mín. 15 chars)
Prazo: NF-e deve ser cancelada em até 24 horas (regra SEFAZ, não validada no código)
Chave NF: Deve estar preenchida (l10n_br_chave_nf)
Permissão: Usuário deve ter acesso ao botão de cancelamento

Troubleshooting¶

Problema	Causa	Solução
"Justificativa muito curta"	Menos de 15 caracteres	Aumentar texto de `l10n_br_motivo`
Cancelamento fora de prazo	Mais de 24h após autorização	Emitir NF-e de estorno/devolução
CCe rejeitada	Tentou alterar campo não permitido	Verificar texto de correção
NFS-e não cancela	Handle inválido ou município não suporta	Verificar `l10n_br_nfse_handle`
Status `excecao_cancelado`	SEFAZ rejeitou cancelamento	Verificar motivo no chatter
XML/DANFE não gerado	Integrador offline	Retry via botão `Gerar XML/DANFE`

Referências¶

NF-e TX2: NF-e Geração TX2
NFS-e TX2: NFS-e Geração TX2
Wiki principal: Notas Fiscais
Índice: Sumário Geral