API v2: pide solo lo que vas a usar

Económica por defecto

La v1 se diseñó para la app Ordo y devuelve todo lo que una pantalla de la app necesita. Quien solo quería las referencias de las lecturas de mañana recibía el día entero, con colecta, salmo y lecturas de la mañana y de la tarde. La v2 lo invierte.

La v1 sigue publicada y sin plazo de retiro. Usa la v2 en integraciones nuevas y migra una ruta a la vez, si y cuando tenga sentido.

Una clave, un encabezado

La v2 acepta solo clave de API, enviada en el encabezado X-API-Key. Es la misma clave de la v1: el plan, los límites y el panel de uso valen para las dos versiones.

https://api.caminhoanglicano.com.br/api/v2

curl -G "https://api.caminhoanglicano.com.br/api/v2/days/today" \
  -H "X-API-Key: $ESTEVAO_API_KEY" \
  --data-urlencode "book=loc_2015" \
  --data-urlencode "include=readings,collect"

Sin la clave, la respuesta es 401 MISSING_API_KEY. Mantén la clave en el servidor: nunca la pongas en código que corre en el navegador o en la app.

book es obligatorio

En la v1, quien olvida el libro recibe 200 con los datos de un libro que no eligió. En la v2, todo recurso que depende del libro exige book. Los catálogos de libros y de Biblias y /passages no lo exigen.

{
  "type": "https://estevao.caminhoanglicano.com.br/docs/v2/errors#missing-prayer-book",
  "title": "Missing prayer book",
  "status": 400,
  "code": "MISSING_PRAYER_BOOK",
  "detail": "O parâmetro 'book' é obrigatório na v2. Consulte GET /api/v2/prayer-books.",
  "documentation_url": "https://estevao.caminhoanglicano.com.br/docs/v2",
  "request_id": "6f0c2c1e-…"
}

include: lo que se calcula

Sin include, /days devuelve solo el día litúrgico: tiempo, color, semana y la celebración que prevaleció. Cada include añade un subrecurso y tiene un costo relativo, informado en X-Request-Cost.

• — Un hijo implica al padre: include=readings.text ya calcula readings.
• — Un include que el endpoint no ofrece responde 400 INVALID_INCLUDE, con la lista aceptada en allowed.
• — En /days/:date/readings y /collects/:date el recurso ya es el de la ruta; include solo añade text o alternatives.

fields: lo que se serializa

fields[tipo] recibe la lista de atributos a devolver para ese tipo de recurso. No cambia lo que se calcula; solo lo que vuelve en el JSON.

/api/v2/days?book=loc_2015&from=2026-03-01&to=2026-03-31
  &fields[day]=date,season,color,celebration

Tipos aceptados: dayreadingcollectcelebrationcelebration_typeannual_overviewseasonkey_datelectionary_cycleprayer_bookbible_version

data, meta y links

Un sobre único, para escribir un solo parser. Las claves son snake_case en inglés en todos los recursos; los valores, como nombres de tiempos y colores, vienen en el idioma del libro o de lang.

{
  "data": {
    "date": "2026-03-25",
    "liturgical_year": 2026,
    "week_of_season": 5,
    "is_sunday": false,
    "is_holy_day": true,
    "day_of_week": "Quarta-feira",
    "season": { "slug": "lent", "name": "Quaresma" },
    "color": "branco",
    "description": ["Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria"],
    "fast": null,
    "celebration": {
      "id": 412,
      "name": "Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria",
      "type": "principal_feast",
      "color": "branco",
      "movable": false,
      "transferred": false
    }
  },
  "meta": {
    "prayer_book": "loc_2015",
    "language": "pt-BR",
    "bible": "nvi",
    "generated_at": "2026-03-25T09:00:00Z"
  }
}

• — meta repite el contexto que resolvió la respuesta: libro, idioma, versión bíblica y variante del leccionario, cuando la hay.
• — Las lecturas son una lista con slot (first_reading, psalm, second_reading, gospel…), no cuatro claves fijas: los libros difieren en cuántas lecturas asignan.
• — Un día sin lecturas responde 200 con readings vacío. 404 queda para recursos que no existen.
• — Las colecciones paginadas traen links.self y links.next; meta trae count y total.

Caché, costo y límites

Dónde quedó cada ruta

Los datos salen de los mismos servicios litúrgicos de la v1; lo que cambia es el formato. La v2 todavía no publica el Oficio Diario: para eso, sigue en la v1.

• — El blob preferences se convierte en parámetros planos: book, bible, lectionary, psalter, reading_type y lang. El blob todavía se acepta para facilitar la migración.
• — Las fechas van en formato ISO (2026-03-25), tanto en la ruta como en las respuestas.
• — Las rutas usan guion (key-dates, prayer-books) en lugar de guion bajo.