Você tem um ERP, um PDV, um marketplace ou qualquer SaaS e chegou a hora de emitir nota fiscal de dentro dele. Existem dois caminhos: falar direto com a SEFAZ ou usar uma API. Este guia mostra como funciona o segundo — o caminho que a maioria dos desenvolvedores escolhe depois de ver o tamanho do primeiro.
O jeito difícil: falar direto com a SEFAZ
Emitir nota "na unha" significa conversar com web services SOAP de cada Secretaria da Fazenda. Na prática você vai:
- Montar o XML da nota respeitando o esquema XSD oficial, campo por campo;
- Assinar esse XML com o certificado digital da empresa;
- Entender WSDL, namespaces e envelopes SOAP para transmitir;
- Tratar as diferenças das 27 UFs, cada uma com endpoint, versão e detalhe próprio;
- Cuidar de contingência, cancelamento, carta de correção, inutilização e todo o ciclo de vida do documento.
É meses de trabalho antes da primeira nota autorizada — e manutenção eterna, porque a SEFAZ muda regras com frequência.
O jeito prático: uma API REST
Uma API fiscal abstrai tudo isso. Você faz uma requisição REST em JSON e recebe de volta a nota autorizada: o XML e o DANFE em PDF prontos para entregar ao cliente final. Nada de SOAP, XSD ou assinatura manual — a API monta, assina e transmite por você, para qualquer UF.
Se você ainda está decidindo qual documento precisa emitir (NF-e, NFC-e, MDF-e ou CT-e), vale ler antes o guia NF-e, NFC-e, MDF-e ou CT-e: qual emitir.
Integração passo a passo
1. Pegue sua credencial de parceiro
Você recebe uma chave de API — algo como sph_... — com escopos que definem o que ela pode fazer. Essa credencial identifica o seu sistema (o integrador) e é ela que autentica todas as chamadas. Uma só integração serve a sua carteira inteira de clientes.
2. Provisione cada cliente
Para cada CNPJ que vai emitir, você cadastra o emitente e envia o certificado digital do cliente, que fica armazenado criptografado. Para emissão automática por servidor — o caso de qualquer sistema — o certificado adequado é o A1, um arquivo que roda sem token físico nem cartão. Entenda a diferença no guia Certificado A1 ou A3 para emissão de nota.
3. Emita a nota
Com o emitente pronto, você chama o endpoint de emissão, por exemplo POST /emitentes/{id}/nfce/emitir, passando os itens, valores, meios de pagamento e dados do destinatário. A API responde com o status da SEFAZ. Quando vem cStat 100, a nota está autorizada — e você recebe o XML assinado e o DANFE em PDF. O que cada código de retorno significa está detalhado em cStat 100: nota autorizada.
No SoftPay, você integra uma vez e emite para todos os seus clientes: teste grátis com 50 notas sem cartão e, no white-label, a partir de R$ 0,10 por nota, consolidado, sem mensalidade por CNPJ. Ver planos e preços.
Boas práticas que evitam dor de cabeça
Teste em homologação primeiro
Toda API fiscal séria oferece um ambiente de homologação — uma cópia da SEFAZ onde as notas não têm valor fiscal. Rode toda a sua integração ali antes de virar a chave para produção. Assim você valida payloads, trata rejeições e só emite nota de verdade quando tudo estiver redondo.
Use idempotência
Rede falha. Se a sua chamada de emissão cair no timeout mas a SEFAZ tiver autorizado, um retry ingênuo gera nota duplicada — um problema fiscal chato de resolver. A solução é enviar uma idempotencyKey única por emissão: se a mesma chave chegar duas vezes, a API devolve a nota já criada em vez de emitir outra.
Confirme pelos webhooks
A autorização pode não ser instantânea. Em vez de ficar consultando o status em loop, configure webhooks: a API te avisa de forma assíncrona quando a nota é autorizada, rejeitada ou cancelada, e o seu sistema reage a esse evento.
Trate rejeições e reenvio
Nem toda nota passa de primeira. Um CPF inválido, um imposto mal calculado ou um problema de cadastro geram rejeição com um código específico. Seu fluxo precisa ler esse retorno, corrigir o dado e reenviar. Um clássico é o DIFAL em vendas interestaduais, que costuma derrubar nota quando calculado errado.
Deixe a contingência com a API
Quando a SEFAZ sai do ar, a emissão não pode parar. Uma boa API entra em contingência automaticamente e transmite as notas quando o serviço volta — sem você escrever essa lógica. Veja como isso funciona em Contingência de NFC-e quando a SEFAZ está fora do ar.
Por que white-label muda o jogo
Numa API white-label, a nota, o XML e o PDF saem com a sua marca, não com a do fornecedor. Para o seu cliente final, a emissão fiscal é uma funcionalidade nativa do seu sistema. E como uma única integração atende toda a base, você adiciona um diferencial ao produto sem multiplicar o esforço de desenvolvimento a cada novo cliente.
Resumo
Emitir nota por API é trocar meses de trabalho com SOAP e XML por algumas requisições REST. O caminho é: credencial de parceiro, provisionar cada CNPJ com certificado A1, emitir e tratar o retorno da SEFAZ. Faça isso com homologação, idempotência e webhooks desde o início e a emissão fiscal deixa de ser um projeto para virar só mais um recurso do seu sistema.