Com a conta, o emitente, o certificado e a chave prontos, a primeira nota de produto é uma única chamada. Este exemplo vai para homologação, o ambiente de teste, e pode ser repetido quantas vezes quiser.
1. Os cabeçalhos
- X-Chave-Integracao: a sua chave de API (começa com dfapp_).
- Idempotency-Key: um código seu que identifica a venda, por exemplo o número do pedido. É ele que impede nota em dobro (tem um tutorial só sobre isso).
- Content-Type: application/json.
curl -X POST https://erp.datafrontier.com.br/api/v1/nfe \
-H "X-Chave-Integracao: dfapp_SUA_CHAVE" \
-H "Idempotency-Key: pedido-1234" \
-H "Content-Type: application/json" \
-d @nota.json2. O corpo: a nota inteira
O arquivo nota.json leva o destinatário, os itens com os impostos, o frete e o pagamento. Não existe cadastro prévio: o que vai no corpo é o que sai na nota.
{
"ambiente": "homologacao",
"referencia": "pedido-1234",
"naturezaOperacao": "VENDA DE MERCADORIA",
"finalidade": 1,
"consumidorFinal": true,
"presenca": 2,
"destinatario": {
"cpfCnpj": "12345678909",
"nome": "Cliente Exemplo",
"indicadorIE": 9,
"email": "cliente@exemplo.com",
"endereco": {
"logradouro": "Rua A", "numero": "10", "bairro": "Centro",
"codigoMunicipio": "3106200", "municipio": "Belo Horizonte",
"uf": "MG", "cep": "30110000"
}
},
"itens": [{
"codigo": "SKU-1",
"descricao": "Produto exemplo",
"ncm": "39269090",
"cfop": "5102",
"unidade": "UN",
"quantidade": 2,
"valorUnitario": 50.00,
"valorDesconto": 10.00,
"valorFrete": 5.00,
"icms": { "origem": 0, "csosn": "102" },
"pis": { "cst": "99" },
"cofins": { "cst": "99" }
}],
"transporte": { "modalidadeFrete": 0 },
"pagamentos": [{ "forma": "17", "valor": 95.00 }],
"informacoesComplementares": "Pedido 1234"
}Alguns campos que costumam gerar dúvida:
| Campo | No exemplo | Significa |
|---|---|---|
| finalidade | 1 | Nota normal. 2 = complementar, 4 = devolução (com notasReferenciadas). |
| presenca | 2 | Venda pela internet. 1 = presencial. |
| indicadorIE | 9 | Destinatário não contribuinte do ICMS (pessoa física, por exemplo). |
| cfop | 5102 | Venda de mercadoria dentro do estado. Para outro estado, a família 6xxx. |
| csosn | 102 | Empresa do Simples, tributada sem permissão de crédito. |
| modalidadeFrete | 0 | Frete contratado por quem vende. |
| forma (pagamento) | 17 | PIX. |
A API calcula o total da nota: produtos, menos descontos, mais frete, seguro, outras despesas e IPI. No exemplo, 2 × 50,00 − 10,00 + 5,00 = 95,00, e a soma dos pagamentos tem de fechar com esse valor.
3. A resposta
HTTP/1.1 201 Created
{
"id": "0199...",
"tipo": "nfe",
"referencia": "pedido-1234",
"situacao": "autorizada",
"ambiente": "homologacao",
"numero": 42,
"serie": 1,
"chave": "3126...",
"protocolo": "1312...",
"codigoSefaz": "100",
"mensagem": "[100] Autorizado o uso da NF-e",
"valorTotal": 95.00,
"repetida": false,
"links": {
"self": "/api/v1/nfe/0199...",
"xml": "/api/v1/nfe/0199.../xml",
"pdf": "/api/v1/nfe/0199.../pdf"
}
}Guarde o id e a chave de acesso (os 44 dígitos). O id é o que você usa nas outras rotas da API; a chave é a identidade oficial da nota.
4. Baixar o XML e o PDF
curl https://erp.datafrontier.com.br/api/v1/nfe/ID_DA_NOTA/xml -H "X-Chave-Integracao: dfapp_SUA_CHAVE" -o nota.xml
curl https://erp.datafrontier.com.br/api/v1/nfe/ID_DA_NOTA/pdf -H "X-Chave-Integracao: dfapp_SUA_CHAVE" -o danfe.pdfO XML é o documento que vale perante a lei; o PDF (DANFE) é só a representação impressa. Mande os dois ao cliente, e guarde o XML.
Se voltar erro
Campo inválido volta com 422 e a lista do que corrigir, com o caminho exato, como "itens[0].ncm: 8 dígitos.". Nada foi enviado à Sefaz nesse caso, e você pode mandar de novo com a mesma Idempotency-Key. Se quem recusou foi a Sefaz, o motivo dela vem inteiro na resposta.
Conhecer a API de nota fiscal Documentação completa
Tutorial escrito pela equipe da API em 29 de setembro de 2026, conferido com a versão v1 no ar. Regra fiscal muda: o enquadramento de imposto da sua empresa é com o seu contador. Viu algo desatualizado? Fale com a gente pelo WhatsApp.