Ключи API Ozon Доставки: как получить Client ID и Client Secret и какие права выдать

Ozon Delivery API — программный интерфейс «Ozon Доставки для бизнеса». Через него сайт получает справочник пунктов выдачи, считает стоимость доставки, создаёт заказы, подтверждает отправления, скачивает этикетки и узнаёт статусы. Чтобы Ozon понимал, от чьего имени идут запросы, в кабинете создаётся частное приложение, и у него есть два ключа:

• Client ID — идентификатор приложения;
• Client Secret — секретный ключ, который нельзя никому показывать.

По этим ключам сайт сам получает у Ozon временный токен доступа: запрос идёт на сервер авторизации xapi.ozon.ru, а дальше все вызовы — на api-delivery.ozon.ru с этим токеном. Токен живёт около часа, плагин обновляет его заранее и сам получает новый, если Ozon ответил, что токен устарел. Ни вам, ни покупателю делать для этого ничего не нужно. Если вы разработчик и пишете свою интеграцию, порядок методов и подводные камни собраны в обзоре Ozon Delivery API.

Все запросы к Ozon идут с сервера сайта на сервер Ozon. Ключи никогда не попадают в браузер покупателя, в код страниц и в журналы плагина.

Приложение создаётся в кабинете Ozon Доставки, а не в кабинете продавца маркетплейса. Если кабинеты объединены, переключитесь на «Доставку» кнопкой рядом с названием магазина.

1. Откройте Настройки → Управление частными приложениями и нажмите «Создать».
2. Задайте название, например «Сайт магазина», и отметьте уровни доступа — список ниже.
3. Нажмите «Создать». В строке приложения появится значок ключа.
4. Нажмите на значок и скопируйте Client ID и Client Secret.

Права определяют, какие группы методов API доступны приложению. Плагину нужны пять обязательных прав и желательно ещё три — для удобных экранов в админке.

Без желательных прав плагин работает, но в настройках вместо названия метода и адресов пунктов вы увидите только номера. При проверке подключения плагин сначала просит у Ozon все права, а если Ozon отказывает в дополнительных, работает с обязательными.

В настройках приложения можно включить белый список IP — тогда Ozon принимает запросы с ключами только с перечисленных адресов. Это хорошая защита на случай утечки ключей, но здесь часто ошибаются.

Указывать нужно исходящий IP-адрес сервера, на котором работает сайт: именно с него плагин отправляет запросы в Ozon. Его знает хостинг — напишите в поддержку: «Какой исходящий IP у моего сайта для запросов во внешние API?». Этот адрес может не совпадать с IP, который вы используете для SSH или FTP, и с адресом из DNS-записи домена: на одном из наших проектов адрес для SSH и исходящий адрес сервера были разными.

Если вы включили белый список и указали не тот адрес, проверка подключения в плагине не пройдёт: Ozon отклонит запрос. Если переезжаете на другой хостинг или сервер, сначала добавьте новый адрес в список, а потом переносите сайт.

1. В админке WordPress откройте WooCommerce → Ozon Доставка, вкладку «Подключение».
2. Вставьте Client ID и Client Secret в соответствующие поля.
3. Нажмите «Сохранить и проверить подключение».

Плагин сразу запрашивает у Ozon токен и пробует прочитать данные кабинета. Если всё в порядке, в чек-листе готовности строка «Ключи приложения Ozon Доставки» становится выполненной, а «Подключение к Ozon» показывает «Ozon принимает ключи» и время проверки. Следующий шаг — выбрать метод доставки, об этом в статье Метод доставки. Весь порядок настройки — в инструкции.

Иногда Ozon отвечает не сразу: примерно один запрос из 10–20 «зависает» без ответа. Плагин ставит короткие таймауты и сразу повторяет такой запрос, поэтому единичные сетевые предупреждения в журнале — это нормально. Подробнее о том, как их отличать от настоящих проблем, — в статье Частые ошибки и решения.

Ozon использует защиту от DDoS: на запрос сервер иногда отвечает перенаправлением и просит повторить его с cookie. Плагин делает это сам, поэтому в настройках хостинга ничего менять не нужно.

• Вставляйте ключи только в настройки плагина. Плагин хранит их в базе вашего сайта, в настройках без автозагрузки. В журналах, письмах и коде страниц ключей нет.
• Не пересылайте ключи в мессенджерах и открытым текстом по почте. Если ключи нужно передать разработчику, используйте одноразовую ссылку, менеджер паролей или зашифрованный архив с паролем, отправленным по другому каналу.
• Не используйте одни ключи на нескольких сайтах без необходимости. Для каждого сайта удобнее отдельное приложение: так проще понять, откуда идут запросы, и отключить доступ одному сайту.
• Включите белый список IP, если хостинг даёт постоянный исходящий адрес.

Доступ к самому кабинету Ozon Доставки для работы плагина не нужен: достаточно ключей приложения.