# EvanBible API — Documentación completa

> API REST gratuita de la Biblia: 55 versiones en 24 idiomas.
> Este documento está pensado para compartirse con asistentes de IA: contiene todo lo
> necesario para consumir el API sin información adicional.

- **Base URL:** `https://evanbible.com/api/v1`
- **Método:** solo `GET`. Respuestas JSON UTF-8 con CORS abierto (`Access-Control-Allow-Origin: *`).
- **Documentación web:** https://evanbible.com · **Biblias disponibles:** https://evanbible.com/bibles.php
- **Versión de esta documentación:** 2.2.1 (generada 2026-09-17)

## Autenticación y límites

La API funciona **sin registro**: 500 peticiones/día por IP.
Con una **API key gratuita** (https://evanbible.com/key.php): 5,000 peticiones/día.

Enviar la key de cualquiera de las dos formas:

```
X-API-Key: TU_KEY          # header (recomendado)
?key=TU_KEY                # parámetro de query
```

Cada respuesta incluye `X-RateLimit-Limit` y `X-RateLimit-Remaining`.
Al exceder el límite: HTTP 429 con `{"ok": false, "error": "..."}`.

## Endpoints

| Método y ruta | Descripción |
|---|---|
| `GET /api/v1/versions` | Lista todas las versiones publicadas |
| `GET /api/v1/{ver}/books` | Los 66 libros de la versión (id, nombre, testamento) |
| `GET /api/v1/{ver}/{libro}` | Info del libro: número de capítulos y versículos |
| `GET /api/v1/{ver}/{libro}/{cap}` | Capítulo completo |
| `GET /api/v1/{ver}/{libro}/{cap}/{vers}` | Un versículo (`16`) o un rango (`16-18`) |
| `GET /api/v1/{ver}/search?q=texto` | Búsqueda de texto (parámetros: `q` mín. 3 chars, `book`, `page`, `limit` máx. 50) |
| `GET /api/v1/{ver}/random` | Versículo aleatorio |
| `GET /api/v1/compare/{libro}/{cap}/{vers}?versions=A,B,C` | El mismo versículo en hasta 8 versiones |

### El parámetro `{ver}`

Código de la versión, sin distinguir mayúsculas: `rv60`, `RV60` y `Rv60` son equivalentes.
La lista completa de códigos está al final de este documento y en `/api/v1/versions`.

### El parámetro `{libro}`

Acepta tres formas equivalentes:

1. **Número canónico** 1–66 (tabla más abajo). Funciona en todas las versiones y es la forma más segura para agentes de IA.
2. **Nombre** en el idioma de la versión: `juan`, `génesis`, `genesis` (acentos opcionales, sin distinguir mayúsculas).
3. **Abreviación** o **prefijo**: `apoc` resuelve a Apocalipsis.

En `compare`, el libro se resuelve contra la primera versión de la lista `versions`;
para mezclar idiomas usa el número canónico.

## Formato de respuestas

Todas las respuestas exitosas incluyen `"ok": true`. Ejemplos reales:

### Versículo — `GET /api/v1/rv60/juan/3/16`

```json
{
  "ok": true,
  "version": "RV60",
  "book": 43,
  "book_name": "Juan",
  "chapter": 3,
  "reference": "Juan 3:16",
  "count": 1,
  "verses": [
    { "verse": 16, "text": "Porque de tal manera amó Dios al mundo..." }
  ]
}
```

Un rango (`/juan/3/16-18`) o un capítulo completo (`/juan/3`) devuelven la misma
estructura con más elementos en `verses`.

### Búsqueda — `GET /api/v1/rv60/search?q=esperanza&limit=2`

```json
{
  "ok": true,
  "version": "RV60",
  "query": "esperanza",
  "total": 141,
  "page": 1,
  "pages": 71,
  "limit": 2,
  "results": [
    {
      "book": 8, "book_name": "Rut", "chapter": 1, "verse": 12,
      "reference": "Rut 1:12",
      "text": "..."
    }
  ]
}
```

### Aleatorio — `GET /api/v1/rv60/random`

```json
{
  "ok": true, "version": "RV60", "book": 19, "book_name": "Salmos",
  "chapter": 23, "verse": 1, "reference": "Salmos 23:1", "text": "..."
}
```

### Comparación — `GET /api/v1/compare/43/3/16?versions=RV60,KJV`

```json
{
  "ok": true,
  "book": { "id": 43, "name": "Juan" },
  "chapter": 3, "verse": 16, "reference": "Juan 3:16",
  "versions": {
    "RV60": "Porque de tal manera amó Dios al mundo...",
    "KJV": "For God so loved the world..."
  }
}
```

## Errores

| HTTP | Significado |
|---|---|
| 400 | Parámetros inválidos (rango mal formado, `q` muy corta, etc.) |
| 401 | API key inválida |
| 404 | Versión, libro o referencia no encontrada |
| 429 | Límite diario alcanzado |

Formato: `{"ok": false, "error": "mensaje descriptivo"}`.

## Numeración canónica de libros (1–66)

Nombres en español (RV60); la numeración es idéntica en todas las versiones.

| # | Libro | | # | Libro |
|---|---|---|---|---|
| 1 | Génesis | | 34 | Nahúm |
| 2 | Éxodo | | 35 | Habacuc |
| 3 | Levítico | | 36 | Sofonías |
| 4 | Números | | 37 | Hageo |
| 5 | Deuteronomio | | 38 | Zacarías |
| 6 | Josué | | 39 | Malaquías |
| 7 | Jueces | | 40 | Mateo |
| 8 | Rut | | 41 | Marcos |
| 9 | 1 Samuel | | 42 | Lucas |
| 10 | 2 Samuel | | 43 | Juan |
| 11 | 1 Reyes | | 44 | Hechos |
| 12 | 2 Reyes | | 45 | Romanos |
| 13 | 1 Crónicas | | 46 | 1 Corintios |
| 14 | 2 Crónicas | | 47 | 2 Corintios |
| 15 | Esdras | | 48 | Gálatas |
| 16 | Nehemías | | 49 | Efesios |
| 17 | Ester | | 50 | Filipenses |
| 18 | Job | | 51 | Colosenses |
| 19 | Salmos | | 52 | 1 Tesalonicenses |
| 20 | Proverbios | | 53 | 2 Tesalonicenses |
| 21 | Eclesiastés | | 54 | 1 Timoteo |
| 22 | Cantares | | 55 | 2 Timoteo |
| 23 | Isaías | | 56 | Tito |
| 24 | Jeremías | | 57 | Filemón |
| 25 | Lamentaciones | | 58 | Hebreos |
| 26 | Ezequiel | | 59 | Santiago |
| 27 | Daniel | | 60 | 1 Pedro |
| 28 | Oseas | | 61 | 2 Pedro |
| 29 | Joel | | 62 | 1 Juan |
| 30 | Amós | | 63 | 2 Juan |
| 31 | Abdías | | 64 | 3 Juan |
| 32 | Jonás | | 65 | Judas |
| 33 | Miqueas | | 66 | Apocalipsis |

Libros 1–39: Antiguo Testamento · 40–66: Nuevo Testamento.

## Versiones disponibles (55)

**Español:** `BJ` (Biblia de Jerusalén), `BJ2` (Biblia de Jerusalén (2)), `BLA95` (Biblia Latinoamericana 1995), `BLAH` (Biblia Latinoamericana de Hoy), `DHH` (Dios Habla Hoy), `LBLA` (La Biblia de las Américas), `NBJ` (Nueva Biblia de Jerusalén), `NBLA` (Nueva Biblia de los Hispanos), `NBLH` (Nueva Biblia Latinoamericana de Hoy), `NTV` (Nueva Traducción Viviente), `NVIES` (Nueva Versión Internacional), `PDT` (Palabra de Dios para Todos), `RV1909` (Reina Valera 1909), `RV19WS` (Reina Valera 1909 With Strongs), `RVG2010` (Reina Valera Gómez (2010)), `RVR60` (Reina-Valera 1960), `TLA` (Traducción en Lenguaje Actual), `RV60` (Reina Valera 1960)

**Afrikaans:** `AFR` (Afrikaans 1953)

**Albanian:** `ALBN` (Albanian)

**Bengali:** `BEN` (বাংলা)

**Chinese:** `CHUS` (Chinese Union (Simplified))

**Czech:** `BKR` (Bible Kralicka)

**English:** `ASV` (American Standard Version (1901)), `BBE` (Bible in Basic English), `BISHOPS` (Bishops Bible (1568)), `DBY` (Darby English Bible), `ENG` (English American Bible), `ERV` (Easy-to-Read Version), `KJ2000` (King James 2000), `KJV` (King James Version), `MKJV` (Modern King James Version), `WBT` (Webster's Bible), `WEB` (World English Bible (2006)), `YLT` (Young's Literal Translation)

**Greek:** `TIS` (Un-parsed Tischendorf)

**Gujarati:** `GUJ` (ગુજરાતી)

**Hindi:** `HIN` (हिन्दी)

**Indonesian:** `IND` (Alkitab Terjemahan Baru (TB))

**Italian:** `DIODATI` (Diodati (1649))

**Japanese:** `BUNGO` (Bungo-yaku: Taisho-kaiyaku (NT) (1950), Meiji-yaku (OT) (1953) (1950/1953))

**Kannada:** `KAN` (ಕನ್ನಡ)

**Malayalam:** `MAL` (മലയാളം)

**Oriya:** `ORI` (ଓଡ଼ିଆ oḍiā)

**Pedi:** `SEP` (Bibele Taba Yea Botse (NSO00))

**Português:** `AA` (Tradução de João Ferreira de Almeida (Versão Revista e Atualizada)), `ACF` (Tradução de João Ferreira de Almeida Revista e Corrigida.), `BLIVRE` (Biblia Livre), `NVI` (Nova Versão Internacional )

**Punjabi:** `PUN` (ਪੰਜਾਬੀ پنجابی)

**Tamil:** `TAM` (தமிழ் )

**Telugu:** `TEL` (తెలుగు)

**Vietnamese:** `CADMAN` (Vietnamese Cadman (1934))

**Xhosa:** `XHO` (Izibhalo Ezingcwele (XHO75))

**Zulu:** `ZUL` (Ibhayibheli Elingcwele (ZUL59))

## Ejemplos de uso

```bash
# curl
curl "https://evanbible.com/api/v1/rv60/salmos/23/1-6"
curl -H "X-API-Key: TU_KEY" "https://evanbible.com/api/v1/kjv/john/3"
```

```javascript
// JavaScript — versículo del día
const res = await fetch('https://evanbible.com/api/v1/rv60/random');
const d = await res.json();
console.log(`"${d.text}" — ${d.reference} (${d.version})`);
```

```php
// PHP
$d = json_decode(file_get_contents('https://evanbible.com/api/v1/rv60/juan/3/16'), true);
echo $d['verses'][0]['text'];
```

## Notas para agentes de IA

- Prefiere el **número canónico de libro** (1–66) sobre nombres: evita ambigüedades entre idiomas.
- Para citar, usa el campo `reference` que ya viene formateado (`Juan 3:16`).
- La búsqueda es *substring* simple (LIKE), no semántica; usa palabras concretas.
- Pagina con `page` y `limit`; `total` y `pages` vienen en la respuesta.
- Los textos pueden incluir comillas y puntuación del idioma original; ya vienen decodificados (sin entidades HTML).
- Esta documentación vive en `https://evanbible.com/docs.md` y `https://evanbible.com/llms.txt` — siempre refleja las versiones publicadas actualmente.