Pular para o conteúdo principal

Emitindo uma NF-e

POST /v1/nfe/emitir

A estrutura completa do payload está na Referência da API — esta página trata do fluxo e das decisões, não do schema.

Forma da chamada​

{
  "cpf_cnpj": "60772432000142",
  "referencia_externa": "pedido_98231",
  "webhook_url": "https://seu-sistema.com.br/webhooks/conota",
  "nota": {
    "identificacao": { "nNF": 1234, "serie": 1, "natOp": "Venda de mercadoria" },
    "destinatario":  { "CNPJCPF": "11222333000181", "xNome": "Cliente Exemplo Ltda" },
    "produtos":      [ { "cProd": "SKU-1", "xProd": "Produto exemplo", "NCM": "84713012" } ],
    "total":         { "vNF": 1500.00 }
  }
}

Exemplo simplificado: os blocos de imposto, endereço e transporte foram omitidos. Use a Referência para o conjunto real de campos.

Resposta: 202 com job_id — ver Sua primeira emissão.

Confira antes de emitir​

Campo com nome errado é ignorado em silêncio

O conversor repassa chave desconhecida como veio. vlrProd no lugar de vProd gera uma NF-e válida no schema, com o produto a R$ 0,00 — sem um único aviso, e nem a validação do autorizador pega, porque o campo ignorado não chega ao XML.

Existe uma rota para isso, que não consome cota:

POST /v1/nfe/verificar-campos

Ela confere os nomes dos campos e, se você informar cpf_cnpj, roda também a validação contra o schema oficial.

Checklist​

  • Emitente cadastrado e ativo
  • Certificado A1 válido (GET /v1/empresas/certificados)
  • Ambiente correto
  • Série correta
  • Número conferido (GET /v1/empresas/numeracao)
  • CFOP revisado
  • NCM de todos os itens
  • CST/CSOSN coerente com o regime
  • IBS/CBS quando aplicável
  • Totais coerentes com a soma dos itens
  • referencia_externa única
  • Payload passou em verificar-campos

Emissão em dois passos​

Para fluxos com aprovação humana — em especial os conduzidos por agentes de IA — existe a emissão assistida:

POST /v1/nfe/preparar    ->  token + resumo legível  (não emite, não consome cota)
POST /v1/nfe/confirmar   ->  emite

O preparar só devolve token se o payload passar na verificação, aplica um teto de valor por conta e prende a referencia_externa ao token. O confirmar é de uso único: repetir devolve o mesmo job em vez de emitir outra nota.

Existe também POST /v1/nfe/preparar-de, que parte de uma nota que já existe — útil para corrigir uma rejeitada ou copiar uma anterior. Ver Segurança no MCP.

O teto vale só na emissão assistida

POST /v1/nfe/emitir não tem limite de valor: lá o dado vem do ERP do cliente. O teto existe onde uma pessoa aprova um resumo — porque atenção humana falha, e o teto não depende dela.

Última atualização em