Pular para o conteúdo

Novidade: App disponível para iPhone e Android. Conheça →

Para Desenvolvedores

API Católica — Ora et Labora

API REST aberta com a Bíblia Católica completa (73 livros), Regra de São Bento, Vida de São Bento (Diálogos de São Gregório), 721 Apoftegmas dos Padres do Deserto, o Graduale Romanum e o Calendário Litúrgico.

Base URL

https://oraetlabora.com.br/api/v1
  • Versionamento: /api/v1 é o contrato oficial (OpenAPI 3.1); os caminhos /api continuam funcionando como legado compatível, com as mesmas respostas
  • Contrato formal: openapi/openapi.yaml no repositório — validado contra a implementação em CI
  • Formato de resposta: JSON (exceção: o folheto do Graduale retorna PDF)
  • Autenticação: opcional — header x-api-key para uso licenciado
  • Rate limit: 60 req/min por IP600 req/min com API key
  • CORS: respostas via navegador restritas às origens do próprio oraetlabora.com.br — para consumir de outro domínio, chame a API a partir do seu servidor
  • Método: GET apenas (e OPTIONS para preflight)

Referência rápida — Todos os endpoints

MétodoEndpointDescrição
GET/api/bibliaLista todos os 73 livros
GET/api/biblia/:livroInformações de um livro
GET/api/biblia/:livro/:capituloVersículos de um capítulo
GET/api/regraLista Prólogo e 73 capítulos
GET/api/regra/:capituloVersículos de um capítulo
GET/api/regra/busca?q=:termoBusca na Regra
GET/api/dialogosLista os 40 capítulos
GET/api/dialogos/:capituloParágrafos de um capítulo
GET/api/apoftegmasLista os 92 autores
GET/api/apoftegmas/:padreApoftegmas de um autor
GET/api/calendarioCalendário litúrgico completo
GET/api/calendario/hojeTempo litúrgico atual
GET/api/calendario/:mesCelebrações de um mês
GET/api/graduale/folhetoFolheto da Missa em PDF (4 req/min)
GET/api/v1/metaEstatísticas e versão da API
GET/api/v1/healthHealth check (sem cache)

Bíblia Católica

GET/api/biblia

Lista todos os 73 livros da Bíblia Católica, separados por Antigo e Novo Testamento

Exemplo

https://oraetlabora.com.br/api/biblia

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "total_livros": 73,
  "antigo_testamento": [
    { "abbrev": "gn", "nome": "Gênesis", "capitulos": 50 },
    { "abbrev": "ex", "nome": "Êxodo", "capitulos": 40 },
    { "abbrev": "lv", "nome": "Levítico", "capitulos": 27 }
    // ... 43 livros restantes
  ],
  "novo_testamento": [
    { "abbrev": "mt", "nome": "Evangelho Segundo São Mateus", "capitulos": 28 },
    { "abbrev": "mc", "nome": "Evangelho Segundo São Marcos", "capitulos": 16 },
    { "abbrev": "lc", "nome": "Evangelho Segundo São Lucas", "capitulos": 24 }
    // ... 24 livros restantes
  ]
}
GET/api/biblia/:livro

Informações de um livro específico

Parâmetros: livro — abreviação do livro (veja tabela completa abaixo)

Exemplo

https://oraetlabora.com.br/api/biblia/gn

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "abbrev": "gn",
  "nome": "Gênesis",
  "capitulos": 50
}
GET/api/biblia/:livro/:capitulo

Todos os versículos de um capítulo específico

Parâmetros: livro — abreviação do livro · capitulo — número do capítulo

Exemplo

https://oraetlabora.com.br/api/biblia/gn/1

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "livro": "Gênesis",
  "abbrev": "gn",
  "capitulo": 1,
  "versiculos": [
    { "numero": 1, "texto": "No princípio criou Deus o céu e a terra." },
    { "numero": 2, "texto": "A terra, porém, estava informe e vazia, e as trevas cobriam a face do abismo, e o Espírito de Deus movia-Se sobre as águas." },
    { "numero": 3, "texto": "E Deus disse: Exista a luz. E a luz existiu." }
    // ... demais versículos
  ]
}

Regra de São Bento

GET/api/regra

Lista o Prólogo (capítulo 0) e os 73 capítulos da Regra de São Bento

Exemplo

https://oraetlabora.com.br/api/regra

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "total": 74,
  "capitulos": [
    { "numero": 0, "titulo": "Prólogo da Regra", "versiculos": 50 },
    { "numero": 1, "titulo": "Dos vários gêneros de monges", "versiculos": 13 },
    { "numero": 2, "titulo": "Das qualidades que deve ter o Abade", "versiculos": 40 }
    // ... 71 capítulos restantes
  ]
}
GET/api/regra/:capitulo

Versículos de um capítulo específico

Parâmetros: capitulo — número (0 = Prólogo, 1–73 = capítulos)

Exemplo

https://oraetlabora.com.br/api/regra/0

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "numero": 0,
  "titulo": "Prólogo da Regra",
  "versiculos": [
    { "numero": 1, "texto": "Escuta, filho, os preceitos do Mestre, e inclina o ouvido do teu coração; recebe de boa vontade e executa eficazmente o conselho de um bom pai," },
    { "numero": 2, "texto": "para que pelo trabalho da obediência tornes a Aquele de quem te afastaste pela inércia da desobediência." }
    // ... 48 versículos restantes
  ]
}
GET/api/regra/busca?q=:termo

Busca por palavra-chave em todos os versículos da Regra

Parâmetros: q — termo de busca (mínimo 2 caracteres)

Exemplo

https://oraetlabora.com.br/api/regra/busca?q=humildade

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "query": "humildade",
  "total": 12,
  "resultados": [
    {
      "capitulo": 7,
      "titulo": "Da humildade",
      "versiculo": 1,
      "texto": "Clama-nos a divina Escritura, irmãos, dizendo: Todo aquele que se exalta será humilhado, e quem se humilha será exaltado."
    }
    // ... 11 resultados restantes
  ]
}

Vida de São Bento (Diálogos)

Segundo Livro dos Diálogos de São Gregório Magno — a principal fonte histórica sobre a vida de São Bento.

GET/api/dialogos

Lista o Prefácio (−1), Prólogo (0) e os 38 capítulos

Exemplo

https://oraetlabora.com.br/api/dialogos

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "total": 40,
  "capitulos": [
    { "numero": -1, "titulo": "Prefácio de São Gregório Magno aos Quatro Livros dos Diálogos", "paragrafos": 5 },
    { "numero": 0, "titulo": "Prólogo", "paragrafos": 3 },
    { "numero": 1, "titulo": "A infância e a juventude de Bento", "paragrafos": 12 }
    // ... 37 capítulos restantes
  ]
}
GET/api/dialogos/:capitulo

Parágrafos de um capítulo, com campo interlocutor (Gregório, Pedro ou null para narrador)

Parâmetros: capitulo — número (−1 = Prefácio, 0 = Prólogo, 1–38 = capítulos)

Exemplo

https://oraetlabora.com.br/api/dialogos/1

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "numero": 1,
  "titulo": "A infância e a juventude de Bento",
  "paragrafos": [
    {
      "numero": 1,
      "interlocutor": "Gregório",
      "texto": "Houve um homem de vida venerável, abençoado pela graça e pelo nome..."
    },
    {
      "numero": 2,
      "interlocutor": null,
      "texto": "Nascido de família nobre na região de Núrsia..."
    }
    // ... demais parágrafos
  ]
}

Apoftegmas dos Padres do Deserto

GET/api/apoftegmas

Lista todos os 92 autores e a contagem total de apoftegmas

Exemplo

https://oraetlabora.com.br/api/apoftegmas

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "total_autores": 92,
  "total_apoftegmas": 721,
  "autores": [
    { "id": "abade-antao", "nome": "Abade Antão", "apoftegmas": 38 },
    { "id": "abade-arsenio", "nome": "Abade Arsênio", "apoftegmas": 44 },
    { "id": "abade-agatao", "nome": "Abade Agatão", "apoftegmas": 30 }
    // ... 89 autores restantes
  ]
}
GET/api/apoftegmas/:padre

Todos os apoftegmas de um autor específico

Parâmetros: padre — ID do autor (ex: abade-antao, abade-arsenio, abade-agatao; veja a tabela completa abaixo)

Exemplo

https://oraetlabora.com.br/api/apoftegmas/abade-antao

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "id": "abade-antao",
  "nome": "Abade Antão",
  "total": 38,
  "apoftegmas": [
    {
      "numero": 1,
      "texto": "O santo Abade Antão, certa vez sentado no deserto, foi acometido de acedia e grande turbilhão de pensamentos; disse então a Deus: “Senhor, quero ser salvo, e não me deixam os pensa…"
    }
    // ... 37 apoftegmas restantes
  ]
}

Calendário Litúrgico

Calendário litúrgico do ano em curso com tempos, solenidades, festas e memórias. As respostas abaixo são exemplos ilustrativos — as datas reais acompanham o ano litúrgico vigente; para o dia atual, use /api/calendario/hoje.

GET/api/calendario

Retorna o ano litúrgico completo com todos os tempos e celebrações

Exemplo

https://oraetlabora.com.br/api/calendario

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "ano_liturgico": "2025-2026",
  "ciclo_dominical": "B",
  "ciclo_ferial": "II",
  "tempos": [
    { "id": "advento", "nome": "Advento", "cor": "Roxo", "inicio": "2025-11-30", "fim": "2025-12-24" }
    // ... demais tempos
  ],
  "total_celebracoes": 150,
  "celebracoes": [
    { "data": "2025-12-25", "nome": "Natal do Senhor", "tipo": "solenidade", "cor": "Branco", "tempo": "natal" }
    // ...
  ]
}
GET/api/calendario/hoje

Retorna o tempo litúrgico atual e se há celebração hoje

Parâmetros: data (opcional) — data no formato YYYY-MM-DD

Exemplo

https://oraetlabora.com.br/api/calendario/hoje

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "data": "2026-03-18",
  "tempo_liturgico": "Quaresma",
  "cor_liturgica": "Roxo",
  "celebracao": null,
  "proximo_evento": {
    "data": "2026-03-19",
    "nome": "São José, Esposo de Nossa Senhora",
    "tipo": "solenidade"
  }
}
GET/api/calendario/:mes

Todas as celebrações de um mês específico

Parâmetros: mes — número do mês (1–12)

Exemplo

https://oraetlabora.com.br/api/calendario/12

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "mes": 12,
  "nome": "Dezembro",
  "total": 12,
  "celebracoes": [
    { "data": "2025-12-08", "nome": "Imaculada Conceição de Nossa Senhora", "tipo": "solenidade", "cor": "Branco", "tempo": "advento" },
    { "data": "2025-12-25", "nome": "Natal do Senhor", "tipo": "solenidade", "cor": "Branco", "tempo": "natal" }
    // ...
  ]
}

Graduale Romanum — Folheto da Missa

Gera no servidor o folheto em PDF de uma Missa montada no Graduale (a mesma da URL compartilhável de /graduale). Por exigir renderização no servidor, tem limite próprio de 4 requisições por minuto — inclusive para requisições com API key.

GET/api/graduale/folheto

Folheto da Missa em PDF (A4 paisagem), pronto para impressão. Resposta binária application/pdf com Content-Disposition: attachment. Ao contrário dos demais endpoints, os erros retornam text/plain.

Parâmetros: proprio e ordinario (obrigatórios) — slugs de celebração do Graduale · opcionais: credo, asperges, seq e as escolhas por slot (introito, kyrie, gloria, gradual, aleluia, ofertorio, sanctus, agnus, communio)

Exemplo

https://oraetlabora.com.br/api/graduale/folheto?proprio=advento-1&ordinario=kyriale-missa-1

Resposta

// Resposta binária — application/pdf (não JSON)
// Content-Disposition: attachment; filename="folheto-advento-1.pdf"
// Cache-Control: public, max-age=3600

// Erros (text/plain):
// 400 — Parâmetros 'proprio' e 'ordinario' são obrigatórios.
// 404 — Celebração não encontrada.
// 500 — Não foi possível gerar o PDF.

Meta e Health

Endpoints de serviço, disponíveis apenas sob /api/v1. As estatísticas de /meta são contadas do acervo real a cada deploy — nunca digitadas.

GET/api/v1/meta

Versão da API, data da última publicação e estatísticas de todos os recursos, geradas da base real em tempo de build

Exemplo

https://oraetlabora.com.br/api/v1/meta

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "name": "Ora et Labora API",
  "version": "1.0.0",
  "updated_at": "(data do último deploy)",
  "base_url": "/api/v1",
  "docs": "/desenvolvedores",
  "resources": {
    "biblia": { "livros": 73, "versiculos": 35602 },
    "regra": { "capitulos": 74, "versiculos": 921 },
    "dialogos": { "capitulos": 40 },
    "apoftegmas": { "total": 721 },
    "graduale": { "celebracoes": 144, "pecas": 777 }
  }
}
GET/api/v1/health

Health check para monitoramento externo — sempre dinâmico, sem cache

Exemplo

https://oraetlabora.com.br/api/v1/health

Resposta

{
  "fonte": "Ora et Labora — oraetlabora.com.br",
  "status": "ok",
  "at": "2026-08-22T12:00:00.000Z"
}

Formato de erro

Erros usam o status HTTP correspondente (400, 404, 413, 429) e um JSON com o campo erro. Toda resposta da API inclui os headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset; o 429 traz também Retry-After (em segundos):

// 404 — Recurso não encontrado
{
  "erro": "Livro não encontrado.",
  "fonte": "Ora et Labora — oraetlabora.com.br"
}

// 400 — Parâmetro inválido
{
  "erro": "Número de capítulo inválido.",
  "fonte": "Ora et Labora — oraetlabora.com.br"
}

// 429 — Limite de requisições excedido (header Retry-After em segundos)
{
  "erro": "Limite de requisições excedido. Tente novamente em instantes.",
  "limite": "60 requisições por minuto",
  "fonte": "Ora et Labora — oraetlabora.com.br"
}

Exceção: /api/graduale/folheto retorna erros em text/plain, não em JSON.

Abreviações dos 73 livros da Bíblia

Use estas abreviações (em minúsculas) nos endpoints da Bíblia. Exemplo: /api/biblia/gn/1 para Gênesis capítulo 1.

Antigo Testamento (46 livros)

Abrev.LivroCap.
gnGênesis50
exÊxodo40
lvLevítico27
nmNúmeros36
dtDeuteronômio34
jsLivro De Josué24
jzLivro Dos Juízes21
rtRute4
1smPrimeiro Livro De Samuel31
2smSegundo Livro De Samuel24
1rsPrimeiro Livro Dos Reis22
2rsSegundo Livro Dos Reis25
1crPrimeiro Livro Das Crônicas29
2crSegundo Livro Das Crônicas36
esdEsdras10
neNeemias13
tbTobias14
jtJudite16
estEster16
1mcPrimeiro Livro Dos Macabeus16
2mcSegundo Livro Dos Macabeus15
42
slSalmos150
prProvérbios31
eclEclesiastes12
ctCântico Dos Cânticos8
sbSabedoria19
ecloEclesiástico51
isIsaías66
jrJeremias52
lmLamentações5
brBaruc6
ezEzequiel48
dnDaniel14
osOséias14
jlJoel3
amAmós9
abAbdias1
jnJonas4
mqMiquéias7
naNaum3
habHabacuc3
sfSofonias3
agAgeu2
zcZacarias14
mlMalaquias4

Novo Testamento (27 livros)

Abrev.LivroCap.
mtEvangelho Segundo São Mateus28
mcEvangelho Segundo São Marcos16
lcEvangelho Segundo São Lucas24
joEvangelho Segundo São João21
atAtos Dos Apóstolos28
rmCarta Aos Romanos16
1corPrimeira Carta Aos Coríntios16
2corSegunda Carta Aos Coríntios13
glCarta Aos Gálatas6
efCarta Aos Efésios6
flCarta Aos Filipenses4
clCarta Aos Colossenses4
1tsPrimeira Carta Aos Tessalonicenses5
2tsSegunda Carta Aos Tessalonicenses3
1tmPrimeira Carta A Timóteo6
2tmSegunda Carta A Timóteo4
ttCarta A Tito3
fmCarta A Filemon1
hbCarta Aos Hebreus13
tgCarta De São Tiago5
1pdPrimeira Carta De São Pedro5
2pdSegunda Carta De São Pedro3
1joPrimeira Carta De São João5
2joSegunda Carta De São João1
3joTerceira Carta De São João1
jdCarta De São Judas1
apApocalipse De São João22

Autores dos Apoftegmas

Os 92 autores (Padres e Madres do Deserto) disponíveis em /api/apoftegmas/:padre — use o slug (ID) para obter todos os apoftegmas de um autor.

Slug (ID)AutorApoftegmas
abade-antaoAbade Antão38
abade-arsenioAbade Arsênio44
abade-agataoAbade Agatão30
abade-amonasAbade Amonas11
abade-aquilazAbade Aquilaz6
abade-amoesAbade Amoés5
abade-amum-da-nitriaAbade Amum Da Nítria3
abade-anubeAbade Anube2
abade-abraaoAbade Abraão3
abade-areAbade Aré1
abade-alonioAbade Alônio4
abade-afiAbade Afi1
abade-apoloAbade Apolo3
abade-andreAbade André1
abade-aioAbade Aio1
abade-amonatazAbade Amonataz1
grande-basilioGrande Basílio1
abade-bessariaoAbade Bessarião12
abade-benjamimAbade Benjamim5
abade-biareAbade Biaré1
abade-gregorio-o-teologoAbade Gregório O Teólogo2
abade-gelasioAbade Gelásio6
abade-geroncioAbade Gerôncio1
abade-danielAbade Daniel8
abade-dioscoroAbade Dióscoro3
abade-dulazAbade Dulaz2
santo-epifanio-bispo-de-chipreSanto Epifânio, Bispo De Chipre17
abade-efremAbade Efrém3
eucaristo-o-secularEucaristo, O Secular1
eulogio-o-presbiteroEulógio, O Presbítero1
abade-euprepioAbade Euprépio7
abade-eladioAbade Eládio2
abade-evagrioAbade Evágrio7
abade-eudemaoAbade Eudemão1
abade-zenoAbade Zeno8
abade-zacariasAbade Zacarias5
abade-isaias-1Abade Isaías (1)11
abade-eliasAbade Elias8
abade-heraclioAbade Heráclio1
abade-teodoro-de-fermaAbade Teodoro De Ferma29
abade-teodoro-de-enatoAbade Teodoro De Enato3
abade-teodoro-da-cetiaAbade Teodoro Da Cétia1
abade-teodoro-de-eleuteropolisAbade Teodoro De Eleuterópolis2
abade-teonazAbade Teonaz1
arcebispo-teofiloArcebispo Teófilo5
madre-teodoraMadre Teodora7
abade-joao-curtoAbade João Curto40
abade-joao-o-cenobitaAbade João O Cenobita1
abade-isidoroAbade Isidoro9
abade-isidoro-de-pelusioAbade Isidoro De Pelúsio6
abade-isaque-o-presbitero-das-celiasAbade Isaque, O Presbítero Das Célias12
abade-jose-de-panefoAbade José De Panefo11
abade-tiagoAbade Tiago4
abade-hierazAbade Hieraz2
abade-joao-o-eunucoAbade João O Eunuco6
abade-joao-das-celiasAbade João Das Célias2
abade-isidoro-o-presbiteroAbade Isidoro O Presbítero7
abade-joao-persaAbade João Persa4
abade-joao-tebanoAbade João Tebano1
abade-joao-o-discipulo-do-abade-pauloAbade João, O Discípulo Do Abade Paulo1
abade-isaque-tebanoAbade Isaque Tebano2
abade-jose-tebanoAbade José Tebano1
abade-hilariaoAbade Hilarião1
abade-isquiriaoAbade Isquirião1
abade-cassianoAbade Cassiano8
abade-cronioAbade Crônio6
abade-cariaoAbade Carião2
abade-ciroAbade Ciro1
abade-lucioAbade Lúcio1
abade-loteAbade Lote2
abade-longinoAbade Longino5
abade-macario-egipcioAbade Macário Egípcio41
abade-moisesAbade Moisés18
abade-matoesAbade Matoés13
abade-marcos-discipulo-do-abade-silvanoAbade Marcos, Discípulo Do Abade Silvano5
abade-milesioAbade Milésio2
abade-mocioAbade Mócio2
abade-megetioAbade Megétio4
abade-miosAbade Miós3
abade-marcos-o-egipcioAbade Marcos, O Egípcio1
abade-macario-da-cidadeAbade Macário, Da Cidade3
abade-niloAbade Nilo10
abade-nisterooAbade Nisterôo5
abade-nisteroo-o-cenobitaAbade Nisterôo, O Cenobita2
abade-niconAbade Nicon1
abade-netrazAbade Netraz1
abade-nicetasAbade Nicetas1
abade-xoioAbade Xoio2
abade-xantiasAbade Xântias3
abade-olimpioAbade Olímpio2
abade-orsisioAbade Orsísio2
abade-poimemAbade Poimém149
Total — 92 autores721

Exemplos de uso

JavaScript / fetch

// Buscar os versículos de Gênesis capítulo 1
fetch("https://oraetlabora.com.br/api/biblia/gn/1")
  .then(res => res.json())
  .then(data => {
    console.log(data.livro, "—", "Capítulo", data.capitulo);
    data.versiculos.forEach(v => {
      console.log(`v.${v.numero}: ${v.texto}`);
    });
  });

// Buscar um capítulo dos Diálogos de São Gregório
fetch("https://oraetlabora.com.br/api/dialogos/1")
  .then(res => res.json())
  .then(data => console.log(data.titulo, "—", data.paragrafos.length, "parágrafos"));

Python

import requests

# Listar o Prólogo e os capítulos da Regra de São Bento
r = requests.get("https://oraetlabora.com.br/api/regra")
data = r.json()
print(f"{data['total']} capítulos")
for cap in data['capitulos'][:5]:
    print(f"Cap. {cap['numero']}: {cap['titulo']}")

cURL

# Versículos de Gênesis 1
curl https://oraetlabora.com.br/api/biblia/gn/1

# Buscar na Regra de São Bento
curl "https://oraetlabora.com.br/api/regra/busca?q=humildade"

# Apoftegmas de um padre do deserto
curl https://oraetlabora.com.br/api/apoftegmas/abade-antao

PHP

<?php
// Buscar os apoftegmas de um padre do deserto
$response = file_get_contents("https://oraetlabora.com.br/api/apoftegmas/abade-antao");
$data = json_decode($response, true);
echo $data['nome'] . "\n";
echo $data['apoftegmas'][0]['texto'];

// Buscar um capítulo dos Diálogos
$response = file_get_contents("https://oraetlabora.com.br/api/dialogos/1");
$data = json_decode($response, true);
echo $data['titulo'] . "\n";
foreach ($data['paragrafos'] as $p) {
    $speaker = $p['interlocutor'] ?? 'Narrador';
    echo "[$speaker] " . $p['texto'] . "\n";
}

Tipos TypeScript

Tipos para consumir a API com TypeScript. Copie e cole no seu projeto.

Tipos das respostas

/** Tipos de TODOS os endpoints JSON — espelham openapi/openapi.yaml. */

/** Base de todas as respostas */
interface OraEtLaboraResponse {
  fonte: string;
}

interface Versiculo {
  numero: number;
  texto: string;
}

/* ── Bíblia ─────────────────────────────────────────────── */

/** GET /api/biblia */
interface BibliaListResponse extends OraEtLaboraResponse {
  total_livros: number;
  antigo_testamento: BibliaLivro[];
  novo_testamento: BibliaLivro[];
}

interface BibliaLivro {
  abbrev: string;
  nome: string;
  capitulos: number;
}

/** GET /api/biblia/:livro */
interface BibliaLivroResponse extends OraEtLaboraResponse, BibliaLivro {}

/** GET /api/biblia/:livro/:capitulo */
interface BibliaCapituloResponse extends OraEtLaboraResponse {
  livro: string;
  abbrev: string;
  capitulo: number;
  versiculos: Versiculo[];
}

/* ── Regra de São Bento ─────────────────────────────────── */

/** GET /api/regra */
interface RegraListResponse extends OraEtLaboraResponse {
  total: number;
  capitulos: { numero: number; titulo: string; versiculos: number }[];
}

/** GET /api/regra/:capitulo */
interface RegraCapituloResponse extends OraEtLaboraResponse {
  numero: number;
  titulo: string;
  versiculos: Versiculo[];
}

/** GET /api/regra/busca?q= */
interface RegraBuscaResponse extends OraEtLaboraResponse {
  query: string;
  total: number;
  resultados: {
    capitulo: number;
    titulo: string;
    versiculo: number;
    texto: string;
  }[];
}

/* ── Diálogos de São Gregório ───────────────────────────── */

/** GET /api/dialogos */
interface DialogosListResponse extends OraEtLaboraResponse {
  total: number;
  capitulos: { numero: number; titulo: string; paragrafos: number }[];
}

/** GET /api/dialogos/:capitulo */
interface DialogosCapituloResponse extends OraEtLaboraResponse {
  numero: number;
  titulo: string;
  paragrafos: {
    numero: number;
    interlocutor: "Gregório" | "Pedro" | null;
    texto: string;
  }[];
}

/* ── Apoftegmas ─────────────────────────────────────────── */

/** GET /api/apoftegmas */
interface ApoftegmasListResponse extends OraEtLaboraResponse {
  total_autores: number;
  total_apoftegmas: number;
  autores: { id: string; nome: string; apoftegmas: number }[];
}

/** GET /api/apoftegmas/:padre */
interface ApoftegmasAutorResponse extends OraEtLaboraResponse {
  id: string;
  nome: string;
  total: number;
  apoftegmas: Versiculo[];
}

/* ── Calendário Litúrgico ───────────────────────────────── */

interface Celebracao {
  data: string;
  nome: string;
  tipo: string;
  cor: string;
  tempo: string;
}

/** GET /api/calendario */
interface CalendarioResponse extends OraEtLaboraResponse {
  ano_liturgico: string;
  ciclo_dominical: string;
  ciclo_ferial: string;
  tempos: {
    id: string;
    nome: string;
    cor: string;
    inicio: string;
    fim: string;
  }[];
  total_celebracoes: number;
  celebracoes: Celebracao[];
}

/** GET /api/calendario/hoje */
interface CalendarioHojeResponse extends OraEtLaboraResponse {
  data: string;
  tempo_liturgico: string;
  cor_liturgica: string;
  celebracao: Celebracao | null;
  proximo_evento: { data: string; nome: string; tipo: string } | null;
}

/** GET /api/calendario/:mes */
interface CalendarioMesResponse extends OraEtLaboraResponse {
  mes: number;
  nome: string;
  total: number;
  celebracoes: Celebracao[];
}

/* ── Serviço (/api/v1) ──────────────────────────────────── */

/** GET /api/v1/meta */
interface MetaResponse extends OraEtLaboraResponse {
  name: string;
  version: string;
  updated_at: string;
  base_url: string;
  docs: string;
  resources: {
    biblia: { livros: number; versiculos: number };
    regra: { capitulos: number; versiculos: number };
    dialogos: { capitulos: number };
    apoftegmas: { total: number };
    graduale: { celebracoes: number; pecas: number };
  };
}

/** GET /api/v1/health */
interface HealthResponse extends OraEtLaboraResponse {
  status: "ok";
  at: string;
}

/* ── Erro ───────────────────────────────────────────────── */

/** Erro da API (JSON — exceto /api/graduale/folheto, que usa text/plain) */
interface OraEtLaboraError {
  erro: string;
  /** Presente apenas no 429, ex.: "60 requisições por minuto" */
  limite?: string;
  fonte: string;
}

Notas e particularidades

  • Regra de São Bento: o Prólogo é o capítulo 0. Capítulos de 1 a 73.
  • Diálogos: o Prefácio é o capítulo -1, o Prólogo é 0. Capítulos de 1 a 38.
  • Salmos: o livro de Salmos (sl) tem 150 capítulos. É o maior da Bíblia.
  • Rate limit: a API pública permite 60 requisições por minuto por IP. Requisições autenticadas com x-api-key têm limite ampliado de 600 requisições por minuto. O folheto do Graduale tem limite próprio de 4 requisições por minuto, mesmo com API key. Toda resposta traz os headers X-RateLimit-*; ao receber 429, aguarde o tempo indicado em Retry-After.
  • Cache: conteúdo estático (Bíblia, Regra, Diálogos, Apoftegmas) tem cache de 24h no navegador e 7 dias na CDN. Calendário litúrgico: 1h no navegador e 24h na CDN. Folheto do Graduale: 1h.
  • Abreviações bíblicas: a API aceita abreviações em maiúsculas ou minúsculas (Gn = gn).

Termos de uso

Uso público aberto

A API do Ora et Labora é aberta para uso em projetos de caráter catequético, devocional e educacional.

Ao utilizar a API, você concorda com as seguintes condições:

  1. Atribuição obrigatória: cite “Ora et Labora (oraetlabora.com.br)” como fonte dos dados em qualquer projeto que utilize a API.
  2. Sem garantia: a API é oferecida “como está”, sem garantias de disponibilidade contínua.
  3. Uso responsável: a API pública tem limite de 60 requisições por minuto por IP. Se precisar de acesso em volume, entre em contato.
  4. Respeito ao conteúdo: os textos sagrados devem ser utilizados com respeito à sua natureza religiosa.

Uso licenciado — Anjo Comunicação

A API pode ser consumida por produtos e serviços da Anjo Comunicação e seus clientes diretos (como sites paroquiais) mediante acordo de licenciamento.

  1. Autenticação: requisições licenciadas devem incluir o header x-api-key com a chave fornecida pela equipe do Ora et Labora.
  2. Limite ampliado: requisições autenticadas têm limite de 600 req/min, em vez das 60 req/min do acesso público. O folheto do Graduale mantém o limite próprio de 4 req/min mesmo com API key.
  3. Atribuição: não é obrigatório exibir atribuição visível ao usuário final, mas o crédito “Ora et Labora” deve constar no rodapé ou na página “Sobre” do site.
  4. Escopo: a licença cobre todos os endpoints de conteúdo (Bíblia, Regra, Apoftegmas, Diálogos, Graduale Romanum e Calendário Litúrgico).

Para solicitar uma API key, entre em contato pelo e-mail contato@oraetlabora.com.br.

Dúvidas ou sugestões sobre a API?