Обзор
Для публичных запросов ключ API не нужен. Ответы содержат опубликованные сведения об организациях и группах, без личных данных родителей и детей.
Эта документация описывает чтение каталога. Управление организациями, списками записанных и решениями по заявкам требует полномочий и не входит в публичный API.
Первый запрос
Найдите занятие и ограничьте число результатов. Используйте полученные ID для чтения организации или конкретной публикации.
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=ru'Контракт описывает публичные эндпоинты этой интеграции. Используйте определённые в нём поля и коды ответов.
Эндпоинты
| Метод | Путь | Что возвращает |
|---|---|---|
| GET | /api/v1/search | Упорядоченный поиск с фильтрами и пагинацией. |
| GET | /api/v1/catalog | Публичный каталог организаций. |
| GET | /api/v1/organizations/{organizationId} | Публичная карточка организации и опубликованные группы. |
| GET | /api/v1/offerings | Текущие публикации; фильтры organizationId, age, city, text и after. |
| GET | /api/v1/offerings/{publicationId} | Текущая публикация с заданным publicationId. |
| GET | /api/v1/openapi.json | Контракт OpenAPI для публичного чтения. |
Поиск и фильтры
Возраст, дни и время в поиске должны подходить одной опубликованной группе. Дни обозначаются числами от 0 (воскресенье) до 6 (суббота); несколько дней означают «любой из».
| Параметр | Использование |
|---|---|
q | Свободный текст: занятие, название группы или организации. |
age | Возраст от 0 до 18 лет в пределах включительного диапазона группы. |
city / neighborhood | Город и район площадки. |
days | Дни через запятую, например 2,4. |
period | manha — утро, tarde — день, noite — вечер. |
after17 | true для занятий с 17:00. |
locale | pt-BR, ru, en или es для текста интерфейса. |
limit / cursor | До 50 результатов; повторяйте cursor с теми же фильтрами. |
Как использовать данные
- Сохраняйте organizationId, publicationId и version. Не подменяйте изменённую или снятую группу другой.
- Показывайте адрес площадки и условия выбранной группы. Не используйте цену или время другого адреса.
- Учитывайте freshness.checkedAt и freshness.validUntil публикации. Перечитайте её перед переходом семьи к форме.
- Опубликованная группа и ссылка на форму не подтверждают свободное место. Заявку должна подтвердить организация.
- Поиск возвращает упорядоченную подборку, а не весь каталог. Сохраняйте unresolvedConstraints и resultScope; используйте nextCursor, если он есть. Не называйте количество результатов исчерпывающим.
Форма OiAir отправляет заявку организации. Отправка не бронирует место. Это подключение для чтения не отправляет заявки и не подтверждает запись.
Ответы и ошибки
Явно сообщайте о недоступности данных. Не додумывайте неизвестные условия и не используйте снятую группу.
| HTTP | Использование |
|---|---|
400 | Некорректный параметр или фильтр: исправьте запрос. |
404 | Организация или публикация недоступна: повторите поиск. |
409 | Каталог или версия изменились: отбросьте старый cursor и перечитайте данные. |
410 | Срок действия cursor истёк: начните поиск заново. |
503 | Поиск или каталог временно недоступен: повторите позднее. |
Подключение и версии
Примеры подключения и история версий — на GitHub. Метаданные сервера можно посмотреть в MCP Registry.
Следующий шаг
Создаёте агента? Сервер MCP даёт доступ к этим же данным через инструменты.