Referencia / Calendario

Calendario litúrgico

Consulta una fecha, un mes o el año completo con el libro de oración y las preferencias que elijas.

Día litúrgico

Devuelve el tiempo y el color litúrgicos, las celebraciones, las colectas y las lecturas correspondientes a la fecha y a las preferencias enviadas.

GET/api/v1/calendar/today— la fecha de hoy

GET/api/v1/calendar/:year/:month/:day— una fecha específica

/today usa la fecha actual. Ambos endpoints exigen preferences[prayer_book_code]. Para otra fecha usa /calendar/2026/03/25; el formato es YYYY/MM/DD.

Fragmento de la respuesta — 25/03/2026, loc_2015200 OK

{
  "date": "25/03/2026",
  "day_of_week": "Quarta-feira",
  "liturgical_season": "Quaresma",
  "liturgical_color": "branco",
  "liturgical_year": "A",
  "is_holy_day": true,
  "description": ["Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria"],
  "celebration": {
    "name": "Anunciação de Nosso Senhor Jesus Cristo à Bem-Aventurada Virgem Maria",
    "type": "principal_feast",
    "post_slug": "celebration-annunciation",
    "transferred": false
  },
  "readings": {
    "first_reading": {
      "reference": "Isaías 7:10-14",
      "book_name": "Isaías"
    },
    "psalm": {
      "reference": "Salmo 45"
    },
    "second_reading": {
      "reference": "Hebreus 10:4-10"
    },
    "gospel": {
      "reference": "Lucas 1:26-38"
    }
  }
}

El parámetro preferences

Envía el leccionario y las traducciones bíblicas en un objeto JSON codificado para URL en el parámetro preferences.

Clave	Descripción
prayer_book_code	El código del libro (ej: loc_2015, loc_2019, loc_1662_en). Define la regla litúrgica y las colectas.
bible_version	El código de la versión bíblica. Consulta /api/v1/bible_versions para ver las opciones disponibles.
lectionary_variant	Tabla de lecturas opcional del BCP 1662: original_1662, revised_1871 o revised_1922. Úsala solo cuando el libro declare esta preferencia.
psalm_translation	Texto de los Salmos: bible_version usa la versión elegida; coverdale usa el Salterio Coverdale de 1662. Consulta las preferencias del libro.

Preferencias dinámicas: los valores que admite cada libro vienen de GET /api/v1/prayer_books/:prayer_book_code/preferences. Para el BCP 1662 en inglés, usa loc_1662_en y la variante deseada dentro de preferences.

Descripción de los campos

Campo	Descripción
date	Fecha de la respuesta, formateada.
day_of_week	Nombre del día de la semana, escrito por completo.
liturgical_season	El tiempo litúrgico actual (ej: Cuaresma, Adviento, Tiempo Ordinario).
liturgical_color	El color recomendado de vestiduras y ornamentos (verde, rojo, morado, blanco).
liturgical_year	El ciclo anual del leccionario (A, B o C).
description	Lista de textos que describen la semana o el día específico (ej: "1.ª Semana de Cuaresma").
celebration	Objeto con los detalles de la fiesta o del santo principal del día.
collect	Lista de oraciones (colectas) propias del día.
readings	Referencias bíblicas estructuradas para el leccionario del día.

Vista general del año litúrgico

Un conjunto de endpoints por año para responder preguntas como “¿cuándo es la Pascua en 2027?” o “¿cuáles son las fiestas principales de este año?”. Todos requieren el parámetro preferences con prayer_book_code y se guardan en caché durante un mes.

GET/api/v1/calendar/:year/<endpoint>

1. /overview

Todo en una sola solicitud: ciclo litúrgico, tiempos, fechas móviles y celebraciones. Ideal para generar un calendario anual completo.

GET/api/v1/calendar/2026/overview?preferences={"prayer_book_code":"loc_2015"}

Respuesta JSON200 OK

{
  "year": 2026,
  "prayer_book": "loc_2015",
  "liturgical_year": "A",
  "seasons": [ /* tiempos litúrgicos */ ],
  "key_dates": { /* fechas móviles */ },
  "celebrations": [ /* todas las celebraciones, en orden cronológico */ ],
  "celebrations_by_type": {
    "principal_feast": [ /* ... */ ],
    "major_holy_day":  [ /* ... */ ],
    "festival":        [ /* ... */ ],
    "lesser_feast":    [ /* ... */ ],
    "sunday":          [ /* ... */ ]
  }
}

2. /seasons

Los seis tiempos litúrgicos del año con fechas de inicio y fin. El tiempo de Navidad empieza el 25 de diciembre del año anterior: eso es lo esperado.

GET/api/v1/calendar/2026/seasons?preferences={"prayer_book_code":"loc_2015"}

Respuesta JSON200 OK

[
  { "name": "Natal",        "slug": "season-christmas",     "start_date": "2025-12-25", "end_date": "2026-01-10" },
  { "name": "Epifania",     "slug": "season-epiphany",      "start_date": "2026-01-11", "end_date": "2026-02-17" },
  { "name": "Quaresma",     "slug": "season-lent",          "start_date": "2026-02-18", "end_date": "2026-04-04" },
  { "name": "Páscoa",       "slug": "season-easter",        "start_date": "2026-04-05", "end_date": "2026-05-24" },
  { "name": "Tempo Comum",  "slug": "season-ordinary-time", "start_date": "2026-05-25", "end_date": "2026-11-28" },
  { "name": "Advento",      "slug": "season-advent",        "start_date": "2026-11-29", "end_date": "2026-12-24" }
]

Campo	Tipo	Descripción
name	string	Nombre del tiempo
slug	string	Identificador usado en URLs de enlaces y publicaciones
start_date	string (YYYY-MM-DD)	Fecha de inicio (inclusive)
end_date	string (YYYY-MM-DD)	Fecha de fin (inclusive)

3. /key_dates

Las fechas móviles más importantes del año, todas calculadas a partir de la Pascua con el algoritmo de Computus.

GET/api/v1/calendar/2026/key_dates?preferences={"prayer_book_code":"loc_2015"}

Fragmento de la respuesta200 OK

{
  "ash_wednesday": {
    "date": "2026-02-18",
    "name": "Quarta-Feira de Cinzas",
    "post_slug": "celebration-ash-wednesday"
  },
  "palm_sunday": { "date": "2026-03-29" },
  "easter": {
    "date": "2026-04-05",
    "name": "Páscoa",
    "post_slug": "celebration-easter"
  },
  "first_sunday_of_advent": { "date": "2026-11-29" }
}

Los campos name y post_slug son opcionales: si el libro de oración no tiene una celebración registrada para esa fecha, la entrada devuelve solo la fecha.

4. /celebrations

Todas las celebraciones del año registradas en el libro de oración. Admite filtro por tipo y agrupación.

GET/api/v1/calendar/2026/celebrations?preferences={"prayer_book_code":"loc_2015"}

Parámetro	Tipo	Valores	Por defecto
type	string	principal_feast · major_holy_day · festival · lesser_feast · commemoration	todos
grouped	boolean	true · false	false

Respuesta JSON — lista cronológica (por defecto)200 OK

[
  {
    "date": "2026-01-01",
    "name": "Santo Nome e Circuncisão de Nosso Senhor Jesus Cristo",
    "type": "principal_feast",
    "color": "branco",
    "post_slug": "celebration-holy-name-circumcision",
    "transferred": false
  }
  // ... todas las celebraciones del año en orden cronológico
]

Respuesta JSON — agrupada (?grouped=true)200 OK

{
  "principal_feast": [ /* ... */ ],
  "major_holy_day":  [ /* ... */ ],
  "festival":        [ /* ... */ ],
  "lesser_feast":    [ /* ... */ ],
  "sunday":          [ /* ... */ ]
}
// los tipos sin celebraciones se omiten

Campo	Tipo	Descripción
date	string (YYYY-MM-DD)	Fecha observada (puede diferir de la original en caso de traslado)
name	string	Nombre según el libro de oración
type	string	Tipo de celebración (principal_feast, major_holy_day, festival, lesser_feast, commemoration)
color	string	Color litúrgico
post_slug	string \| null	Slug para enlazar a una publicación o contenido
transferred	boolean	true si la fecha fue trasladada por un conflicto litúrgico; date ya refleja la fecha observada

Errores

Estado	Mensaje
400	"Ano inválido: ..."
400	"O parâmetro preferences[prayer_book_code] é obrigatório"
400	"Tipo inválido. Valores aceitos: principal_feast, major_holy_day, festival, lesser_feast, commemoration"