OpenAPI спецификации API Retail Rocket
У каждого API Retail Rocket есть описание в формате OpenAPI — открытом стандарте машиночитаемого описания REST API.
Что такое OpenAPI
OpenAPI описывает HTTP API целиком: список эндпоинтов, методы, параметры, форматы запросов и ответов, коды ошибок и модели данных. Один такой файл одинаково понятен и человеку, и инструментам — на его основе работают генераторы кода, Postman, Swagger, а также его понимают современные ИИ-агенты.
Из этой спецификации собраны интерактивные справочники в текущей документации, и ее же можно скачать отдельным файлом или передать ИИ-ассистенту, чтобы быстрее разобраться с интеграцией.
Для кого эта статья
Эта статья будет полезна, если вы:
- отвечаете за запуск Retail Rocket на стороне интернет-магазина, маркетплейса или любого другого e-commerce проекта;
- ставите задачи внутренней или внешней команде разработки;
- хотите быстрее оценить объём интеграции;
- согласуете технические требования с подрядчиком;
- хотите передать разработчикам понятную спецификацию;
- используете ИИ-ассистентов, чтобы быстрее разобраться в технической документации;
Если коротко: OpenAPI поможет быстрее разобраться, какие данные нужно передавать в Retail Rocket, какие запросы поддерживаются, какие параметры обязательны и как сократить количество вопросов между бизнесом, интегратором и разработчиками.
Зачем это бизнесу и менеджерам
На первый взгляд OpenAPI выглядит как инструмент только для разработчиков. Но на практике он помогает всей команде, которая участвует в запуске интеграции.
1. Быстрее поставить задачу разработчикам
Вместо длинного описания в задаче можно дать разработчику:
- ссылку на страницу API;
- ссылку на OpenAPI-файл;
- короткое описание бизнес-сценария.
Разработчик сразу видит структуру запросов, параметры и ожидаемые ответы.
2. Проще подключать подрядчиков
Если интеграцию делает внешняя команда, OpenAPI-файл можно передать подрядчику вместе с постановкой задачи. Это упрощает коммуникацию: подрядчик получает не пересказ требований, а формальное описание API.
3. Быстрее разбирать API с помощью ИИ
OpenAPI-файл можно передать ИИ-агенту: ChatGPT, Claude, Gemini и т.д.
Агент поможет:
- объяснить назначение эндпоинтов простыми словами;
- собрать примеры запросов;
- подсказать, какие параметры обязательны;
- подготовить черновик задачи для разработчиков;
- помочь менеджеру проверить, все ли данные есть у команды для старта интеграции.
Спецификации API Retail Rocket
В таблице — ссылки на файл спецификации в формате JSON: это исходный формат, в котором мы храним описание API. Если нужен формат YAML, откройте соответствующую страницу документации нужного API — в его верхней панели есть встроенная кнопка скачивания, которая отдаёт спецификацию и в JSON, и в YAML.
| API | Документация | Спецификация | Открыть в ИИ |
|---|---|---|---|
| Retail Rocket: Core | Открыть | JSON | Claude · ChatGPT |
| Retail Rocket: Recoms | Открыть | JSON | Claude · ChatGPT |
| Sailplay | Открыть | JSON | Claude · ChatGPT |
| Smart Placement | Открыть | JSON | Claude · ChatGPT |
| Rocket Search | Открыть | JSON | Claude · ChatGPT |
| Rocket Listing | Открыть | JSON | Claude · ChatGPT |
| Push-уведомления | Открыть | JSON | Claude · ChatGPT |
Как использовать OpenAPI на практике
Сценарий 1. Быстро разобраться в API с помощью ИИ
Спецификацию удобно передать ИИ-ассистенту (ChatGPT, Claude, Gemini и другим): он поможет разобраться с эндпоинтами, соберёт примеры запросов и подскажет по интеграции. Есть два способа:
- Быстрые ссылки. Ссылки «Claude» и «ChatGPT» в таблице выше открывают новый чат с готовым запросом, который ссылается на нужную спецификацию — ассистент загрузит её сам.
- Файл вручную. Скачайте файл спецификации и приложите его к диалогу с любым ИИ-ассистентом.
Сценарий 2. Передать задачу разработчикам
Скопируйте ссылку на нужную документацию и JSON-файл спецификации, затем добавьте короткое описание бизнес-задачи.
ИИ-ассистент может ошибаться или работать с неполной версией спецификации. Сверяйте сгенерированные запросы с интерактивным справочником и документацией.