Integrar com uma API fiscal não precisa ser complicado.
Se você é desenvolvedor, CTO ou apenas alguém que quer entender como funciona a emissão de NFS-e por API, este guia foi feito para você.
Aqui, você vai passar por todo o fluxo essencial:
- gerar uma API Key
- testar a autenticação
- emitir a primeira NFS-e
- visualizar o retorno
- entender os próximos passos para produção
Tudo isso em poucos minutos.
1. Pré-requisitos
Antes de começar, você só precisa ter:
- uma conta na NFE.io
- uma empresa cadastrada no painel
- um certificado digital A1 ativo
curlou Node.js instalado
Com isso pronto, você já consegue integrar sem complicação.
2. Gerando sua API Key
A API Key é a credencial que identifica sua aplicação na NFE.io.
Siga os passos:
- Acesse o painel da NFE.io
- Vá em Configurações → API Keys
- Clique em Criar nova chave
- Copie e guarde — você vai usar nos headers das requisições
3. Teste rápido: verifique se sua API Key funciona
No terminal, execute:
curl -X GET “https://api.nfe.io/v1/companies” \
-H “Authorization: ApiKey SUA_API_KEY_AQUI”
Possíveis resultados:
- 200 OK → sua chave está funcionando
- 401 Unauthorized → chave inválida ou header ausente
Se recebeu o status 200, você já pode emitir sua primeira nota.
4. Emitindo sua primeira NFS-e (4–5 minutos)
Payload mínimo recomendado
Para facilitar, aqui está um exemplo completo e funcional:
Chamando o endpoint via cURL
curl -X POST “https://api.nfe.io/v1/nfse/SEU_ID_DA_EMPRESA” \
-H “Content-Type: application/json” \
-H “Authorization: ApiKey SUA_API_KEY_AQUI” \
-d ‘{
“cityServiceCode”: “101”,
“description”: “Consultoria em tecnologia”,
“servicesAmount”: 150,
“borrower”: {
“federalTaxNumber”: “12345678909”,
“name”: “Cliente Exemplo”,
“email”: “[email protected]”,
“address”: {
“country”: “BRA”,
“postalCode”: “01311000”,
“street”: “Av Paulista”,
“number”: “1000”,
“district”: “Bela Vista”,
“city”: “São Paulo”,
“state”: “SP”
}
}
}’
5. Entendendo o retorno da API
{
“id”: “123456”,
“status”: “processing”,
“companyId”: “SEU_ID_DA_EMPRESA”,
“servicesAmount”: 150,
“borrower”: {
“federalTaxNumber”: “12345678909”,
“name”: “Cliente Exemplo”
}
}
Algumas observações:
- processing significa que a nota foi enviada à prefeitura
- a prefeitura pode demorar alguns segundos para responder
- em breve estará disponível PDF, XML e o status final
6. Consultando a nota emitida
Você pode consultar o status da NFS-e com:
curl -X GET “https://api.nfe.io/v1/nfse/SEU_ID_DA_EMPRESA/ID_DA_NOTA” \
-H “Authorization: ApiKey SUA_API_KEY_AQUI”
7. Próximos passos para produção
Para uma operação fiscal realmente automatizada, considere:
- configurar webhooks
- emitir em múltiplos municípios
- criar filas e retentativas
- integrar dados com seu meio de pagamento/sistema
- tratar erros de prefeitura
- validar padrões fiscais específicos de cada cidade
Com isso, você cobre mais de 80% do fluxo profissional de emissão fiscal.
Conclusão
Você acabou de emitir sua primeira NFS-e usando a API da NFE.io.
Se quiser expandir a integração, explorar outros endpoints ou avançar para produção, recomendamos acessar a documentação completa.
Link: Acesse a documentação oficial da NFE.io
