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​

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

  1. API Key via Header HTTP (Recomendado)
  2. JWT Bearer Token
dica

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

1. API Key via Header HTTP (Recomendado)​

Envie sua chave em um dos cabeçalhos HTTP:

  • X-NFE-APIKEY: (Recomendado)
  • Authorization: (Alternativo)

Exemplo curl:

curl -X GET https://api.nfe.io/v2/companies \
  -H "X-NFE-APIKEY: $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: {
    "X-NFE-APIKEY": 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
  • ✅ Prefira API Key via Header quando possível (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 "X-NFE-APIKEY: $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: {
      "X-NFE-APIKEY": 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.