Documentação da API — Danfe Rápida

Toda requisição deve ser autenticada por uma chave de acesso exclusiva (API Key), gerada na área da conta, em Chaves. Inclua o cabeçalho HTTP x-api-key em todas as chamadas.

Content-Type: application/json
x-api-key: SUA_API_KEY

Ideal quando seu ERP/CRM importa listas volumosas de chaves de acesso. Você envia as chaves, o sistema processa em segundo plano e você consulta o status até concluir.

Passo A — Criar o lote

Corpo da requisição (chaves de acesso de 44 dígitos):

{
  "keyListToProcess": [
    "35250000000000000000550010000000011000000017",
    "35250000000000000000550010000000021000000028"
  ]
}

Resposta de sucesso (201 Created):

{
  "id": 42,
  "userId": "00000000-0000-0000-0000-000000000000",
  "quantity": 2,
  "status": "PENDING",
  "createdAt": "2026-05-27T12:00:00.000Z",
  "updatedAt": "2026-05-27T12:00:00.000Z",
  "message": "Lote criado e em processamento.",
  "queries": { "held": 2, "remaining": 1497 },
  "notice": "Se alguma consulta do lote falhar, ela volta ao seu saldo quando o lote terminar."
}

Passo B — Consultar status dos lotes

O userId é extraído automaticamente da API Key — você não precisa enviá-lo.

Query params: page (padrão 1), limit (padrão 10, máx 100).

Resposta de sucesso (200 OK):

{
  "data": [
    {
      "id": 42,
      "userId": "00000000-0000-0000-0000-000000000000",
      "quantity": 2,
      "status": "FINISHED",
      "documents": [
        {
          "id": 105,
          "accessKey": "35250000000000000000550010000000011000000017",
          "xmlCode": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ...",
          "status": "FOUND"
        }
      ],
      "createdAt": "2026-05-27T12:00:00.000Z",
      "updatedAt": "2026-05-27T12:00:15.000Z"
    }
  ],
  "totalItems": 1,
  "currentPage": 1,
  "itemsPerPage": 10
}

Para consultar uma única nota imediatamente (ex.: cliente insere a chave na tela de vendas do seu sistema). Possui fallbacks inteligentes para entregar a nota o mais rápido possível.

Resposta de sucesso (200 OK):

{
  "xmlCode": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ...",
  "base64Code": "JVBERi0xLjQKJcfsj6y...[PDF em Base64]",
  "accessKey": "35250000000000000000550010000000011000000017"
}

5.1 Gerar PDF a partir de lista de XMLs

Recebe uma lista de XMLs em texto e retorna as DANFEs em PDF (Base64).

{
  "xmls": [
    "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ...>...</nfeProc>",
    "<?xml version=\"1.0\" encoding=\"UTF-8\"?><nfeProc ...>...</nfeProc>"
  ]
}

Resposta (200 OK):

[
  {
    "accessKey": "35250000000000000000550010000000011000000017",
    "danfeBase64": "JVBERi0xLjQKJcfsj6y...[PDF em Base64]"
  }
]

5.2 Gerar PDFs dos documentos de um lote existente

Path param: id — identificador numérico do lote (ex.: 42). Resposta (200 OK):

[
  {
    "accessKey": "35250000000000000000550010000000011000000017",
    "danfeBase64": "JVBERi0xLjQKJcfsj6y...[PDF em Base64]"
  }
]

As chamadas usam o saldo de consultas pré-pagas da conta dona da API Key, compradas via PIX na área da conta. Todas as chaves da conta usam o mesmo saldo.

• GET /documents/b2b/search/:accessKey — 1 consulta quando a nota é entregue. Nota não encontrada, chave inválida ou erro não consomem. O saldo restante vem no campo queriesRemaining da resposta e no header X-Queries-Remaining.
• POST /batchs — retém 1 consulta por chave ou XML ao criar o lote e responde queries.held e queries.remaining. Quando o lote termina, as consultas das notas não entregues voltam ao saldo (queries.refunded na consulta do lote).
• Demais endpoints (XML → PDF, PDFs de um lote, listagens) não consomem consulta.

Sem saldo suficiente, a chamada não é processada e a API responde 402 Payment Required:

{
  "success": false,
  "error": "INSUFFICIENT_QUERIES",
  "message": "Consultas insuficientes: saldo 0, esta requisição consome 1.",
  "saldo": 0,
  "solicitado": 1
}

• 401 Unauthorized — API Key inválida, ou lote pertence a outro usuário.
• 404 Not Found — lote ou recurso não encontrado.
• 400 Bad Request — chave de acesso inválida (deve ter 44 dígitos numéricos).
• 402 Payment Required — saldo de consultas insuficiente (INSUFFICIENT_QUERIES).

Fluxo de criação e monitoramento de lote até FINISHED:

const axios = require('axios');

const API_URL = 'https://api.danferapida.com.br';
const API_KEY = 'SUA_API_KEY';

const api = axios.create({
  baseURL: API_URL,
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': API_KEY,
  },
});

async function integrarNotas() {
  // 1. Enviar lote de chaves
  const { data: lote } = await api.post('/batchs', {
    keyListToProcess: [
      '35250000000000000000550010000000011000000017',
      '35250000000000000000550010000000021000000028',
    ],
  });
  console.log(`Lote #${lote.id} criado. Status: ${lote.status}`);

  // 2. Monitorar até FINISHED
  let finished = false;
  let attempts = 0;
  while (!finished && attempts < 10) {
    attempts++;
    const { data } = await api.get('/batchs', { params: { page: 1, limit: 5 } });
    const current = data.data.find((b) => b.id === lote.id);
    if (current && current.status === 'FINISHED') {
      console.log(`✅ Lote #${lote.id} concluído!`);
      finished = true;
    } else {
      await new Promise((r) => setTimeout(r, 5000));
    }
  }
}

integrarNotas().catch((e) =>
  console.error('Erro:', e.response ? e.response.data : e.message)
);

As API Keys e chaves de acesso usadas nesta página são fictícias. Gere sua chave real na área da conta.