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, o caminho certo
O mesmo endpoint emite pelo sistema da prefeitura (São Paulo, Bertioga e Itupeva) ou pelo padrão 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.
Emitir, cancelar e consultar
A chave da empresa emite e cancela NFS-e, lista as notas para conciliação, baixa o PDF e recebe webhooks. É a mesma infraestrutura usada pelo painel e pelo WhatsApp.
Clínicas, consultorias e plataformas
Uma clínica emite ao receber a consulta; uma consultoria emite as faturas do mês de uma vez. Um SaaS que emite em nome dos clientes usa a API para plataformas, por acordo comercial.
Como integrar a API de NFS-e
Pegue suas credenciais. Chave de API incluída no plano Negócio. Você cria a conta, cadastra a empresa com o certificado A1 e gera a chave em Configurações → Integrações.
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 o número da nota; o PDF sai por uma rota própria, e você acompanha o status pela API ou por webhook. Para o contador, as notas e os XMLs são exportados pelo painel.
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/tenant/nfse
Authorization: Bearer np_live_xxxxxxxx
Idempotency-Key: fatura-2026-10-0042
Content-Type: application/json
{
"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 da empresa (
np_live_…) só acessa a própria empresa. Há também a opção só de leitura, para assistentes de IA e planilhas. - Nota real desde a primeira chamada. A chave da empresa não tem ambiente de testes: toda emissão bem-sucedida é uma nota fiscal real e conta na cota do plano.
- 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.failedenfse.cancelled, 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
Em quais cidades a API emite?
A emissão está em produção em São Paulo, Bertioga e Itupeva. Nas demais cidades, a Nota Plena está pronta para as 2.886 cidades do padrão nacional. A rota de prontidão da API (readiness) diz se a sua empresa já pode emitir.
Tem ambiente de testes?
Não para a chave da empresa: a empresa já está em produção, e toda emissão bem-sucedida é uma nota fiscal real. Teste com um serviço de verdade ou cancele a nota em seguida.
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?
Chave de API incluída no plano Negócio. Os detalhes de cada plano estão na página de preços. Para emitir em nome dos seus clientes, fale com o nosso time comercial sobre a API para plataformas.
A API se integra ao sistema do meu contador?
Não há integração direta com sistemas contábeis. O contador recebe as notas e os XMLs do período, exportados pelo painel da Nota Plena.
Dá para emitir nota fiscal com o ChatGPT ou outro assistente de IA?
Dá. Com a chave da própria empresa, o assistente emite, lista e cancela as notas, sempre pedindo sua confirmação antes de emitir. Prompt pronto e passo a passo em /nfse/ia.
Onde vejo os endpoints e exemplos?
Na documentação, em /docs/api: autenticação, emissão e cancelamento de NFS-e, lista de notas, PDF, link de visualização, webhooks e erros.