API v2: peça só o que for usar

Barata por padrão

A v1 foi desenhada para o aplicativo Ordo e devolve tudo o que uma tela do app precisa. Quem só quer as referências das leituras de amanhã recebia o dia inteiro, com coleta, salmo e leituras da manhã e da tarde. A v2 inverte isso.

A v1 continua publicada e sem prazo para sair. Use a v2 em integrações novas e migre uma rota de cada vez, se e quando fizer sentido.

Uma chave, um cabeçalho

A v2 aceita apenas chave de API, enviada no cabeçalho X-API-Key. É a mesma chave da v1: o plano, os limites e o painel de uso valem para as duas versões.

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"

Sem a chave, a resposta é 401 MISSING_API_KEY. Mantenha a chave no servidor: nunca a coloque em código que roda no navegador ou no app.

book é obrigatório

Na v1, quem esquece o livro recebe 200 com os dados de um livro que não escolheu. Na v2, todo recurso que depende do livro exige book. Os catálogos de livros e de Bíblias e /passages não exigem.

{
  "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: o que é calculado

Sem include, /days devolve só o dia litúrgico: tempo, cor, semana e a celebração que prevaleceu. Cada include acrescenta um sub-recurso e tem um custo relativo, informado em X-Request-Cost.

• — Um filho implica o pai: include=readings.text já calcula readings.
• — Um include fora da lista do endpoint responde 400 INVALID_INCLUDE, com a lista aceita em allowed.
• — Em /days/:date/readings e /collects/:date o recurso já é o do caminho; include só acrescenta text ou alternatives.

fields: o que é serializado

fields[tipo] recebe a lista de atributos a devolver para aquele tipo de recurso. Não altera o que é calculado; só o que volta no JSON.

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

Tipos aceitos: dayreadingcollectcelebrationcelebration_typeannual_overviewseasonkey_datelectionary_cycleprayer_bookbible_version

data, meta e links

Um envelope único, para escrever um parser só. As chaves são snake_case em inglês em todos os recursos; os valores, como nomes de tempos e cores, vêm no idioma do livro ou 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 repete o contexto que resolveu a resposta: livro, idioma, versão bíblica e variante do lecionário, quando houver.
• — As leituras são uma lista com slot (first_reading, psalm, second_reading, gospel…), e não quatro chaves fixas: livros diferentes têm números diferentes de leituras.
• — Um dia sem leituras responde 200 com readings vazio. 404 fica para recurso que não existe.
• — Coleções paginadas trazem links.self e links.next; meta traz count e total.

Cache, custo e limites

Onde cada rota foi parar

Os dados vêm dos mesmos serviços litúrgicos da v1; o que muda é o formato. A v2 ainda não publica o Ofício Diário: para ele, continue na v1.

• — O blob preferences vira parâmetros planos: book, bible, lectionary, psalter, reading_type e lang. O blob ainda é aceito para facilitar a migração.
• — As datas ficam no formato ISO (2026-03-25), tanto no caminho quanto nas respostas.
• — As rotas usam hífen (key-dates, prayer-books) em vez de sublinhado.