Ozon Delivery API (Ozon Доставка для бизнеса): методы, порядок работы и подводные камни

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

Все методы Delivery API — POST с JSON. Деньги передаются объектом {"amount": "строка", "currency_code": "RUB"}, вес — в граммах, размеры — в миллиметрах, даты — в UTC, телефон — строго +7XXXXXXXXXX. Песочницы нет: api-delivery.ozon.ru — боевой сервер.

Приложение создаётся в кабинете Ozon Доставки: Настройки → Управление частными приложениями. Обязательные права — delivery-api.delivery, delivery-api.delivery-point, delivery-api.order, delivery-api.posting, delivery-api.return. С 16 сентября 2026 года есть ещё delivery-api.shipment-method, delivery-api.dropoff-point и delivery-api.return-point — для данных о методах доставки и пунктах отгрузки и возвратов. Как создать приложение и не ошибиться с белым списком IP — в статье Ключи API.

Токен запрашивается на сервере авторизации. Ключи в примерах условные:

curl -sL --post302 -c cookies.txt -b cookies.txt \
  -X POST https://xapi.ozon.ru/oauth/token \
  -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","delivery-api.return"]}'

1. /v1/delivery/check-client — есть ли у номера аккаунт Ozon (can_be_delivered). Без аккаунта доставка невозможна.
2. /v1/delivery-point/list и /v1/delivery-point/info — справочник пунктов, фоновой задачей.
3. /v1/delivery-point/check-availability — примет ли пункт эту посылку: до 100 пунктов, метод доставки, вес, размеры, объявленная стоимость.
4. /v1/order/checkout — предварительные стоимость доставки, страховка и срок в днях. Без телефона получателя расчёта нет.
5. /v1/order/create — заказ после оплаты. Перед ним повторите checkout с теми же параметрами. В заказе до 100 отправлений, у каждого обязательны описание от 1 до 500 символов и объявленная стоимость — не больше 500 000 ₽.
6. /v1/posting/approve — «собрано». Асинхронно: Ozon проверяет баланс, результат смотрите в /v1/posting/info — ready_for_shipping или forming_failed.
7. /v1/posting/label — этикетка PDF, только в статусе ready_for_shipping.
8. /v1/posting/search и /v1/posting/info — статусы по расписанию.
9. /v1/posting/cancel — отмена до статуса delivered, тоже асинхронно.
10. /v1/return/search, /v1/return/info, /v1/return/download_barcode — возвраты и штрихкод для их получения.

Пример расчёта для посылки 790 г в выбранный пункт (номера условные; ID Ozon — 16-значные числа):

curl -sL --post302 -c cookies.txt -b cookies.txt \
  -X POST https://api-delivery.ozon.ru/v1/order/checkout \
  -H "Authorization: Bearer ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"recipient":{"phone_number":"+70000000000"},"postings":[{"request_id":1,"shipment_method_id":1000000000000000,"declared_value":{"amount":"4480","currency_code":"RUB"},"dimensions":{"weight_g":790,"length_mm":250,"width_mm":100,"height_mm":85}}],"delivery":{"delivery_point":{"delivery_point_id":1000000000000001}}}'

В ответе — results[] с estimated_delivery_cost, estimated_insurance_cost и estimated_delivery_days или с error, если в этот пункт посылку не доставить.

delivery-point/list отдаёт только номера пунктов и номера ваших методов доставки, которыми туда можно отправить, — без адресов, координат и фильтра по городу. В сентябре 2026 года это было 88 337 пунктов на 884 страницах по 100. Подробности приходят из delivery-point/info пачками до 100: около 2 КБ на пункт, примерно 180 МБ на весь справочник. Поэтому справочник хранят в своей базе и обновляют раз в сутки инкрементально: полный проход по list, info — только для новых пунктов и проверенных больше 7 дней назад, удаление пропавших — только после завершённого прохода.

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

Тело ошибки — {"error": {...}, "details": [...]}, в пакетных методах ошибки приходят по каждому элементу в results[].error. Сохраняйте в журнал заголовок x-o3-trace-id: его попросит поддержка Ozon.

Защита от DDoS. Сервер может ответить 302 или 307 с заголовками Location и Set-Cookie. Нужно повторить тот же POST с тем же телом по адресу из Location, приложив cookie, а cookie хранить по хосту и обновлять при каждом новом Set-Cookie. При нашей проверке так ответил уже первый запрос к api-delivery.ozon.ru. В WordPress автоматическое следование перенаправлению нужно отключить: при 302 стандартный HTTP-клиент превращает POST в GET и теряет тело запроса.

«Зависания». С сервера сайта из кейса СКИН ЕТИКА обычный ответ приходит за 50–250 мс, но примерно один запрос из 10–20 принимает соединение и не отдаёт ни байта до таймаута, а повтор сразу проходит. Помогают короткие таймауты в несколько секунд и быстрый повтор. На оформлении заказа таймауты ещё короче, ответы расчёта кэшируются в сессии покупателя, а любая ошибка Ozon просто скрывает способ доставки — оформление заказа не должно падать.

• Уведомлений о статусах — только опрос posting/search и posting/info.
• Товарных позиций — ни артикулов, ни маркировки, ни чеков.
• Тестовой среды — тестовый заказ настоящий, отменяйте его до отгрузки.
• Карты и виджета пунктов выдачи.
• Безопасных чисел для JavaScript: номера Ozon — 16-значные int64, в браузер и JSON для браузера передавайте их строкой.

Документация меняется: 31 августа 2026 года добавили грузоместа, 16 сентября — методы доставки и пункты отгрузки и возвратов. Перед новым этапом сверяйтесь с разделом новостей официальной документации.

Своя интеграция — это справочник, окно выбора пункта, расчёт, заказы, статусы, отмены и возвраты плюс все особенности выше. Если сайт на WordPress и WooCommerce, всё это уже делает плагин Ozon Доставки для WooCommerce: для студий есть лицензия на 5 сайтов, порядок настройки — в инструкции по установке. Для Тильды есть сервис Ozon Доставка для Тильды, для других CMS — интеграция под ключ.