Recursos Core

Calendário Litúrgico

"Ensina-nos a contar os nossos dias, para que alcancemos coração sábio."

Dia Litúrgico

Retorna a verdade litúrgica consolidada para uma data, processando cores, tempos, celebrações e lecionário.

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

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

Dica: /today é um atalho para a data atual. Para consultar qualquer outra data, use /calendar/2026/03/25 — o formato é sempre YYYY/MM/DD.

Response JSON200 OK

{
  "date": "24/02/2026",
  "day_of_week": "Terça-feira",
  "liturgical_season": "Quaresma",
  "liturgical_color": "vermelho",
  "liturgical_year": "A",
  "description": ["1ª Semana da Quaresma"],
  "celebration": {
    "name": "Matias",
    "type": "festival",
    "description": "Apóstolo"
  },
  "collect": [
    {
      "title": "Matias",
      "text": "Senhor Deus, o teu servo Matias foi escolhido..."
    }
  ],
  "readings": {
    "first_reading": {
      "reference": "Gênesis 4.1-16",
      "book_name": "Gênesis"
    },
    "psalm": {
      "reference": "Salmo 32"
    }
  }
}

Parâmetro Preferences

Você pode customizar o lecionário e as traduções bíblicas enviando um objeto JSON (URL encoded) no parâmetro preferences.

Chave	Descrição
prayer_book_code	O código do livro (ex: `loc_2015`, `loc_2019`). Define a regra litúrgica e as coletas.
bible_version	O código da versão bíblica (ex: `nvi`, `esv`). Define a tradução dos textos das leituras.

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 em português.
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 strings descrevendo a semana ou dia específico (ex: "1ª Semana da Quaresma").
celebration	Objeto contendo detalhes da festa ou 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 fazem cache de 1 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"}

Response JSON200 OK

{
  "year": 2026,
  "prayer_book": "loc_2015",
  "liturgical_year": "C",
  "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":    [ /* ... */ ],
    "commemoration":   [ /* ... */ ]
  }
}

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"}

Response 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 em português
slug	string	Identificador URL-friendly para 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"}

Response JSON200 OK

{
  "baptism_of_the_lord":   { "date": "2026-01-11", "name": "Batismo do Senhor",      "post_slug": "baptism-of-the-lord" },
  "ash_wednesday":          { "date": "2026-02-18", "name": "Quarta-Feira de Cinzas", "post_slug": "ash-wednesday" },
  "palm_sunday":            { "date": "2026-03-22", "name": "Domingo de Ramos",       "post_slug": "palm-sunday" },
  "maundy_thursday":        { "date": "2026-03-26", "name": "Quinta-Feira Santa",     "post_slug": "maundy-thursday" },
  "good_friday":            { "date": "2026-03-27", "name": "Sexta-Feira da Paixão",  "post_slug": "good-friday" },
  "holy_saturday":          { "date": "2026-03-28", "name": "Sábado Santo",           "post_slug": "holy-saturday" },
  "easter":                 { "date": "2026-04-05", "name": "Páscoa",                 "post_slug": "easter-sunday" },
  "ascension":              { "date": "2026-05-14", "name": "Ascensão",               "post_slug": "ascension" },
  "pentecost":              { "date": "2026-05-24", "name": "Pentecostes",            "post_slug": "pentecost" },
  "trinity_sunday":         { "date": "2026-05-31", "name": "Santíssima Trindade",    "post_slug": "trinity-sunday" },
  "christ_the_king":        { "date": "2026-11-22", "name": "Cristo Rei",             "post_slug": "christ-the-king" },
  "first_sunday_of_advent": { "date": "2026-11-29", "name": "1º Domingo do Advento",  "post_slug": "advent-sunday" }
}

Os campos name e post_slug são opcionais: se o prayer book não tiver uma celebração cadastrada para aquela data, a entrada retorna apenas {"date": "..."}.

4. /celebrations

Todas as celebrações do ano cadastradas no prayer book. Suporta filtro por tipo e agrupamento.

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

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

Response JSON — lista cronológica (default)200 OK

[
  {
    "date": "2026-01-01",
    "name": "A Circuncisão de Cristo",
    "type": "principal_feast",
    "color": "branco",
    "post_slug": "circumcision-of-christ",
    "transferred": false
  }
  // ... todas as celebrações do ano em ordem cronológica
]

Response JSON — agrupado (?grouped=true)200 OK

{
  "principal_feast": [ /* ... */ ],
  "major_holy_day":  [ /* ... */ ],
  "festival":        [ /* ... */ ],
  "lesser_feast":    [ /* ... */ ],
  "commemoration":   [ /* ... */ ]
}
// 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 prayer book
type	string	Tipo da celebração (principal_feast, major_holy_day, festival, lesser_feast, commemoration)
color	string	Cor litúrgica em português
post_slug	string \| null	Slug para link a post/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	"prayer_book_code é obrigatório"
400	"Tipo inválido. Valores aceitos: principal_feast, major_holy_day, festival, lesser_feast, commemoration"