Введение и начало работы

Документация Ozon Delivery API

В документе описаны методы Ozon Delivery API для Ozon Доставки для бизнеса.
Подробнее об Ozon Доставке для бизнеса в Базе знаний продавца

Рабочая среда: https://api-delivery.ozon.ru/.

Введение#

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

С помощью Ozon Delivery API можно:

• проверять доступность доставки для покупателя;
• рассчитывать предварительные сроки и стоимость доставки, а также стоимость страховки;
• создавать заказы с одним или несколькими отправлениями;
• подтверждать готовность отправлений к отгрузке, генерировать этикетки;
• получать информацию об отправлениях, историю статусов;
• отменять отправления;
• отслеживать возвраты, скачивать штрихкоды для их получения.

Готовится к релизу#

Разделы ниже закомментированы в исходной спецификации Ozon: функциональность объявлена, но ещё не выпущена. Приведены как индикатор планов — в рабочем API этих методов и статусов пока нет.

• создавать методы доставки и управлять ими;
• выбирать точки отгрузки и получения возвратов;
• формировать грузоместа для доверительной приёмки;

Создание приложения#

Ozon Delivery API работает через OAuth-токен в частном приложении. Для подключения создайте приложение:

1. В личном кабинете Ozon Доставки в разделе Настройки → Управление частными приложениями нажмите Создать.
2. Выберите уровни доступа приложения к API:
   • delivery-api.delivery — методы для проверки доступности доставки и сроков;
   • delivery-api.delivery-point — методы для получения информации по пунктам выдачи;
   • delivery-api.order — методы для оформления заказа;
   • delivery-api.posting — методы для работы с отправлениями;
   • delivery-api.return — методы для работы с возвратами;
   • delivery-api.all — все методы.
3. Нажмите Создать.

В строке с приложением нажмите и скопируйте client_id и client_secret. Используйте их для авторизации в API.

Вы также можете выдать доступ разработчикам для управления частным приложением.
Подробнее о выдаче доступа

Авторизация#

Чтобы получить OAuth-токен, отправьте POST-запрос по ссылке https://xapi.ozon.ru/oauth/token с обязательными параметрами:

• client_id — уникальный идентификатор OAuth-клиента;
• client_secret — секретный ключ OAuth-клиента;
• grant_type = client_credentials — тип гранта c прямой авторизацией;
• scope — массив с уровнями доступа к API.

Если запрос выполнен успешно, Ozon возвращает ответ в JSON-формате с токеном доступа access_token. С ним вы можете обращаться к методам API.

Защита от DDoS-атак#

Серверы Ozon защищены модулем testcookie. Для успешного взаимодействия с API приложение должно корректно обрабатывать редиректы:

1. При вызове метода модуль перехватывает входящий HTTP-запрос для проверки.
2. Сервер отправляет клиенту HTTP-редирект с кодом 302 или 307 с заголовками Location и Set-Cookie.
3. Клиент выполняет запрос с тем же телом по пути из заголовка Location, приложив Cookie из заголовка Set-Cookie.
4. Клиент сохраняет значение заголовка Set-Cookie и использует его для последующих запросов к API.
5. Последующие запросы работают без редиректа при наличии указанных Cookie в запросе.

Значение Set-Cookie является уникальным, зашифрованным и может измениться без уведомления. В некоторых случаях при отсутствии Cookie в запросе сервер может позволить сделать вызов без редиректа, а в некоторых всегда отвечает редиректом до получения корректных Cookie.

Работа с API#

Рабочая среда: https://api-delivery.ozon.ru/.

Шаблон запроса:

curl -X POST https://api-delivery.ozon.ru/{эндпоинт метода Ozon Delivery API} \
-H "Authorization: Bearer ACCESS_TOKEN"

Пример работы с API на bash#

Переменные окружения

# Укажите ваш CLIENT_ID.
export CLIENT_ID="..." 

# Укажите ваш CLIENT_SECRET.
export CLIENT_SECRET="..."

# Адрес рабочей среды.
export HOST="api-delivery.ozon.ru"

# Адрес получения токена авторизации.
export AUTH_URL="https://xapi.ozon.ru/oauth/token"

Получить и сохранить токен

curl -sL -c ~/.b2c_cookies -b ~/.b2c_cookies -X POST "$AUTH_URL" \
  -H "Content-Type: application/json" \
  -d "{\"client_id\":\"$CLIENT_ID\",\"client_secret\":\"$CLIENT_SECRET\", \"grant_type\": \"client_credentials\", \"scope\": [ \"delivery-api.delivery\", \"delivery-api.delivery-point\", \"delivery-api.order\", \"delivery-api.posting\" ]}" \
  | jq -r '.access_token' > ~/.b2c_token
  
cat ~/.b2c_token

Результат:

eyJhbGciOU73Dutst9_0eoU73Dutst9_cDBM0VmkL0W1I6RGDcYM41M6bkFMx3-1lSZ-SjfOh2_ZGguYPQcRA...

Пример вызова метода

# Номер телефона покупателя для проверки.
export PHONE_NUMBER="+7..."

curl -sL -c ~/.b2c_cookies -b ~/.b2c_cookies -X POST "https://$HOST/v1/delivery/check-client" \
  -H "Authorization: Bearer $(cat ~/.b2c_token)" \
  -H "Content-Type: application/json" \
  -d "{\"phone_number\": \"$PHONE_NUMBER\"}"

Результат:

{"can_be_delivered":true}%