Como emitir NFS-e pela API sem lidar com XML e certificado
Um roteiro para integrar o seu sistema à Pluma Fiscal: token, criação da nota, idempotência e webhooks.
Integrar diretamente com o Sistema Nacional NFS-e exige montar a DPS no leiaute oficial, assinar o XML e manter conexão com TLS mútuo. A API da Pluma Fiscal concentra essa parte e expõe operações simples em JSON.
1. Gere o token
Na área API e webhooks, um administrador cria um token. Ele aparece uma única vez; guarde-o no seu cofre de segredos e envie no cabeçalho Authorization: Bearer.
2. Crie e emita a nota
Envie POST /api/v1/nfse com a empresa, o serviço (ou os códigos), o tomador e o valor. A resposta traz a situação e, quando autorizada, o número e a chave de acesso.
3. Use o external_id
Informe o identificador do pedido ou da fatura do seu sistema em external_id. Se a sua aplicação repetir a chamada, a Pluma Fiscal devolve a mesma nota, sem emitir em duplicidade.
4. Assine os webhooks
Cadastre uma URL HTTPS para receber nfse.emitida, nfse.rejeitada e nfse.cancelada. Valide a assinatura HMAC-SHA256 antes de processar o evento.
5. Teste em homologação
Deixe a empresa em homologação enquanto integra: as notas de teste não têm validade fiscal e não consomem a franquia.