A Stripe é a plataforma de pagamentos e faturamento recorrente mais adotada por SaaS, plataformas digitais e startups globais. No entanto, por ser uma solução internacional, a Stripe não emite notas fiscais de serviço brasileiras (NFS-e).
No Brasil, qualquer venda de serviço ou assinatura cobrada de pessoas físicas ou jurídicas exige a emissão da NFS-e correspondente para cumprimento das normas tributárias da Receita Federal e municípios. Fazer esse processo manualmente a cada renovação mensal ou novo checkout é inviável e gera graves passivos contábeis.
Neste tutorial prático, você aprenderá a construir um fluxo 100% automatizado: quando uma fatura for paga na Stripe (invoice.payment_succeeded ou checkout.session.completed), seu backend recebe o webhook e dispara a emissão da nota fiscal através da API REST da Notaas.
🔄 Fluxo de Arquitetura da Solução
💳 Pipeline Stripe + Notaas via Webhooks:
- 1. Cliente: Assina seu plano ou realiza pagamento no Stripe Checkout.
- 2. Stripe Engine: Processa o cartão/PIX e dispara o evento
invoice.payment_succeeded.- 3. Seu Backend: Valida a assinatura do webhook da Stripe, extrai o CPF/CNPJ e chama a Notaas (
POST /api/v1/emitir).- 4. Notaas Engine: Valida dados, assina digitalmente com certificado A1 e transmite para a prefeitura ou Sistema Nacional.
- 5. Webhook Notaas: Seu backend recebe a confirmação final com links de PDF (DANFSe) e XML e os envia ao cliente.
⚙️ Coleta de CPF/CNPJ e Endereço no Stripe Checkout
Para emitir uma NFS-e válida no Brasil, você precisa obrigatoriamente do CPF ou CNPJ do tomador e, preferencialmente, do CEP e município. Na Stripe, você pode habilitar a coleta de dados fiscais de duas formas:
- Stripe Tax IDs: Ative a opção
tax_id_collection: { enabled: true }na criação da Stripe Checkout Session. - Custom Fields ou Metadata: Adicione um campo personalizado no checkout ou salve o CPF/CNPJ no objeto
Customer.metadata.cpfCnpj.
💻 Implementação da Rota de Webhook em Next.js (App Router)
Crie o endpoint seguro que receberá os eventos da Stripe e acionará a Notaas:
// app/api/webhooks/stripe/route.ts
import { NextRequest, NextResponse } from "next/server";
import Stripe from "stripe";
import axios from "axios";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
apiVersion: "2024-06-20" as any,
});
export async function POST(req: NextRequest) {
const signature = req.headers.get("stripe-signature");
const rawBody = await req.text();
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(
rawBody,
signature!,
process.env.STRIPE_WEBHOOK_SECRET!
);
} catch (err: any) {
console.error("Assinatura de Webhook Stripe inválida:", err.message);
return NextResponse.json({ error: "Webhook signature failed" }, { status: 400 });
}
if (event.type === "invoice.payment_succeeded") {
const invoice = event.data.object as Stripe.Invoice;
const customer = (await stripe.customers.retrieve(invoice.customer as string)) as Stripe.Customer;
// Recupera CPF/CNPJ da metadata ou tax_ids
const cpfCnpj =
customer.metadata?.cpfCnpj ||
(customer.tax_ids?.data?.[0]?.value ?? "00000000000");
const valorEmReais = (invoice.amount_paid || 0) / 100;
try {
// Dispara a emissão da NFS-e na Notaas
const response = await axios.post(
"https://platform.notaas.com.br/api/v1/emitir",
{
tipo: "nfse",
ambiente: process.env.NODE_ENV === "production" ? "producao" : "sandbox",
referencia: `stripe_${invoice.id}`,
prestador: {
cnpj: process.env.EMPRESA_CNPJ!,
},
tomador: {
cpfCnpj: cpfCnpj.replace(/\D/g, ""),
razaoSocial: customer.name || "Cliente Assinante",
email: customer.email,
},
servico: {
codigoTributacaoNacional: "010701",
discriminacao: `Assinatura de Software - Fatura ${invoice.number || invoice.id}`,
valorServicos: valorEmReais,
aliquota: 2.0,
},
},
{
headers: {
"Content-Type": "application/json",
"X-API-Key": process.env.NOTAAS_API_KEY!,
},
timeout: 10000,
}
);
console.log(`[Notaas] NFS-e enfileirada: ID ${response.data.id}`);
} catch (apiError: any) {
console.error("[Notaas] Erro ao emitir NFS-e:", apiError.response?.data || apiError.message);
// Retornar 500 para a Stripe tentar o webhook novamente, se desejado
}
}
return NextResponse.json({ received: true });
}
❓ Perguntas Frequentes (FAQ)
E se minha cobrança for em Dólar (USD)?
Se a sua empresa brasileira emite faturas em moeda estrangeira através da Stripe, a NFS-e nacional deve ser emitida em Reais (BRL) convertidos pela taxa PTAX do Banco Central na data do fato gerador. Seu backend calcula o valor em BRL e envia no campo valorServicos.
A Notaas oferece ambiente de testes para simular a Stripe?
Sim. A Notaas oferece ambiente Sandbox ilimitado com webhooks reais, permitindo que você valide todo o fluxo com cartões de teste da Stripe antes de ir para 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.
🚀 Conecte sua Conta Stripe à Notaas
Automatize 100% das notas fiscais dos seus clientes Stripe com o melhor plano do mercado:
- 🎁 50 notas fiscais gratuitas por mês em produção real.
- ⚡ Webhooks assíncronos e idempotência automática.
- 📄 Geração instantânea de DANFSe v2.0 em PDF.
👉 Criar Conta Gratuita na Notaas Platform
👉 Guia Técnico Completo de Integração