API de NFS-e Nacional, sem a parte difícil.
Você envia um JSON. A gente assina com o certificado A1, numera sem falhas, conversa com o governo e reenvia quando ele cai.
Emitir é uma chamada.
A emissão é assíncrona: a API responde na hora com a nota "pendente", e você consulta até ela ficar "autorizada".
- Sem nota duplicadaRepita a chamada com a mesma chave de idempotência e recebe a mesma resposta. Seguro em caso de tempo esgotado.
- Erros em portuguêsCada recusa vem com código, mensagem e o campo com problema.
- Leiaute do governo por nossa contaO formato da API não muda quando o governo troca o leiaute da nota.
curl -X POST https://SEU-ENDERECO/api/v1/nfse \
-H "Authorization: Bearer gnf_SEU_TOKEN" \
-H "Idempotency-Key: pedido-1042" \
-H "Content-Type: application/json" \
-d @nota.json
# 202 Accepted
{ "id": "01a15be7-…", "numero": 42, "status": "pendente" } $resposta = Http::withToken('gnf_SEU_TOKEN')
->withHeaders(['Idempotency-Key' => 'pedido-1042'])
->post('https://SEU-ENDERECO/api/v1/nfse', [
'tomador' => ['documento' => '12.345.678/0001-95', 'nome' => 'Cliente Exemplo'],
'servico' => ['descricao' => 'Suporte técnico', 'c_trib_nac' => '010701',
'competencia' => '2026-11-04'],
'valores' => ['valor' => '1500.00', 'iss_retido' => false],
]);
$nota = $resposta->json(); // status "pendente": consulte até "autorizada" const resposta = await fetch('https://SEU-ENDERECO/api/v1/nfse', {
method: 'POST',
headers: {
Authorization: 'Bearer gnf_SEU_TOKEN',
'Idempotency-Key': 'pedido-1042',
'Content-Type': 'application/json',
},
body: JSON.stringify({ tomador, servico, valores }),
});
const nota = await resposta.json(); // { status: "pendente", ... } As rotas.
Base: https://SEU-ENDERECO/api/v1. Autenticação por token, um por empresa, que pode ser revogado. Limite de 120 chamadas por minuto.
| Método | Rota | Para quê |
|---|---|---|
| POST | /nfse | Emitir uma nota (resposta 202, assíncrona) |
| GET | /nfse/{id} | Situação e detalhes, com o motivo se o governo recusar |
| GET | /nfse | Listar por período, situação ou tomador |
| GET | /nfse/{id}/xml | XML autorizado, o documento fiscal |
| GET | /nfse/{id}/pdf | PDF da nota (DANFSe) |
| POST | /nfse/{id}/cancelamento | Cancelar, com motivo e justificativa |
| POST | /lotes | Enviar várias notas num arquivo CSV |
| GET | /lotes/{id} | Acompanhar o lote |
A vida de uma nota.
Consulte a cada 10 a 30 segundos até a nota sair de pendente, processando ou incerta.
pendentena filaprocessandosendo enviada ao governoincertao governo não respondeu; o sistema confirma sozinho antes de reenviarautorizadanota válida, com chave de acessorejeitadao governo recusou; o motivo vem no detalhecanceladacancelamento registrado
Teste antes, na homologação.
Liberamos um acesso no ambiente de testes do governo, onde a nota não tem valor fiscal, e uma coleção do Postman pronta para usar.
Integre sua emissão de nota esta semana.
Conte qual é o seu sistema e quantas notas ele emite por mês. A gente libera o acesso de testes e acompanha a integração.