Pular para o conteúdo principal

Introdução à REST API NFe.io

Bem-vindo à documentação da API REST da NFe.io. Aqui você encontra como autenticar, consumir endpoints, lidar com erros, aplicar boas práticas de segurança e acelerar sua integração para emissão, consulta e gestão de documentos fiscais e dados cadastrais.

Visão Geral​

A API oferece serviços para:

  • Emissão e gestão de NF-e, NFC-e e NFS-e
  • Cálculo de tributos
  • Consulta de CNPJ, CPF, CT-e, endereços e distribuição de NF-e
  • Webhooks para eventos assíncronos
  • Gestão de certificados digitais (via plataforma)

Baseada em HTTP + JSON, seguindo princípios REST, versionada por caminho (ex: /v1/, /v2/).

Base URLs Disponíveis​

Abaixo estão listadas as URLs base disponíveis para integração com as APIs:

  • Nota Fiscal de Produto: https://api.nfse.io/

  • Consulta de Notas Fiscais: https://nfe.api.nfe.io

  • Nota Fiscal de Serviço (RTC): https://api.nfe.io

  • Nota Fiscal de Produto/Consumidor (RTC): https://api.nfse.io/

  • Nota Fiscal de Serviço (Webhooks): https://api.nfse.io

  • Nota Fiscal de Produto: https://api.nfse.io/

    • API para emissão de Notas Fiscais de Produto (NFe/NFCe), seguindo os padrões estabelecidos pelo Governo.
    • Suporta autenticação via API Key e oferece endpoints para consulta e emissão de documentos fiscais.

  • Consulta de Notas Fiscais: https://nfe.api.nfe.io

    • Permite consultar notas fiscais diretamente na SEFAZ utilizando a chave de acesso.
    • Ideal para verificar a validade e detalhes de documentos fiscais emitidos.

  • Nota Fiscal de Serviço (RTC): https://api.nfe.io

    • API para envio de dados de RPS/DPS para emissão de NFS-e, alinhada com padrões nacionais e municipais.
    • Inclui suporte para integração com prefeituras e adequação ao leiaute ABRASF.

  • Nota Fiscal de Produto/Consumidor (RTC): https://api.nfse.io/

    • API para emissão de Notas Fiscais de Produto e Consumidor, com suporte à legislação vigente.
    • Inclui funcionalidades para adequação ao modelo 55 e 65.

  • Nota Fiscal de Serviço (Webhooks): https://api.nfse.io

    • Suporta a criação de webhooks para notificações de eventos relacionados a NFS-e.
    • Permite configurar URLs responsivas para receber notificações em tempo real.

Autenticação​

Você possui DUAS chaves de API diferentes

A NFE.io fornece duas chaves distintas com propósitos específicos:

  • 🔍 Chave de Dados → Para consultas (CNPJ, CPF, CEP, notas emitidas)

    • Base URLs: *.api.nfe.io (ex: legalentity.api.nfe.io, nfe.api.nfe.io)

  • 📝 Chave de Nota Fiscal → Para emissão de notas e gerenciamento

    • Base URLs: api.nfe.io/*, api.nfse.io/*

Usar a chave errada resultará em erro 401. Consulte Chaves de Autenticação para entender melhor quando usar cada uma.

A API suporta 2 métodos de autenticação.

  1. API Key via Header Authorization
  2. JWT Bearer Token
dica

Recomendamos usar API Key via Header Authorization para máxima compatibilidade.

1. API Key via Header Authorization​

Envie sua chave no cabeçalho HTTP Authorization:

Exemplo curl:

curl -X GET https://api.nfe.io/v2/companies \
  -H "Authorization: $NFEIO_API_KEY"

Exemplo Node.js:

const API_KEY = process.env.NFEIO_API_KEY;
const resp = await fetch("https://api.nfe.io/v2/companies", {
  headers: {
    "Authorization": API_KEY
  }
});

2. JWT Bearer Token​

Para integrações avançadas e fluxos com escopos específicos:

Authorization: Bearer SEU_JWT_TOKEN

Exemplo curl:

curl -X GET https://api.nfe.io/v2/companies \
  -H "Authorization: Bearer $JWT_TOKEN"

Exemplo Node.js:

const JWT_TOKEN = process.env.NFEIO_JWT_TOKEN;
const resp = await fetch("https://api.nfe.io/v2/companies", {
  headers: {
    "Authorization": `Bearer ${JWT_TOKEN}`
  }
});
info

Nota: Consulte Chaves de Autenticação para obter mais detalhes sobre geração de chaves e tokens JWT.

Boas Práticas de Segurança​

  • ✅ Não exponha chaves em código-fonte ou repositórios git
  • ✅ Armazene chaves em variáveis de ambiente ou gerenciadores de secrets
  • ✅ Rotacione chaves periodicamente se suspeitar de vazamento
  • ✅ Use HTTPS em todas as requisições
  • ✅ Use sempre o header Authorization (mais seguro que query param)

Versionamento​

  • Versão no path: /v1/, /v2/
  • Quebras de compatibilidade geram nova versão
  • Deprecações terão aviso prévio

Exemplos:

GET /v1/cnpj/{numero}
GET /v2/nota-fiscal/{id}

Formatos e Convenções​

  • Content-Type: application/json
  • Datas: ISO 8601 UTC (2024-03-18T14:25:13Z)
  • Valores monetários: número decimal com ponto (1234.56)
  • Identificadores: UUID ou numéricos conforme recurso
  • Campos opcionais podem ser omitidos (evite enviar null sem necessidade)

Rate Limiting​

Se excedido:

429 Too Many Requests
Retry-After: <segundos>

Implemente backoff exponencial + jitter.

Códigos HTTP Principais​

  • 200 Sucesso
  • 201 Criado
  • 202 Aceito (processamento assíncrono)
  • 400 Erro de validação/sintaxe
  • 401 Falha na autenticação
  • 403 Sem permissão
  • 404 Não encontrado
  • 409 Conflito (estado / duplicado)
  • 422 Erro semântico
  • 429 Limitado
  • 500 Erro interno
  • 503 Indisponível temporário

Estrutura de Erro (exemplo)​

{
  "error": {
    "code": "validation_error",
    "message": "CNPJ inválido",
    "details": [
      { "field": "cnpj", "message": "Formato incorreto" }
    ],
    "requestId": "baf3e0e9e55d4f0c"
  }
}

Guarde requestId em logs para suporte.

Segurança​

  1. Armazene chaves em variáveis de ambiente
  2. Use somente HTTPS
  3. Valide assinatura/origem de webhooks (../documentacao/conceitos/webhook)
  4. Aplique princípio de menor privilégio internamente
  5. Não logue dados sensíveis (ex: CPF completo) em texto puro

Observabilidade Recomendada​

Registre por requisição:

  • Timestamp
  • Método + caminho
  • Status
  • Latência (ms)
  • requestId
  • Referência interna da conta/chave (não a própria chave completa)

Exemplo Rápido (curl)​

curl -X POST https://api.nfe.io/v2/nota-fiscal \
  -H "Authorization: $NFEIO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "cliente": { "cpf": "12345678901", "nome": "Consumidor" },
    "itens": [
      { "descricao": "Produto A", "quantidade": 1, "valorUnitario": 100.00 }
    ]
  }'

Exemplo Node.js (fetch nativo Node 18+)​

const API_KEY = process.env.NFEIO_API_KEY;

async function emitirNota() {
  const resp = await fetch("https://api.nfe.io/v2/nota-fiscal", {
    method: "POST",
    headers: {
      "Authorization": API_KEY,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID()
    },
    body: JSON.stringify({
      cliente: { cpf: "12345678901", nome: "Consumidor" },
      itens: [{ descricao: "Produto A", quantidade: 1, valorUnitario: 100.0 }]
    })
  });

  const data = await resp.json().catch(() => ({}));
  if (!resp.ok) {
    throw new Error(`Falha ${resp.status}: ${JSON.stringify(data)}`);
  }
  return data;
}

emitirNota()
  .then(n => console.log("Nota criada:", n.id))
  .catch(e => console.error(e));

Webhooks​

  • Entregas pelo menos uma vez (trate duplicados)
  • Responda 2xx rapidamente
  • Re-tentativas podem ocorrer
  • Valide autenticidade antes de processar

Veja Conceitos de Webhook.

Certificados Digitais​

Necessários para NF-e / NFC-e / NFS-e. Faça upload e monitore validade em: Upload do Certificado Digital.

Fluxos Assíncronos​

Algumas emissões retornam 202 e seguem processamento interno. Consulte status posteriormente ou aguarde webhook de autorização/cancelamento.

Boas Práticas de Resiliência​

  • Timeouts de cliente (ex: 30s leitura, 5s conexão)
  • Retry apenas em erros transitórios (429, 503, timeouts)
  • Circuit breaker para evitar cascata de falhas
  • Idempotência em criação de documentos

Próximos Passos​

  1. Chaves: Chaves de Autenticação
  2. Cálculo: Cálculo de Impostos V1
  3. Consulta CNPJ: Consulta de CNPJ V1
  4. Consulta CPF: Consulta de CPF V1
  5. NF-e Produto: Nota Fiscal de Produto V2
  6. NFC-e Consumidor: Nota Fiscal de Consumidor V2
  7. NFS-e Serviço: Nota Fiscal de Serviço V1
  8. Distribuição NF-e: Consulta NF-e Distribuição V1
  9. Webhooks: Conceitos de Webhook

Suporte​

Abra ticket via plataforma e informe:

  • timestamp aproximado,
  • O cabeçalho requestId,
  • endpoint e status.

Você terminou a introdução à REST API da NFe.io! Explore os links acima para aprofundar seu conhecimento e começar a integrar rapidamente.

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.