Pular para o conteúdo principal

Exemplos Reais do SDK NFE.io v3

Este documento contém exemplos práticos que você pode executar usando suas credenciais do arquivo .env.test.

🚀 Pré-requisitos​

Setup Automático (Recomendado)​

Execute o script de setup interativo:

npm run examples:setup

Este script irá:

  • ✅ Solicitar sua API Key
  • ✅ Configurar environment (production/development)
  • ✅ Criar arquivo .env.test automaticamente
  • ✅ Verificar e fazer build se necessário

Setup Manual​

  1. Configure suas credenciais no arquivo .env.test na raiz do projeto:

    NFE_API_KEY=sua-chave-api-aqui
    NFE_TEST_ENVIRONMENT=development

  2. Instale as dependências (se ainda não fez):

    npm install

  3. Faça o build do projeto:

    npm run build

Teste sua Configuração​

# Testar conexão e credenciais
npm run examples:test

# Ou diretamente
node examples/test-connection.js

🎯 Execução Rápida com Helper Script​

Use o script helper para executar exemplos facilmente:

# Modo interativo - menu de seleção
node examples/run-examples.js

# Executar exemplo específico (1-4)
node examples/run-examples.js 1

# Executar todos em sequência
node examples/run-examples.js all

Benefícios do helper:

  • ✅ Menu interativo com descrições
  • ✅ Execução individual ou em lote
  • ✅ Feedback visual de progresso
  • ✅ Tratamento de erros amigável
  • ✅ Ordem recomendada de execução

📝 Exemplos Disponíveis​

0. test-connection.js - Teste de Conexão ⚡ (COMECE AQUI!)​

Script de diagnóstico que verifica sua configuração:

  • ✅ Valida credenciais do .env.test
  • ✅ Testa conexão com a API
  • ✅ Lista empresas disponíveis
  • ✅ Verifica recursos do SDK
  • ✅ Confirma build do projeto
node examples/test-connection.js

Execute este primeiro para garantir que tudo está configurado corretamente!

1. real-world-invoice.js - Emissão Completa de Nota Fiscal ⭐​

Exemplo mais completo que demonstra todo o fluxo de emissão de nota fiscal:

  • ✅ Buscar empresa configurada
  • ✅ Criar/buscar tomador (pessoa jurídica)
  • ✅ Emitir nota fiscal com polling automático
  • ✅ Enviar nota por email
  • ✅ Baixar PDF e XML da nota
node examples/real-world-invoice.js

Saída esperada: Nota fiscal emitida + PDF e XML salvos localmente

2. real-world-list-invoices.js - Consulta de Notas Fiscais​

Demonstra como listar e consultar notas fiscais existentes:

  • ✅ Listar empresas da conta
  • ✅ Listar notas fiscais com paginação
  • ✅ Consultar detalhes completos de uma nota
  • ✅ Exibir estatísticas (total, valor médio)
node examples/real-world-list-invoices.js

Saída esperada: Lista de notas fiscais + detalhes completos da primeira nota

3. real-world-manage-people.js - Gerenciamento de Clientes​

Demonstra o CRUD completo de pessoas jurídicas e físicas:

  • ✅ Criar pessoa jurídica (empresa cliente)
  • ✅ Criar pessoa física (cliente individual)
  • ✅ Listar pessoas cadastradas
  • ✅ Buscar por CPF/CNPJ
  • ✅ Atualizar dados cadastrais
node examples/real-world-manage-people.js

Saída esperada: Pessoas criadas e listadas + demonstração de busca

4. real-world-webhooks.js - Configuração de Webhooks​

Demonstra como configurar webhooks para receber eventos:

  • ✅ Listar webhooks configurados
  • ✅ Criar novo webhook
  • ✅ Exemplo de código para validar assinatura
  • ✅ Melhores práticas de implementação
node examples/real-world-webhooks.js

Nota: Este exemplo não cria webhook real (precisa de URL HTTPS válida)

🎯 Exemplos de Desenvolvimento​

basic-usage.ts - Exemplo TypeScript Básico​

Demonstra uso do SDK com TypeScript e tipos completos.

basic-usage-esm.js - Exemplo ESM​

Demonstra uso com import ES modules.

basic-usage-cjs.cjs - Exemplo CommonJS​

Demonstra uso com require() para compatibilidade.

all-resources-demo.js - Tour Completo da API​

Demonstra todos os recursos disponíveis no SDK.

jsdoc-intellisense-demo.ts - IntelliSense Demo​

Demonstra autocompletar e tipos do editor.

📖 Ordem Recomendada de Execução​

Se você é iniciante, recomendamos executar nesta ordem:

  1. 🚨 PRIMEIRO: test-connection.js

    • Verificar se tudo está configurado corretamente
    • Testar credenciais e conexão
    • Validar que o projeto foi buildado

  2. Segundo: real-world-list-invoices.js

    • Ver o que já existe na sua conta
    • Familiarizar-se com a estrutura de dados
    • Não cria nada, apenas consulta

  3. Terceiro: real-world-manage-people.js

    • Cadastrar clientes para usar nas notas fiscais
    • Evitar redigitar dados toda vez
    • Cria dados de teste

  4. Quarto: real-world-invoice.js

    • Emitir sua primeira nota fiscal
    • Ver o fluxo completo funcionando
    • ⚠️ Cria nota fiscal real!

  5. Quinto: real-world-webhooks.js

    • Configurar automação (quando tiver servidor)
    • Receber eventos em tempo real
    • Apenas demonstração (não cria webhook real)

🔍 Entendendo os Resultados​

Status de Nota Fiscal​

As notas podem ter diferentes status:

  • issued - Emitida com sucesso
  • processing - Em processamento (assíncrono)
  • error - Erro na emissão
  • cancelled - Cancelada

Processamento Assíncrono​

Algumas prefeituras processam notas de forma assíncrona:

  • Você recebe status HTTP 202 (Accepted)
  • A nota entra em status processing
  • Use createAndWait() para aguardar automaticamente
  • Ou faça polling manual com retrieve()

Arquivos Gerados​

Após executar real-world-invoice.js, você encontrará:

  • nota-fiscal-XXXXX.pdf - PDF da nota fiscal
  • nota-fiscal-XXXXX.xml - XML da nota fiscal

🐛 Troubleshooting​

Erro: "NFE_API_KEY não encontrada"​

✅ Verifique se o arquivo .env.test existe na raiz do projeto ✅ Verifique se a variável NFE_API_KEY está definida corretamente

Erro: "AuthenticationError: Invalid API key"​

✅ Verifique se copiou a chave corretamente do painel NFE.io ✅ Certifique-se de estar usando a chave do environment correto

Erro: "Nenhuma empresa encontrada"​

✅ Acesse o painel NFE.io e crie uma empresa ✅ Configure o certificado digital da empresa ✅ Aguarde aprovação cadastral (pode levar algumas horas)

Erro ao emitir nota: "ValidationError"​

✅ Verifique se todos os campos obrigatórios estão preenchidos ✅ Confira se o cityServiceCode é válido para sua cidade ✅ Certifique-se de que o CNPJ/CPF do tomador é válido

Erro: "Cannot find module '../dist/index.js'"​

✅ Execute npm run build antes de rodar os exemplos ✅ Verifique se a pasta dist/ foi criada

💡 Dicas Pro​

  1. Reutilize clientes cadastrados

    • Cadastre clientes frequentes com manage-people.js
    • Use findByTaxNumber() ao emitir notas

  2. Use polling automático

    • Prefira createAndWait() em vez de create()
    • Evita necessidade de polling manual

  3. Salve os arquivos

    • PDFs e XMLs são salvos automaticamente
    • Organize em pastas por período

  4. Configure webhooks

    • Receba notificações automáticas
    • Sincronize com seu sistema

  5. Trate erros apropriadamente

    • Use try/catch com verificação de statusCode
    • Log detalhes para debugging

📚 Documentação Adicional​

🤝 Precisa de Ajuda?​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.