Resumen
Las consultas públicas no requieren una clave API. Devuelven información publicada de organizaciones y grupos, sin datos personales de padres o niños.
Esta documentación cubre la lectura del catálogo. La gestión de organizaciones, las listas de inscritos y las decisiones sobre solicitudes requieren autorización y quedan fuera de esta API pública.
Primera consulta
Busca una actividad y limita la respuesta. Utiliza los ID devueltos para consultar una organización o una publicación concreta.
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=es'El contrato describe los endpoints públicos de esta integración. Utiliza los campos y códigos de respuesta que define.
Endpoints
| Método | Ruta | Qué devuelve |
|---|---|---|
| GET | /api/v1/search | Búsqueda ordenada con filtros y paginación. |
| GET | /api/v1/catalog | Catálogo público de organizaciones. |
| GET | /api/v1/organizations/{organizationId} | Ficha pública de una organización y sus grupos publicados. |
| GET | /api/v1/offerings | Publicaciones actuales; acepta organizationId, age, city, text y after. |
| GET | /api/v1/offerings/{publicationId} | Una publicación actual identificada por publicationId. |
| GET | /api/v1/openapi.json | Contrato OpenAPI para lectura pública. |
Búsqueda y filtros
La edad, los días y la hora deben corresponder al mismo grupo publicado. Los días usan números de 0 (domingo) a 6 (sábado); varios días significan «cualquiera de ellos».
| Parámetro | Uso |
|---|---|
q | Texto libre: actividad, nombre del grupo u organización. |
age | Edad de 0 a 18 años, dentro del intervalo inclusivo del grupo. |
city / neighborhood | Ciudad y barrio de la sede. |
days | Días separados por comas, por ejemplo 2,4. |
period | manha (mañana), tarde (tarde) o noite (noche). |
after17 | true para horarios a partir de las 17:00. |
locale | pt-BR, ru, en o es para los textos de interfaz. |
limit / cursor | Hasta 50 resultados; reutiliza el cursor con los mismos filtros. |
Uso de los datos
- Conserva organizationId, publicationId y version. No sustituyas un grupo modificado o retirado por otro sin avisar.
- Muestra la dirección y las condiciones del grupo elegido. No uses el precio ni el horario de otra sede.
- Respeta freshness.checkedAt y freshness.validUntil en las publicaciones. Consulta la publicación de nuevo antes de dirigir a la familia al formulario.
- Un grupo publicado y un enlace al formulario no confirman disponibilidad. La organización debe confirmar la solicitud.
- La búsqueda devuelve una selección ordenada, no todo el catálogo. Conserva unresolvedConstraints y resultScope; usa nextCursor cuando exista. No presentes el total como exhaustivo.
El formulario OiAir envía una solicitud a la organización. El envío no reserva una plaza. Esta conexión de lectura no envía solicitudes ni confirma inscripciones.
Respuestas y errores
Indica de forma explícita cuándo faltan datos. No completes condiciones desconocidas ni reutilices un grupo retirado.
| HTTP | Uso |
|---|---|
400 | Parámetro o filtro inválido: corrige la consulta. |
404 | Organización o publicación no disponible: busca de nuevo. |
409 | El catálogo o la versión cambió: descarta el cursor anterior y consulta de nuevo. |
410 | El cursor caducó: inicia una nueva búsqueda. |
503 | La búsqueda o el catálogo no está disponible temporalmente: inténtalo más tarde. |
Integración y versiones
Consulta ejemplos de conexión y el historial de versiones en GitHub. Revisa los metadatos del servidor en MCP Registry.
Siguiente paso
¿Estás creando un agente? Usa el servidor MCP para acceder a los mismos datos mediante herramientas.