Integrar emissão de nota é um projeto que ninguém pediu.
Quem já tentou emitir NFS-e direto sabe onde a tarde vai: cada prefeitura tem um webservice diferente, um certificado para assinar, um XML com regras próprias e uma homologação que se arrasta. Você queria emitir uma nota; acabou mantendo uma integração fiscal para cada município em que seus clientes trabalham.
A API da Nota Plena põe uma camada só na frente disso tudo. Você chama um endpoint com os dados da nota; a Nota Plena escolhe o caminho — sistema municipal ou padrão nacional —, assina com o certificado, usa o código de serviço e a configuração fiscal cadastrados para a empresa, e devolve a nota oficial. A ponte para cada prefeitura já está construída e mantida do nosso lado.
O que a API resolve por você
Uma integração, vários municípios
O mesmo endpoint emite tanto pelo sistema próprio da prefeitura quanto pelo Emissor Nacional. Quem decide o caminho é a Nota Plena, não o seu código.
Certificado e imposto no nosso lado
A assinatura com o certificado A1, o código de serviço e a alíquota de ISS saem da configuração da empresa. A Nota Plena cuida da comunicação, assinatura e retorno da emissão.
Empresas, emissões e status
A API cobre o ciclo: criar empresas, subir certificados, emitir NFS-e, ler emissões e sincronizar o status. É a mesma infraestrutura usada pelo painel e pelo WhatsApp.
Feita para plataformas verticais
ERPs, CRMs e sistemas de nicho — academias, escolas, plataformas de serviço — integram a emissão sem virar uma software house fiscal.
Como integrar a API de NFS-e
Pegue suas credenciais. A API faz parte do plano Negócio. Você cria a conta, cadastra a empresa e gera a chave Bearer para a sua aplicação.
Chame o endpoint de emissão. Envie os dados da nota — tomador, valor, descrição. A Nota Plena escolhe o caminho, assina e emite na prefeitura ou no padrão nacional.
Receba a nota oficial. A resposta traz número, PDF e XML oficiais, e você acompanha o status pela própria API ou por webhook. Sua aplicação passa a emitir sozinha.
Uma chamada emite a nota
Autenticação por chave Bearer, corpo JSON, resposta síncrona com o número da nota. O header Idempotency-Key torna o retry seguro sem duplicar a nota.
POST /api/v1/integrations/nfse
Authorization: Bearer np_live_...
Idempotency-Key: cobranca-93271
Content-Type: application/json
{
"np_tenant_id": "9c1fa402-3c29-4bbb-9210-baf4cc2a4231",
"valor_servicos": "650.00",
"discriminacao": "Consultoria — pacote 4 sessões",
"codigo_servico": "10.05",
"tomador_nome": "Ana Maria Pereira",
"tomador_documento": "12345678901"
}
→ 200 OK
{
"emission_id": "9c1fa402-…",
"status": "success",
"numero_nfse": "1023",
"codigo_verificacao": "NMTBGWKL",
"error_message": null
}- Autenticação Bearer. A chave é escopada: uma chave de parceiro só acessa as empresas que ela mesma criou.
- Sandbox por padrão. Empresas nascem em modo sandbox — a emissão devolve um número sintético (prefixo
SANDBOX-) sem tocar a prefeitura, e a primeira emissão sandbox bem-sucedida libera a virada para produção. - Idempotência. Reenviar a mesma
Idempotency-Keydevolve a emissão original em vez de emitir de novo — use uma referência única do seu sistema. - Webhooks assinados.
nfse.emitted,nfse.failed,nfse.cancelledecert.expiring_30d, com assinatura HMAC-SHA256. - Erros claros. 402 (cobrança), 429 (limite de 120 req/min por chave), 503 (prefeitura fora do ar — retriable) e 422 (validação), todos com o motivo em português.
Perguntas frequentes
Tem ambiente de testes (sandbox)?
Tem. Toda empresa nasce em modo sandbox: a emissão devolve um número sintético (prefixo SANDBOX-) sem tocar a prefeitura, para você validar o fluxo do seu lado. A primeira emissão sandbox bem-sucedida libera a virada para produção.
Como a API evita notas duplicadas?
Pelo header Idempotency-Key. Reenviar a mesma chave para a mesma empresa devolve a emissão original em vez de emitir de novo — use uma referência única do seu sistema, como o ID da cobrança. Assim o retry vira seguro.
A emissão é síncrona ou por webhook?
As duas. A chamada de emissão responde na hora com o status e o número da nota; e há webhooks (nfse.emitted, nfse.failed, nfse.cancelled) assinados por HMAC-SHA256 para você acompanhar de forma assíncrona.
Quais erros a minha integração precisa tratar?
Os principais: 402 (emissão bloqueada por cobrança), 429 (limite de 120 requisições por minuto por chave), 503 (prefeitura fora do ar — o pedido está certo, dá para reenviar) e 422 (validação). Cada resposta traz o motivo em português no campo detail.
A API está em qual plano?
A emissão programática faz parte do plano Negócio. Os detalhes de limite e preço estão na página de preços.
Onde vejo os endpoints e exemplos?
Na documentação, em /docs/api: autenticação, empresas, certificados A1, emissão de NFS-e, leitura de emissões, webhooks, sincronização de status e catálogo de planos.