NF-e 55 · NFC-e 65 · leiaute 4.00 com IBS/CBS

Nota fiscal direto na SEFAZ, por uma API que explica o que deu errado

Envie JSON, receba a nota autorizada. Teste em simulação sem certificado e vá para produção trocando só a chave.

Criar conta e emitir a primeira nota Ver a referência da API

POST /api/v1/nfe?aguardar=20

$ curl https://SEU-DOMINIO/api/v1/nfe?aguardar=20 \
    -H "Authorization: Bearer mn_sim_••••" \
    -d @pedido.json
HTTP/1.1 201 Created · X-Request-Id: req_01jbx4k2
{
  "id": "nfe_01jbx4k2m9q7t3v8w5z6y1r0ac",
  "status": "autorizada",
  "ambiente": "simulacao",
  "ref": "pedido-1001",
  "serie": 1, "numero": 1042,
  "chave": "3526104738291500017255001…",
  "sefaz": { "cstat": "100", "motivo": "Autorizado o uso da NF-e" }
}

O trabalho chato da nota fiscal, resolvido no servidor

Você manda os dados da venda. A MadNotas monta o XML, assina, valida, transmite e guarda — e avisa quando a SEFAZ responde.

Direto na SEFAZ

Conexão própria com cada autorizador (SEFAZ estaduais, SVRS, SVAN e SVC). Sem intermediário entre a sua nota e o protocolo.

Simulação sem certificado

Com a chave mn_sim_ a nota percorre o mesmo caminho e recebe resposta de SEFAZ simulada. Rejeição e timeout sob encomenda.

Validação antes da SEFAZ

CPF/CNPJ, inscrição estadual, NCM, CFOP, CST e totais conferidos antes do envio. Cada erro volta com o caminho do campo no seu JSON.

Contingência automática

SEFAZ fora do ar? NFC-e sai em contingência offline e NF-e vai para o SVC. A transmissão volta sozinha quando o autorizador responde.

Reforma tributária: IBS e CBS

Leiaute da NT 2025.002 com os grupos de IBS e CBS. Envie calcular: true e a API faz as contas e os totais.

Webhooks assinados

Autorizada, rejeitada, cancelada: cada evento chega assinado com HMAC-SHA256, com novas tentativas e reenvio pelo painel.

Rejeição vira instrução, não código de três dígitos

Quando a SEFAZ recusa, a nota fica com status rejeitada e cada erro aponta o campo do seu JSON, o cStat original e o que fazer.

Corrija e reenvie com a mesma ref: a nota sai com o mesmo número.
Mesma ref e mesmo conteúdo devolvem a nota já criada, sem duplicar.
Cada código tem página própria na base de rejeições.

201 Created · status rejeitada

{
  "id": "nfe_01jbx5c7r2d4f6g8h0j2k4m6n8",
  "status": "rejeitada",
  "erros": [{
    "campo": "destinatario.inscricao_estadual",
    "codigo": "sefaz_233",
    "mensagem": "IE do destinatário não cadastrada",
    "sefaz": { "cstat": "233" },
    "dica": "Confira a IE no cadastro do cliente ou
             envie indicador_ie = 9 (não contribuinte).",
    "documentacao": "/desenvolvedores/erros/233"
  }]
}

Da chave de teste à nota de produção

O mesmo código serve para os três ambientes. O que muda é a chave.

Simulação

Chave mn_sim_. Sem certificado e sem SEFAZ: valide o payload, os estados da nota e os webhooks.
Valores mágicos da simulação
Homologação

Chave mn_hom_ e o certificado A1 do emitente. A nota vai à SEFAZ real, sem valor fiscal.
Passar pela homologação
Produção

Chave mn_prod_. Nota com valor fiscal, XML guardado e DANFE pronto para enviar ao cliente.
Enviar o certificado

Feito para quem integra e para quem emite

Software house

Emita em nome dos seus clientes, cada um com o próprio CNPJ.

Cadastre emitente, certificado e CSC pela API.
Chave de API por emitente, com permissões.
Checklist de prontidão antes de ligar a produção.

Empresa que emite as próprias notas

Integre o seu sistema ou emita pelo painel, sem programar.

Lista de notas com XML, DANFE, cancelamento e carta de correção.
Log de cada chamada à API e de cada conversa com a SEFAZ.
Uso do mês e franquia do plano no painel.

Perguntas frequentes

Preciso de certificado digital para testar?

Não. A simulação funciona sem certificado e sem falar com a SEFAZ. O certificado A1 do emitente só entra na homologação e na produção.

Quais documentos a API emite?

NF-e (modelo 55) e NFC-e (modelo 65), com cancelamento, carta de correção (NF-e) e inutilização de numeração. NFS-e e CT-e não fazem parte do serviço.

Quais estados são atendidos?

A simulação cobre as 27 UFs. Homologação e produção são liberadas por UF; a página Status mostra os autorizadores monitorados e como cada um está respondendo.

O que acontece se a SEFAZ cair no meio da emissão?

A nota fica em processando e a MadNotas consulta de novo antes de reenviar, para não gerar duplicidade. Se o autorizador seguir fora, entra a contingência. Veja o guia de contingência.

Como é a cobrança?

Plano mensal com uma franquia de notas de produção. Passou da franquia, cada nota a mais entra numa fatura de ajuste do mês. Simulação e homologação não contam. Detalhes em Preços.

Emita a primeira nota em simulação hoje

O guia de primeiros passos leva da chave de teste ao webhook da nota autorizada.

Criar conta Falar com a gente