Simulação

Com uma chave mn_sim_, a nota passa pela mesma validação, montagem do XML, numeração, webhooks e logs da produção. Só a SEFAZ é trocada por um simulador — que nunca fala com a SEFAZ de verdade.

Esta página trata dos cenários da NF-e e da NFC-e (MadNotas-Simular). Os da NFS-e Nacional (SIM-REJ-E0625, SIM-NAO-CONVENIADO…) estão em NFS-e Nacional › Simulação, e os do DF-e de entrada (normal, cancelada, so_resumo e cancelamento_posterior) em DF-e › Simulação. O Playground do painel (Integração › Playground) emite cada um e mostra a resposta.

O que é igual e o que muda

	Simulação	Homologação e produção
Validação do payload	Completa	Completa
XML, chave de acesso, numeração	Gerados de verdade	Gerados de verdade
Certificado digital	Não precisa	A1 do emitente
Resposta da SEFAZ	Simulada	Real
Webhooks e logs	Iguais	Iguais
Conta na franquia	Não	Só produção

A escolha do simulador vem da chave, nunca de um campo do payload: não existe jeito de uma chave mn_prod_ cair na simulação, nem o contrário.

Valores mágicos

Sem valor mágico, a nota simulada é autorizada na hora. Para forçar outro desfecho, coloque o valor no codigo do primeiro item ou mande o cabeçalho MadNotas-Simular (o cabeçalho vence o código do item). Nenhum cenário deixa a nota em processando por mais de 5 minutos.

Valor	Estados da nota	Webhooks, em ordem	Até o fim
(nenhum) · `SIM-NORMAL`	`processando` → `autorizada` (cStat 100, protocolo de 15 dígitos começando com 9)	`nfe/nfce.autorizada`	na hora
`SIM-DENEGADA`	`processando` → `denegada` (302, irregularidade do destinatário)	`nfe/nfce.denegada`	na hora
`SIM-REJ-110` · `301` · `302` · `303`	`processando` → `denegada`	`nfe/nfce.denegada`	na hora
`SIM-REJ-<cStat>`	`processando` → `rejeitada` com o texto da base de rejeições; `erros[0].campo` aponta o item (no 778, `itens[0].ncm`)	`nfe/nfce.rejeitada`	na hora
`SIM-TIMEOUT`	a resposta se perde; a MadNotas consulta pela chave (um envio só, nunca duplica) → `autorizada`	`nfe/nfce.autorizada`	~5 s
`SIM-LENTO`	recibo (105) → `autorizada`	`nfe/nfce.autorizada`	~15 s
`SIM-DUPLICIDADE` · `SIM-REJ-204`	a SEFAZ acusa duplicidade; a consulta recupera o protocolo → `autorizada`	`nfe/nfce.autorizada`	na hora
`SIM-CONFLITO` · `SIM-REJ-539`	o número já existe com outra chave → renumerada (aviso `renumerada`) → `autorizada` com o número novo	`emitente.numeracao_conflito` → `nfe/nfce.autorizada`	na hora
`SIM-OFFLINE` (NF-e)	sai pelo SVC (tpEmis 6/7) → `autorizada`	`emitente.contingencia_ativada` → `nfe.autorizada` → `emitente.contingencia_encerrada` logo depois da nota	~20 a 50 s
`SIM-OFFLINE` (NFC-e)	a resposta do POST já vem `contingencia` (tpEmis 9, QR off-line, DANFCE imprimível) → `autorizada` depois do atraso	`emitente.contingencia_ativada` → `nfce.contingencia` → `nfce.autorizada` → `emitente.contingencia_encerrada`	atraso + até 1 min
`SIM-OFFLINE-REJ`	como `SIM-OFFLINE`, mas termina `rejeitada` (778). Corrija com `PUT /nfce/{id}`: mesmo número	… → `nfce.contingencia` → `nfce.rejeitada`	atraso + até 1 min
`SIM-REJ-108` · `109`	serviço paralisado só no autorizador normal: NF-e vai ao SVC, NFC-e vai para off-line → `autorizada`. Sem contingência automática, a SEFAZ "volta" na 4ª tentativa	`emitente.contingencia_ativada` → … → autorizada	~20 a 60 s
`SIM-REJ-656`	consumo indevido no lote; na vida real a espera é de 1 h, aqui de 60 s → `autorizada`	`nfe/nfce.autorizada`	~60 s
`SIM-REJ-999`	erro da SEFAZ: incerto, consulta (217), reenvia → `autorizada`	`nfe/nfce.autorizada`	~5 s
`SIM-OFFLINE` sem contingência automática	a SEFAZ "volta" na 4ª tentativa → `autorizada` (tpEmis 1)	`nfe/nfce.autorizada`	~50 s

Tempos medidos na simulação, com a reconsulta automática rodando a cada minuto.

Forçando a rejeição 233 pelo cabeçalho

curl -X POST "$MADNOTAS_URL/nfe?aguardar=20" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "MadNotas-Simular: SIM-REJ-233" \
  -H "Content-Type: application/json" \
  -d @pedido.json

O pedido.json é o exemplo oficial do primeiro passo. O cenário também pode ser escolhido no Playground do painel, em Integração.

Contingência offline da NFC-e, do começo ao fim

Com SIM-OFFLINE, o POST /nfce responde 201 com status: "contingencia" e tipo_emissao: 9, já com o QR Code off-line e o DANFCE pronto para imprimir. Depois de um atraso, a nota é transmitida e vira autorizada (ou rejeitada com 778, no SIM-OFFLINE-REJ).

O atraso vem do cabeçalho MadNotas-Simular-Atraso, em segundos, de 0 a 600 (padrão 60). Fora dessa faixa, a resposta é 422 simular_atraso_invalido. Assim como MadNotas-Simular, ele só vale com chave mn_sim_: com outra chave, a resposta traz o aviso simulacao_ignorada.

Teste rápido: contingência que autoriza em 5 segundos

curl -X POST "$MADNOTAS_URL/nfce" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "MadNotas-Simular: SIM-OFFLINE" \
  -H "MadNotas-Simular-Atraso: 5" \
  -H "Content-Type: application/json" \
  -d @venda.json
# status: "contingencia" → espere 5 segundos

curl "$MADNOTAS_URL/nfce/{id}?aguardar=20" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE"
# status: "autorizada"

Para saber o resultado sem consultar, assine os webhooks nfce.contingencia e nfce.autorizada (ou nfce.rejeitada). A consulta com aguardar segura a resposta por até 25 segundos e, se o atraso já venceu, transmite na hora.

Fora da simulação os valores mágicos são ignorados e a resposta traz um aviso dizendo isso — o código do item segue como código do produto.

O cabeçalho vale só na emissão. MadNotas-Simular e MadNotas-Simular-Atraso são lidos em POST /nfe e POST /nfce. Em cancelamento, carta de correção e inutilização o cabeçalho é ignorado: o evento segue o caminho normal (cancelamento sai 135).

Para rejeitar um evento, ponha SIM-REJ-<cStat> no texto dele: na justificativa do cancelamento ou da inutilização, ou no texto da carta de correção. O evento sai rejeitado com esse cStat e dispara nfe.evento_rejeitado ou nfce.evento_rejeitado; a inutilização rejeitada dispara inutilizacao.rejeitada. Ex.: "justificativa": "SIM-REJ-501 teste de prazo" simula cancelamento fora do prazo.

Carta de correção rejeitada não gasta sequência nem conta no limite de 20 por nota. A exceção é SIM-REJ-573 (Duplicidade de Evento): a SEFAZ já tem o evento, então ele sai registrado (cStat 573, sem protocolo novo), como na SEFAZ real depois de uma resposta perdida. Sem valor mágico, o cancelamento e a carta de correção saem registrado (135) e a inutilização sai homologada (102).

Derrubar uma SEFAZ de mentira

POST /simulacao/sefaz muda a situação de um autorizador simulado por alguns minutos, só para a sua empresa. Assim você testa a contingência ponta a ponta: emissão em contingência, webhook sefaz.status_alterado e transmissão quando ele volta.

POST /simulacao/sefaz

curl -X POST "$MADNOTAS_URL/simulacao/sefaz" \
  -H "Authorization: Bearer $MADNOTAS_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"uf": "RS", "modelo": "65", "estado": "fora", "minutos": 30}'

Campo	Valores
`uf`	Sigla da UF, obrigatório.
`modelo`	`"55"` ou `"65"`; omitido vale para os dois.
`estado`	`fora` (envio não conecta, entra a contingência) · `lento` (respostas assíncronas) · `normal` (restaura na hora: a contingência automática encerra e as NFC-e off-line pendentes são transmitidas já).
`minutos`	Duração, de 1 a 240; padrão 30.

Limites da simulação

O protocolo e a chave de acesso não existem na SEFAZ: não tente consultar no portal nacional.
O DANFE sai com a marca “SEM VALOR FISCAL”.
Notas simuladas não contam na franquia e seguem a retenção de logs do plano.