Referência / Calendário

Calendário litúrgico

Consulte uma data, um mês ou o ano completo com o livro de oração e as preferências escolhidas.

Dia litúrgico

Retorna o tempo e a cor litúrgicos, as celebrações, as coletas e as leituras correspondentes à data e às preferências enviadas.

GET/api/v1/calendar/today— data de hoje

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

/today usa a data atual. Os dois endpoints exigem preferences[prayer_book_code]. Para outra data, use /calendar/2026/03/25; o formato é YYYY/MM/DD.

Trecho da resposta — 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"
    }
  }
}

Parâmetro preferences

Envie o lecionário e as traduções bíblicas em um objeto JSON codificado para URL no parâmetro preferences.

Chave	Descrição
prayer_book_code	O código do livro (ex: loc_2015, loc_2019, loc_1662_en). Define a regra litúrgica e as coletas.
bible_version	O código da versão bíblica. Consulte /api/v1/bible_versions para ver as opções disponíveis.
lectionary_variant	Tabela de leituras opcional do BCP 1662: original_1662, revised_1871 ou revised_1922. Use somente quando o livro informar essa preferência.
psalm_translation	Texto dos Salmos: bible_version usa a versão escolhida; coverdale usa o Saltério Coverdale de 1662. Consulte as preferências do livro.

Preferências dinâmicas: os valores suportados por cada livro vêm de GET /api/v1/prayer_books/:prayer_book_code/preferences. Para o BCP 1662 em inglês, use loc_1662_en e a variante desejada dentro de preferences.

Descrição dos campos

Campo	Descrição
date	Data da resposta formatada (DD/MM/YYYY).
day_of_week	Nome do dia da semana por extenso.
liturgical_season	O tempo litúrgico atual (ex: Quaresma, Advento, Tempo Comum).
liturgical_color	A cor das vestes e ornamentos recomendada (verde, vermelho, roxo, branco).
liturgical_year	O ciclo anual do lecionário (A, B ou C).
description	Lista de textos descrevendo a semana ou o dia específico (ex: "1ª Semana da Quaresma").
celebration	Objeto com os detalhes da festa ou do santo principal do dia.
collect	Lista de orações (coletas) específicas para o dia.
readings	Referências bíblicas estruturadas para o lecionário do dia.

Visão geral do ano litúrgico

Um conjunto de endpoints escopados por ano para responder perguntas como “quando é a Páscoa em 2027?” ou “quais são as festas principais deste ano?”. Todos requerem o parâmetro preferences com prayer_book_code e ficam em cache por um mês.

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

1. /overview

Consolida tudo numa única requisição: ciclo litúrgico, quadras, datas móveis e celebrações. Ideal para gerar um calendário anual completo.

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

Resposta JSON200 OK

{
  "year": 2026,
  "prayer_book": "loc_2015",
  "liturgical_year": "A",
  "seasons": [ /* quadras litúrgicas */ ],
  "key_dates": { /* datas móveis */ },
  "celebrations": [ /* todas as celebrações, ordem cronológica */ ],
  "celebrations_by_type": {
    "principal_feast": [ /* ... */ ],
    "major_holy_day":  [ /* ... */ ],
    "festival":        [ /* ... */ ],
    "lesser_feast":    [ /* ... */ ],
    "sunday":          [ /* ... */ ]
  }
}

2. /seasons

As seis quadras litúrgicas do ano com datas de início e fim. A quadra do Natal começa em 25 de dezembro do ano anterior — isso é esperado.

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

Resposta 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	Descrição
name	string	Nome da quadra
slug	string	Identificador usado em URLs de links e posts
start_date	string (YYYY-MM-DD)	Data de início (inclusive)
end_date	string (YYYY-MM-DD)	Data de fim (inclusive)

3. /key_dates

As datas móveis mais importantes do ano, todas calculadas em relação à Páscoa pelo algoritmo de Computus.

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

Trecho da resposta200 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" }
}

Os campos name e post_slug são opcionais: se o livro de oração não tiver uma celebração cadastrada para aquela data, a entrada retorna apenas a data.

4. /celebrations

Todas as celebrações do ano cadastradas no livro de oração. Suporta filtro por tipo e agrupamento.

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

Parâmetro	Tipo	Valores	Padrão
type	string	principal_feast · major_holy_day · festival · lesser_feast · commemoration	todos
grouped	boolean	true · false	false

Resposta JSON — lista cronológica (padrão)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 as celebrações do ano em ordem cronológica
]

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

{
  "principal_feast": [ /* ... */ ],
  "major_holy_day":  [ /* ... */ ],
  "festival":        [ /* ... */ ],
  "lesser_feast":    [ /* ... */ ],
  "sunday":          [ /* ... */ ]
}
// tipos sem celebrações são omitidos

Campo	Tipo	Descrição
date	string (YYYY-MM-DD)	Data observada (pode diferir da original em caso de transferência)
name	string	Nome conforme o livro de oração
type	string	Tipo da celebração (principal_feast, major_holy_day, festival, lesser_feast, commemoration)
color	string	Cor litúrgica
post_slug	string \| null	Slug para link a um post ou conteúdo
transferred	boolean	true se a data foi transferida por conflito litúrgico; date já reflete a data observada

Erros

Status	Mensagem
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"