Visão geral
As consultas públicas não exigem chave de API. Elas retornam dados publicados de organizações e turmas, sem dados pessoais de pais ou crianças.
Esta documentação cobre a leitura do catálogo. Gestão de organizações, listas de inscritos e decisões sobre solicitações exigem autorização e não fazem parte desta API pública.
Primeira consulta
Busque uma atividade e limite a resposta. Use os IDs retornados para consultar a organização ou uma publicação específica.
curl --get 'https://oiair.com.br/api/v1/search' \
--data-urlencode 'q=desenho' \
--data-urlencode 'age=6' \
--data-urlencode 'city=Florianópolis' \
--data-urlencode 'limit=5' \
--data-urlencode 'locale=pt-BR'O contrato descreve os endpoints públicos desta integração. Use os campos e códigos de resposta definidos nele.
Endpoints
| Método | Caminho | O que retorna |
|---|---|---|
| GET | /api/v1/search | Busca ordenada com filtros e paginação. |
| GET | /api/v1/catalog | Catálogo público de organizações. |
| GET | /api/v1/organizations/{organizationId} | Ficha pública de uma organização e suas turmas publicadas. |
| GET | /api/v1/offerings | Publicações atuais; aceita organizationId, age, city, text e after. |
| GET | /api/v1/offerings/{publicationId} | Uma publicação atual, identificada por publicationId. |
| GET | /api/v1/openapi.json | Contrato OpenAPI para leitura pública. |
Busca e filtros
Na busca, idade, dias e horário precisam corresponder à mesma turma publicada. Dias usam números de 0 (domingo) a 6 (sábado); vários dias significam “qualquer um”.
| Parâmetro | Uso |
|---|---|
q | Texto livre: atividade, nome da turma ou organização. |
age | Idade de 0 a 18 anos, dentro do intervalo inclusivo da turma. |
city / neighborhood | Cidade e bairro da unidade. |
days | Dias separados por vírgula, por exemplo 2,4. |
period | manha, tarde ou noite. |
after17 | true para horários a partir das 17h. |
locale | pt-BR, ru, en ou es para os textos de interface. |
limit / cursor | Até 50 resultados; reutilize o cursor com os mesmos filtros. |
Como usar os dados
- Mantenha organizationId, publicationId e version. Uma turma substituída ou retirada não deve ser trocada por outra silenciosamente.
- Mostre o endereço da unidade e as condições daquela turma. Não use o preço ou horário de outro endereço.
- Respeite freshness.checkedAt e freshness.validUntil nas publicações. Reconsulte a publicação antes de encaminhar a família.
- Uma turma publicada e o link do formulário não confirmam disponibilidade. A organização precisa confirmar a solicitação.
- A busca retorna uma seleção ordenada, não todo o catálogo. Preserve unresolvedConstraints e resultScope; use nextCursor quando houver. Não apresente o total como exaustivo.
O formulário OiAir envia uma solicitação à organização. Seu envio não reserva uma vaga. Esta conexão de leitura não envia solicitações nem confirma inscrições.
Respostas e erros
Trate a indisponibilidade de forma explícita. Não complete condições desconhecidas nem reutilize uma turma retirada.
| HTTP | Uso |
|---|---|
400 | Parâmetro ou filtro inválido: corrija a consulta. |
404 | Organização ou publicação indisponível: consulte a busca novamente. |
409 | Catálogo ou versão mudou: descarte o cursor antigo e reconsulte. |
410 | O cursor expirou: reinicie a busca. |
503 | Busca ou catálogo temporariamente indisponível: tente novamente mais tarde. |
Integração e versões
Veja exemplos de conexão e o histórico de versões no GitHub. Consulte os metadados do servidor no MCP Registry.
Próximo passo
Está construindo um agente? Use o servidor MCP para acessar os mesmos dados por ferramentas.