Pular para o conteúdo principal

Acessar chave de autenticação na plataforma

Para utilizar as APIs oferecidas pela NFE.io você precisará usar as chaves de autenticação disponibilizadas no momento da criação da conta.

Resumo Rápido

Existem DUAS chaves diferentes com propósitos específicos:

  • Chave de Dados → Para consultar informações (CNPJ, CPF, CEP, notas emitidas)
  • Chave de Nota Fiscal → Para emitir notas fiscais e gerenciar empresas

Regra simples: Precisa consultar dados? Use a Chave de Dados. Precisa emitir nota fiscal? Use a Chave de Nota Fiscal.

Ao final desse tutorial, você será capaz de:

Requisitos
Criar uma conta

1) Menu conta​

1- Clique no menu CONTA e aparecerá todas as chaves disponíveis.

2- Clique na opção CHAVE DE ACESSO

2) Chaves disponíveis​

Nesta tela, você verá duas chaves diferentes:

Atenção

Cada chave tem uma finalidade específica. Usar a chave errada resultará em erro 401 (Não autorizado). Continue lendo para entender quando usar cada uma.

3) Entendendo as duas chaves​

🔍 Chave de Dados (Data Key)​

Propósito: Consultar informações e dados cadastrais.

Esta chave permite que você faça consultas (somente leitura) de:

  • ✅ CNPJ - Dados cadastrais de empresas na Receita Federal
  • ✅ CPF - Status e validação de CPF
  • ✅ CEP - Consulta de endereços
  • ✅ Simples Nacional - Regime tributário de empresas
  • ✅ Notas Fiscais já emitidas - Consultar NFe/NFCe por chave de acesso

Base URLs que usam esta chave:

  • legalentity.api.nfe.io - Consultas de CNPJ
  • naturalperson.api.nfe.io - Consultas de CPF
  • address.api.nfe.io - Consultas de CEP
  • nfe.api.nfe.io - Consultas de notas fiscais

Exemplo de uso:

curl -X GET "https://legalentity.api.nfe.io/v1/legalentities/basicInfo/12345678000195" \
  -H "Authorization: SUA_CHAVE_DE_DADOS"

📝 Chave de Nota Fiscal (Invoice Key)​

Propósito: Emitir e gerenciar notas fiscais.

Esta chave permite que você emita notas e gerencie sua operação fiscal:

  • ✅ Emitir NFS-e - Nota Fiscal de Serviço Eletrônica
  • ✅ Emitir NF-e - Nota Fiscal de Produto Eletrônica (modelo 55)
  • ✅ Emitir NFC-e - Nota Fiscal de Consumidor Eletrônica (modelo 65)
  • ✅ Criar empresas - Cadastrar empresas na plataforma
  • ✅ Gerenciar certificados - Upload de certificados digitais
  • ✅ Cancelar notas - Cancelamento de documentos fiscais
  • ✅ Enviar emails - Envio de PDF/XML para clientes
  • ✅ Webhooks - Configurar notificações de eventos

Base URLs que usam esta chave:

  • api.nfe.io - NFS-e (Nota de Serviço)
  • api.nfse.io - NF-e e NFC-e (Produto e Consumidor)

Exemplo de uso:

curl -X POST "https://api.nfe.io/v2/companies/ID_EMPRESA/serviceinvoices" \
  -H "Authorization: SUA_CHAVE_DE_NOTA_FISCAL" \
  -H "Content-Type: application/json" \
  -d '{"borrower": {...}, "services": [...]}'

4) Quando usar cada chave​

Tabela Comparativa​

Característica🔍 Chave de Dados📝 Chave de Nota Fiscal
PropósitoConsultas (somente leitura)Emissão e gestão fiscal
OperaçõesConsultar CNPJ, CPF, CEP, notasEmitir notas, criar empresas, cancelar
Padrão de URL*.api.nfe.io (subdomínio)api.nfe.io/* ou api.nfse.io/* (caminho)
Tipo de acessoRead-only (GET)Read + Write (GET, POST, PUT, DELETE)
Requer certificado❌ Não✅ Sim (para emissão de notas)
Exemplo de endpointGET legalentity.api.nfe.io/v1/...POST api.nfe.io/v2/companies/.../serviceinvoices

Fluxograma de Decisão​

5) Mapeamento completo de endpoints​

Endpoints que usam 🔍 Chave de Dados​

OperaçãoEndpointDocumentação
Consultar CNPJGET legalentity.api.nfe.io/v1/legalentities/basicInfo/{cnpj}Consulta CNPJ
Consultar CPFGET naturalperson.api.nfe.io/v1/naturalperson/status/{cpf}/{birthDate}Consulta CPF
Consultar CEPGET address.api.nfe.io/v2/addresses/{postalCode}Consulta Endereços
Consultar NF-e por chaveGET nfe.api.nfe.io/v2/productinvoices/{accessKey}Consulta NF-e
Consultar NFC-e por chaveGET nfe.api.nfe.io/v1/consumerinvoices/coupon/{accessKey}Consulta NFC-e

Endpoints que usam 📝 Chave de Nota Fiscal​

OperaçãoEndpointDocumentação
Criar empresaPOST api.nfe.io/v2/companies ou POST api.nfse.io/v2/companiesCriar Empresa
Upload certificadoPOST api.nfe.io/v2/companies/{id}/certificateUpload Certificado
Emitir NFS-ePOST api.nfe.io/v2/companies/{id}/serviceinvoicesNFS-e v1
Emitir NF-ePOST api.nfse.io/v2/companies/{id}/productinvoicesNF-e v2
Emitir NFC-ePOST api.nfse.io/v2/companies/{id}/consumerinvoicesNFC-e v2
Listar NFS-eGET api.nfe.io/v2/companies/{id}/serviceinvoicesNFS-e v1
Cancelar NFS-eDELETE api.nfe.io/v2/companies/{id}/serviceinvoices/{invoiceId}NFS-e v1
Criar webhookPOST api.nfse.io/v2/webhooksWebhooks

6) Erros comuns e soluções​

❌ Erro 401: "API Key da conta não é válida"​

Causa mais comum: Você está usando a chave errada para o endpoint.

Como identificar qual chave usar:

  1. Olhe para a URL base:

    • Se for *.api.nfe.io (com subdomínio) → 🔍 Chave de Dados
    • Se for api.nfe.io/* ou api.nfse.io/* → 📝 Chave de Nota Fiscal

  2. Pergunte-se:

    • "Estou consultando dados?" → 🔍 Chave de Dados
    • "Estou emitindo/criando algo?" → 📝 Chave de Nota Fiscal

Exemplos de erros e soluções:

❌ Erro✅ Solução
Tentando emitir NFS-e com Chave de DadosUse a Chave de Nota Fiscal
Tentando consultar CNPJ com Chave de Nota FiscalUse a Chave de Dados
Tentando criar empresa com Chave de DadosUse a Chave de Nota Fiscal
Tentando consultar nota emitida com Chave de Nota FiscalUse a Chave de Dados (se for consulta por chave de acesso)

Outras verificações de segurança​

  • ✅ Certifique-se de que está usando o cabeçalho correto: Authorization: SUA_CHAVE
  • ✅ Não adicione prefixos como "Bearer" na Chave de API (use apenas para JWT)
  • ✅ Verifique se não há espaços antes ou depois da chave
  • ✅ Confirme que a chave está ativa na plataforma

7) Boas práticas de segurança​

Segurança crítica

NUNCA faça isso:

  • ❌ Commitar chaves no Git/GitHub
  • ❌ Expor chaves em código-fonte público
  • ❌ Compartilhar chaves por email ou chat sem criptografia
  • ❌ Usar a mesma chave em produção e testes (quando possível)
  • ❌ Armazenar chaves em texto plano no frontend

SEMPRE faça isso:

  • ✅ Armazene chaves em variáveis de ambiente (process.env, .env no .gitignore)
  • ✅ Use gerenciadores de secrets (AWS Secrets Manager, Azure Key Vault, etc.)
  • ✅ Rotacione chaves periodicamente ou se suspeitar de vazamento
  • ✅ Use HTTPS em todas as requisições
  • ✅ Limite o acesso às chaves apenas para quem precisa
  • ✅ Monitore o uso das chaves para detectar comportamentos anômalos

Exemplo de uso seguro em Node.js:

// ✅ CORRETO - Usando variável de ambiente
const DATA_API_KEY = process.env.NFEIO_DATA_KEY;
const INVOICE_API_KEY = process.env.NFEIO_INVOICE_KEY;

// Consultar CNPJ
const cnpjResponse = await fetch(
  'https://legalentity.api.nfe.io/v1/legalentities/basicInfo/12345678000195',
  { headers: { 'Authorization': DATA_API_KEY } }
);

// Emitir nota
const invoiceResponse = await fetch(
  'https://api.nfe.io/v2/companies/ID/serviceinvoices',
  {
    method: 'POST',
    headers: {
      'Authorization': INVOICE_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({...})
  }
);

Exemplo de arquivo .env:

# Chaves NFE.io (NÃO commitar este arquivo!)
NFEIO_DATA_KEY=sua-chave-de-dados-aqui
NFEIO_INVOICE_KEY=sua-chave-de-nota-fiscal-aqui

Adicione ao .gitignore:

.env
.env.local
.env.*.local

8) Próximos passos​

Se você vai usar a Chave de Dados:​

  1. Comece com consultas simples:

  2. Consultas avançadas:

Se você vai usar a Chave de Nota Fiscal:​

  1. Configure sua estrutura primeiro:

  2. Emita sua primeira nota:

  3. Gerencie suas notas:

Documentação complementar:​

Dica final

Guarde este marcador! Sempre que tiver dúvida sobre qual chave usar, volte à tabela comparativa ou ao fluxograma de decisão.

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.