Documentação da API — Integração B2B (CRM / ERP)

1. Visão geral

A API foi projetada para alta escalabilidade de forma segura, disponibilizando dois modos de uso:

Lote (assíncrono) — recomendado para volume: enfileira o processamento sem causar timeouts nas suas conexões HTTP.
Individual síncrono (B2B direto) — uma nota na hora, com fallbacks inteligentes em camadas.

Base URL: https://api.danferapida.com.br

2. Autenticação

Toda requisição deve ser autenticada por uma chave de acesso exclusiva (API Key), gerada no seu painel ao criar a conta. Inclua o cabeçalho HTTP x-api-key em todas as chamadas.

A API Key identifica sua conta e define os limites contratados. Mantenha-a em sigilo nas variáveis de ambiente do seu servidor e nunca a exponha no frontend.

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

3. Fluxo de processamento em lote (assíncrono)

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

POST/batchs

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"
}

Passo B — Consultar status dos lotes

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

GET/batchs?page=1&limit=10

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
}

Monitore o status do lote. Quando mudar de PENDING para FINISHED, todos os documentos foram processados e estão prontos para consumo.

4. Consulta individual síncrona (B2B direta)

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.

GET/documents/b2b/search/:accessKey

Resposta de sucesso (200 OK):

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

O campo base64Code é o PDF da DANFE em Base64. Decodifique no seu sistema para renderizar em tela ou salvar como .pdf.

5. Lote avançado (XML → PDF e DANFEs de um lote)

5.1 Gerar PDF a partir de lista de XMLs

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

POST/batchs/xml-to-pdf

{
  "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

GET/batchs/:id/danfes

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

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

Se o lote não pertencer ao detentor da API Key, retorna 401 Unauthorized. Lote inexistente retorna 404 Not Found.

6. Tabela de status

Objeto	Status	Descrição
Lote	`PENDING`	Lote criado. Aguardando processamento em fila.
Lote	`SEARCHING`	Robôs buscando os dados na API externa e SEFAZ.
Lote	`FINISHED`	Processamento concluído para todos os documentos.
Documento	`PENDING`	Documento enfileirado aguardando busca de XML e PDF.
Documento	`FOUND`	XML e DANFE localizados e processados com sucesso.
Documento	`NOT_FOUND`	Não localizado ou chave de acesso inválida.

7. Erros HTTP

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).

8. Exemplo prático (Node.js / Axios)

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 no painel após criar a conta.

Documentação da API — Danfe Rápida