Integrar a emissão de Nota Fiscal Eletrônica de Produtos (NF-e modelo 55) e a API NFC-e (modelo 65) diretamente no backend de um e-commerce, ERP, frente de caixa (PDV) ou plataforma de vendas sempre foi um desafio repleto de barreiras técnicas: lidar com webservices SOAP estaduais das 27 Secretarias da Fazenda (SEFAZ), assinar lotes XML com certificados digitais ICP-Brasil A1 e decifrar centenas de códigos de rejeição tributária.
Com a evolução das APIs fiscais modernas, hoje é possível automatizar todo o ciclo de vida da NF-e com uma interface REST limpa e padronizada em JSON.
Neste guia técnico, demonstraremos como configurar uma integração completa utilizando o plano gratuito da Notaas — que oferece 50 notas fiscais/mês em produção com validade jurídica e testes ilimitados em Sandbox —, incluindo cálculo de tributos (ICMS, PIS, COFINS, CFOP, NCM), códigos de benefício fiscal (cBenef) e recebimento do DANFE em PDF e XML via Webhooks.
⚙️ A Complexidade da NF-e (Modelo 55) vs SEFAZ Estadual
Diferente da NFS-e (que é de competência municipal), a NF-e de mercadorias é regulamentada nacionalmente pelo CONFAZ e operada pelas SEFAZ estaduais (alguns estados possuem autorizadores próprios como SP, PR, MG, RS, enquanto outros utilizam o SVAN ou SVRS).
📦 Fluxo de Emissão de NF-e (Produtos):
- 1. Sua Aplicação / E-commerce: Dispara a requisição JSON com itens, CFOP e NCM via
POST /api/v1/emitir.- 2. Motor Fiscal Notaas: Valida o schema da SEFAZ, calcula alíquotas e assina o XML em nuvem segura (HSM).
- 3. SEFAZ Estadual: Processa o lote e retorna o protocolo de autorização 100.
- 4. Webhook & CDN: Notificação em tempo real com links públicos para download do DANFE em PDF e do XML autorizado.
Principais Dores de Integrar Direto com a SEFAZ:
- Comunicação SOAP e Envelopes XML: A SEFAZ não aceita REST nem JSON. Toda a mensageria é feita em XML SOAP 1.2 com namespaces rígidos.
- Rejeições Fiscais Críticas:
- Rejeição 204 / 539 (Duplicidade de NF-e): Ocorre quando uma tentativa de reenvio repete a numeração sem controle idempotente de chave.
- Rejeição 938 (Não informada a vBCST): Divergência entre a alíquota e base de cálculo de substituição tributária.
- Rejeição 805 (A NT 2020.006): Incompatibilidade de código de benefício fiscal (
cBenef) com a CST do ICMS exigida por estados como PR, RS e SC.
- Gerenciamento do Certificado Digital A1: Armazenamento seguro de chaves criptográficas
.pfxcom renovação e assinatura em tempo de execução sem travamento de threads.
📌 Operações com Regras Tributárias Especiais: Caso sua aplicação necessite emitir NF-e para segmentos específicos com redução de base de cálculo do ICMS (CST 20 e 70) ou detalhamento do grupo de veículos novos (
veicProd), confira nosso guia técnico: Emissão de NF-e para Veículos Novos e Redução de Base de Cálculo de ICMS.
A Notaas absorve toda essa complexidade: você submete um JSON limpo e a plataforma cuida da validação dos schemas da NT 2024/2025, assinatura, envio assíncrono para a SEFAZ correta e entrega do PDF e XML autorizados.
📦 Payload Completo de Emissão de NF-e (JSON)
Veja a estrutura de um payload JSON pronto para emissão de NF-e de venda de produto através da Notaas:
Endpoint:
POST https://platform.notaas.com.br/api/v1/emitir
Headers:
Content-Type: application/json
X-API-Key: sk_live_sua_chave_secreta
Corpo da Requisição (Payload JSON):
{
"tipo": "nfe",
"ambiente": "producao",
"referencia": "pedido_ecommerce_84920",
"naturezaOperacao": "Venda de mercadoria adquirida de terceiros",
"prestador": {
"cnpj": "12345678000195",
"inscricaoEstadual": "123456789110"
},
"tomador": {
"cpfCnpj": "01234567890",
"razaoSocial": "João da Silva Sauro",
"email": "joao.silva@exemplo.com.br",
"indicadorIe": 9,
"endereco": {
"logradouro": "Rua das Flores",
"numero": "123",
"bairro": "Centro",
"codigoMunicipio": "3550308",
"uf": "SP",
"cep": "01001000"
}
},
"itens": [
{
"codigo": "PROD-001",
"descricao": "Teclado Mecânico RGB Switch Blue",
"ncm": "84716052",
"cfop": "5102",
"unidadeComercial": "UN",
"quantidade": 1,
"valorUnitario": 299.90,
"tributos": {
"icms": {
"origem": 0,
"cst": "102"
},
"pis": {
"cst": "07"
},
"cofins": {
"cst": "07"
}
}
}
],
"pagamento": {
"formas": [
{
"meio": "pix",
"valor": 299.90
}
]
}
}
💻 Integração em Código: Multi-Linguagens
1. Chamada via cURL
curl -X POST https://platform.notaas.com.br/api/v1/emitir -H "Content-Type: application/json" -H "X-API-Key: sk_test_sua_chave_aqui" -d '{
"tipo": "nfe",
"ambiente": "sandbox",
"referencia": "teste_nfe_001",
"naturezaOperacao": "Venda de mercadoria",
"prestador": { "cnpj": "12345678000195" },
"tomador": {
"cpfCnpj": "00000000000191",
"razaoSocial": "Empresa Teste Ltda",
"email": "cliente@teste.com.br",
"indicadorIe": 9
},
"itens": [
{
"codigo": "SKU-99",
"descricao": "Mouse Gamer Óptico USB",
"ncm": "84716053",
"cfop": "5102",
"unidadeComercial": "UN",
"quantidade": 1,
"valorUnitario": 120.00,
"tributos": {
"icms": { "origem": 0, "cst": "102" }
}
}
],
"pagamento": {
"formas": [{ "meio": "cartao_credito", "valor": 120.00 }]
}
}'
2. Integração em TypeScript / Node.js
import axios from "axios";
interface ItemNFe {
codigo: string;
descricao: string;
ncm: string;
cfop: string;
unidadeComercial: string;
quantidade: number;
valorUnitario: number;
tributos: {
icms: { origem: number; cst: string };
pis?: { cst: string };
cofins?: { cst: string };
};
}
interface EmitirNFeParams {
referencia: string;
clienteDoc: string;
clienteNome: string;
clienteEmail: string;
itens: ItemNFe[];
valorTotal: number;
}
export async function emitirNfeProduto(params: EmitirNFeParams) {
const payload = {
tipo: "nfe",
ambiente: process.env.NODE_ENV === "production" ? "producao" : "sandbox",
referencia: params.referencia,
naturezaOperacao: "Venda de mercadoria",
prestador: {
cnpj: process.env.EMPRESA_CNPJ!,
},
tomador: {
cpfCnpj: params.clienteDoc,
razaoSocial: params.clienteNome,
email: params.clienteEmail,
indicadorIe: 9, // Não contribuinte
},
itens: params.itens,
pagamento: {
formas: [{ meio: "pix", valor: params.valorTotal }],
},
};
const response = await axios.post("https://platform.notaas.com.br/api/v1/emitir", payload, {
headers: {
"Content-Type": "application/json",
"X-API-Key": process.env.NOTAAS_API_KEY!,
},
timeout: 12000,
});
return response.data;
}
3. Integração em Python 3
import os
import requests
NOTAAS_KEY = os.getenv("NOTAAS_API_KEY")
ENDPOINT = "https://platform.notaas.com.br/api/v1/emitir"
def emitir_nfe(referencia: str, cliente_cpf: str, cliente_nome: str, valor: float):
payload = {
"tipo": "nfe",
"ambiente": "producao",
"referencia": referencia,
"naturezaOperacao": "Venda de Mercadorias",
"prestador": {"cnpj": "12345678000195"},
"tomador": {
"cpfCnpj": cliente_cpf,
"razaoSocial": cliente_nome,
"indicadorIe": 9
},
"itens": [
{
"codigo": "LIVRO-01",
"descricao": "Livro Arquitetura de Software Moderna",
"ncm": "49019900",
"cfop": "5102",
"unidadeComercial": "UN",
"quantidade": 1,
"valorUnitario": valor,
"tributos": {
"icms": {"origem": 0, "cst": "102"}
}
}
],
"pagamento": {
"formas": [{"meio": "pix", "valor": valor}]
}
}
headers = {
"Content-Type": "application/json",
"X-API-Key": NOTAAS_KEY
}
resp = requests.post(ENDPOINT, json=payload, headers=headers, timeout=15)
resp.raise_for_status()
return resp.json()
🔔 Webhook: Recebendo DANFE PDF e XML da SEFAZ
Como a SEFAZ processa as requisições em lotes assíncronos, a Notaas dispara um evento de webhook assim que a autorização for confirmada (geralmente em 1 a 3 segundos).
Rota no Next.js App Router (app/api/webhooks/nfe/route.ts):
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
export async function POST(req: NextRequest) {
const signature = req.headers.get("x-notaas-signature");
const rawBody = await req.text();
const secret = process.env.NOTAAS_WEBHOOK_SECRET!;
// 1. Validar autenticidade HMAC SHA-256
const computedHash = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
if (!signature || !crypto.timingSafeEqual(Buffer.from(computedHash), Buffer.from(signature))) {
return NextResponse.json({ error: "Assinatura inválida" }, { status: 401 });
}
const event = JSON.parse(rawBody);
// 2. Tratar evento de NF-e autorizada pela SEFAZ
if (event.event === "nfe.issued") {
const { numero, chaveAcesso, pdfUrl, xmlUrl } = event.data;
console.log(`✅ NF-e autorizada pela SEFAZ! Número: ${numero}`);
console.log(`Chave de Acesso (44 dígitos): ${chaveAcesso}`);
console.log(`DANFE PDF: ${pdfUrl}`);
console.log(`XML Autorizado: ${xmlUrl}`);
// Disparar e-mail com anexo ou atualizar status do pedido no ERP
}
return NextResponse.json({ received: true });
}
🏛️ A Reforma Tributária 2026 e a NF-e
A Reforma Tributária do Consumo (Emenda Constitucional 132/2023) altera profundamente a tributação de produtos a partir de 2026. O ICMS e o IPI darão lugar gradualmente ao IBS (estadual/municipal) e à CBS (federal), com o regime não cumulativo pleno ("crédito financeiro").
A Nota Técnica 2025.002 introduz campos opcionais para testes de segregação do IBS e CBS nos arquivos XML da NF-e modelo 55. Integrando via Notaas, sua infraestrutura de software já nasce preparada para a transição tributária, sem que você precise reescrever suas rotinas de faturamento quando a nova alíquota entrar em vigor.
Para quem também emite serviços, confira nosso Guia Definitivo da API NFS-e Nacional e o comparativo completo em Melhores APIs para Emissão Fiscal em 2026.
❓ Perguntas Frequentes (FAQ)
1. O plano gratuito da Notaas permite emitir NF-e em produção?
Sim! Você pode emitir até 50 notas fiscais por mês gratuitamente em ambiente de produção real com validade fiscal na SEFAZ. Além disso, o Sandbox é ilimitado para homologação técnica.
2. É possível emitir NFC-e (Nota de Consumidor) no plano gratuito?
Sim. O mesmo endpoint unificado /api/v1/emitir aceita o tipo "nfce". Para quem precisa emitir cupons fiscais em frentes de caixa de varejo, totens ou checkout rápido com QR Code v2 e contingência offline para a Black Friday, consulte o nosso Guia Completo da API NFC-e (Modelo 65).
3. O que é necessário para começar a emitir em produção?
Você precisará de:
- Uma conta na Notaas Platform.
- Certificado digital ICP-Brasil modelo A1 (
.pfxou.p12). - Inscrição Estadual (IE) ativa e credenciamento na SEFAZ do seu estado para emissão em produção.
📚 Referências Oficiais & Guias Técnicos:
- 🌐 API de Nota Fiscal: Motor unificado para emissão e gestão de NFS-e, NF-e e NFC-e via REST API.
- ⚡ API NFS-e Nacional: Guia prático de integração técnica com o padrão nacional da Receita Federal.
- 📦 API NF-e (Modelo 55): Emissão simplificada de nota fiscal de produto com DANFE em PDF.
- 🛒 API NFC-e (Modelo 65): Automação de cupom fiscal para varejo e PDV com QR Code v2.
- 📄 DANFSe v2.0 em PDF: Geração local de DANFSe e conformidade com a NT-008 sem o visualizador do ADN.
- ⚖️ Comparativo de APIs Fiscais: Análise comparativa entre Notaas, Nuvem Fiscal, Focus NFe e TecnoSpeed.
🚀 Comece a Emitir NF-e via API em Menos de 5 Minutos
Esqueça as dificuldades de conectar servidores SOAP à SEFAZ. Ganhe velocidade e estabilidade com a API fiscal mais moderna do país:
👉 Criar Conta Gratuita na Notaas (50 Notas/Mês Sem Cartão)
👉 Acessar a Documentação Técnica Oficial
👉 Guia para Desenvolvedores: Primeiros Passos com a Notaas