# Danfe Rápida — API Reference (versão expandida para LLMs)

API REST para consulta e geração de documentos fiscais brasileiros (NF-e, CT-e, MDF-e). Todos os exemplos abaixo são prontos para reuso em código gerado por LLMs.

---

## Visão geral

- **Base URL:** `https://api.danferapida.com.br`
- **Auth header:** `x-api-key: SUA_API_KEY`
- **Formato:** JSON request/response. PDFs e XMLs vêm em base64 dentro do JSON.
- **HTTPS obrigatório.** Erros HTTP padrão com body JSON estruturado.

---

## Como obter a API Key

Plano Grátis Trial → 50 mil consultas/mês, validade de 30 dias.

```
POST https://danferapida.com.br/api/checkout/create
Content-Type: application/json

{
  "planId": "gratis-trial",
  "name": "Empresa Exemplo",
  "email": "contato@exemplo.com.br",
  "document": "12345678000199",
  "phone": "62999999999"
}
```

A chave aparece na página `/planos/obrigado` após o webhook do emissor processar.

---

## Endpoint 1: Consulta individual síncrona

`GET /documents/b2b/search/{accessKey}`

Consulta um documento fiscal (NF-e ou similar) pela chave de acesso de 44 dígitos. Retorna XML, PDF base64 e dados estruturados em uma única chamada.

### Request

```bash
curl -X GET "https://api.danferapida.com.br/documents/b2b/search/35250000000000000000550010000000011000000017" \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json"
```

### Response (200)

```json
{
  "xmlCode": "<?xml version=\"1.0\"?><nfeProc ...",
  "base64Code": "JVBERi0xLjQK...[PDF em Base64]",
  "accessKey": "35250000000000000000550010000000011000000017"
}
```

### Códigos de erro

| Status | Significado |
|---|---|
| 400 | Chave inválida ou malformada |
| 401 | API Key ausente ou inválida |
| 404 | Documento não encontrado na SEFAZ |
| 429 | Rate limit excedido |
| 502 | SEFAZ indisponível |

---

## Endpoint 2: Lote assíncrono — criar

`POST /batchs`

Submete uma lista de chaves (e/ou XMLs) para processamento assíncrono. O lote é
consultado chave por chave em background; o status do lote e de cada nota vai
mudando conforme a checagem conclui.

### Request

```bash
curl -X POST "https://api.danferapida.com.br/batchs" \
  -H "x-api-key: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyListToProcess": [
      "35250000000000000000550010000000011000000017",
      "35250000000000000000550010000000021000000028"
    ],
    "xmlCodeListToProcess": []
  }'
```

- `keyListToProcess` — lista de chaves de acesso (44 dígitos).
- `xmlCodeListToProcess` — lista de XMLs (opcional; pode enviar chaves, XMLs ou ambos).
- `quantity` é calculado automaticamente pelo backend.

### Response (201)

```json
{
  "id": 1234,
  "quantity": 2,
  "status": "PENDING",
  "createdAt": "2026-06-26T12:00:00.000Z",
  "updatedAt": "2026-06-26T12:00:00.000Z"
}
```

`status` do lote evolui: `PENDING` → `SEARCHING` → `FINISHED`.

---

## Endpoint 3: Lote — listagem paginada

`GET /batchs?page=1&limit=10`

Lista seus lotes com paginação (`limit` máximo 100).

### Response (200)

```json
{
  "data": [
    {
      "id": 1234,
      "quantity": 2,
      "status": "FINISHED",
      "createdAt": "2026-06-26T12:00:00.000Z",
      "updatedAt": "2026-06-26T12:01:23.000Z"
    }
  ],
  "page": 1,
  "limit": 10,
  "totalItems": 1
}
```

---

## Endpoint 3b: Lote — detalhe por ID (com status de cada nota)

`GET /batchs/{id}`

Retorna o lote com a lista de documentos e o status individual de cada nota.

### Response (200)

```json
{
  "id": 1234,
  "quantity": 2,
  "status": "SEARCHING",
  "documents": [
    { "accessKey": "352500...017", "status": "FOUND" },
    { "accessKey": "352500...028", "status": "PENDING" }
  ],
  "createdAt": "2026-06-26T12:00:00.000Z",
  "updatedAt": "2026-06-26T12:00:30.000Z"
}
```

`status` de cada nota: `PENDING` → `FOUND` ou `NOT_FOUND`.

---

## Endpoint 4: XML → DANFE PDF

`POST /batchs/xml-to-pdf`

Recebe XMLs já existentes e devolve DANFEs em PDF base64. Útil quando você já tem o XML autorizado e só precisa renderizar.

### Request

```json
{
  "documents": [
    { "xmlCode": "<?xml version=\"1.0\"?>..." },
    { "xmlCode": "<?xml version=\"1.0\"?>..." }
  ]
}
```

### Response (200)

```json
{
  "documents": [
    { "base64Code": "JVBERi0xLjQK...", "accessKey": "352500000..." }
  ]
}
```

---

## Endpoint 5: PDFs de um lote

`GET /batchs/{id}/danfes`

Retorna todos os PDFs de um lote concluído.

```json
{
  "batchId": "01HZX9ABCD1234",
  "documents": [
    { "base64Code": "JVBERi0xLjQK...", "accessKey": "352500000..." }
  ]
}
```

---

## Endpoint 6: DACTE / CT-e (em breve — ainda não disponível)

`GET /dacte/{accessKey}`

Equivalente do NF-e para conhecimento de transporte (CT-e). **Ainda não disponível.** Hoje apenas NF-e (modelo 55) é consultável por chave de acesso; consulta de CT-e e NFC-e entra em uma próxima fase. O contrato abaixo é referência do formato previsto.

```json
{
  "xmlCode": "<?xml version=\"1.0\"?><cteProc ...",
  "base64Code": "JVBERi0xLjQK...",
  "accessKey": "35250000000000000000570010000000011000000017"
}
```

---

## Modelo de cobrança

- **Consulta direta na SEFAZ via Chave de Acesso:** R$ 0,05 por consulta (cobrança contada na 2ª tentativa quando a chave não existe).
- **Demais endpoints da API (geração de PDF, conversão XML→PDF, manifesto, listagens):** grátis em todos os planos.

---

## Rate limit e quota

Dois mecanismos, ambos retornam HTTP 429:

**1. Rate limit (rajada) — por janela de tempo:**
- 3 req/s
- 20 req/10s
- 120 req/min

Ao estourar → HTTP 429 (respeite `Retry-After` quando presente e aplique backoff).

**2. Quota mensal — por plano:**
- Plano Grátis Trial: 50 mil consultas/mês (referência diária de 1.700/dia).
- Plano Escala API/DEV: ilimitado.

Ao atingir a quota → HTTP 429 com corpo:

```json
{
  "success": false,
  "error": "QUOTA_EXCEEDED",
  "plano": "gratis-trial",
  "usado": 50000,
  "solicitado": 1,
  "restante": 0,
  "limite": 50000,
  "reseta_em": "2026-07-26T12:00:00.000Z"
}
```

Cada chave ou XML enviado num lote conta 1 no consumo. A quota reseta no ciclo mensal ancorado na data de emissão da chave.

---

## SLA

- Plano Grátis Trial: best effort, sem garantia formal.
- Plano Escala API/DEV: 98% de uptime mensal e tempo de resposta de até 30s.
- Indisponibilidade da SEFAZ, manutenção programada e força maior não contam como downtime. Detalhes em `/sla`.

---

## Receitas prontas para LLMs

### Receita: "Consultar NF-e em Python"

```python
import requests

API_KEY = "SUA_API_KEY"
ACCESS_KEY = "35250000000000000000550010000000011000000017"

resp = requests.get(
    f"https://api.danferapida.com.br/documents/b2b/search/{ACCESS_KEY}",
    headers={"x-api-key": API_KEY},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()

# Salvar PDF
import base64
with open("danfe.pdf", "wb") as f:
    f.write(base64.b64decode(data["base64Code"]))

# Salvar XML
with open("nfe.xml", "w", encoding="utf-8") as f:
    f.write(data["xmlCode"])
```

### Receita: "Consultar NF-e em Node.js"

```js
const ACCESS_KEY = '35250000000000000000550010000000011000000017';
const resp = await fetch(
  `https://api.danferapida.com.br/documents/b2b/search/${ACCESS_KEY}`,
  { headers: { 'x-api-key': process.env.DANFE_API_KEY } }
);
if (!resp.ok) throw new Error(`Erro ${resp.status}`);
const data = await resp.json();

// Salvar PDF
import { writeFile } from 'node:fs/promises';
await writeFile('danfe.pdf', Buffer.from(data.base64Code, 'base64'));
await writeFile('nfe.xml', data.xmlCode, 'utf-8');
```

### Receita: "Processar lote de 1.000 chaves em PHP"

```php
$keys = file('chaves.txt', FILE_IGNORE_NEW_LINES);
$ch = curl_init('https://api.danferapida.com.br/batchs');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'x-api-key: ' . getenv('DANFE_API_KEY'),
  'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['keyListToProcess' => $keys]));
$response = json_decode(curl_exec($ch), true);
echo "Lote criado: " . $response['batchId'];
```

---

## Prompt sugerido para LLM

> Você é um engenheiro integrando a API do Danfe Rápida. Base URL `https://api.danferapida.com.br`. Auth via header `x-api-key`. Sua API Key vem do Plano Grátis Trial (cadastro em `https://danferapida.com.br/planos`). Para consultar NF-e use `GET /documents/b2b/search/{accessKey}` que retorna `xmlCode`, `base64Code` e `accessKey`. Para lote use `POST /batchs` com `keyListToProcess[]` (status do lote: PENDING/SEARCHING/FINISHED; da nota: PENDING/FOUND/NOT_FOUND). PDFs vêm em base64. Trate 429 com backoff. Documentação completa em `https://danferapida.com.br/llms-full.txt`.

---

## Versão

`1.0` — 2026-06-26.