Подключение: ключ и первый запрос

Как получить ключ

1. Откройте «API» в группе «Разработчикам» кабинета и нажмите «Создать ключ».
2. Заполните «Название» и «Действует от имени» — вы либо организация.
3. Отметьте «Разрешения» под задачу интеграции.
4. Скопируйте ключ: он показывается один раз.

Запрос к операции без разрешения ключа отклоняется. Перед истечением ключа выпустите новый, переключите на него интеграцию и нажмите «Отозвать» у прежнего.

Как обращаться

Ключ передаётся заголовком X-API-Key, тело и ответ — JSON. Базовый адрес — https://api.opotopo.com.

curl -H "X-API-Key: $OPOTOPO_API_KEY" \
     https://api.opotopo.com/rest/v1/advertisement/seller/ads

Ограничение частоты

Ответ несёт поля RateLimit-Policy и RateLimit: квота окна, остаток и секунды до сброса. Исчерпание отвечает статусом 429 и заголовком Retry-After — повторяйте не раньше указанного срока.

Ошибки

Ошибка приходит в формате problem+json: status, title, машинный code и, при ошибке полей, карта errors. Ответ 4xx повторять бессмысленно — исправьте запрос; 5xx и сетевые сбои повторяйте с возрастающей паузой.

Справочник операций

Операции со схемами запроса и ответа — «Справочник API» раздела «API», спецификация для генератора клиента — «Скачать спецификацию OpenAPI».