Яндекс Доставка: интеграция и ограничения

TL;DR: Яндекс Доставка — оператор с тремя типами доставки (курьер, ПВЗ, постаматы) и API, построенным вокруг расчёта, сценария «создание → подтверждение» и виджета для витрины. Ключевые вещи, которые надо понимать до интеграции: подтверждение создания асинхронное, оплата при получении имеет ограничения, а проблемная отгрузка оператора — не то же самое, что клиентский возврат.

Назначение

Яндекс Доставка используется как один из каналов контура логистики: она закрывает посылочную доставку B2C — от мелких отправлений в постамат до курьерской доставки до двери. Интеграция вписывается в общий сквозной процесс, описанный в интеграции доставки.

Продукт: типы доставки

Тип	Сценарий	Особенности
Курьерская	Доставка до адреса покупателя	Интервалы вручения, забор со склада магазина
ПВЗ	Выдача в пункте выдачи	Выбор точки на витрине, срок хранения до получения
Постамат	Выдача в автоматическую ячейку	Только мелкогабаритные отправления

Один оператор — разные продукты: тарифы, ограничения по весогабаритам и процесс могут отличаться между типами доставки, поэтому на витрине их нельзя смешивать в один вариант «доставка».

Возможности API

Возможность	Что даёт
Pricing calculator (расчёт)	Тариф и срок по параметрам отправления — вход в checkout и в варианты доставки
Сценарий offers/create → offers/confirm	Создание отправления и его подтверждение; подтверждение приходит асинхронно, после запроса
Ярлыки	Печатные формы для наклейки на упаковку
Акты	Документы по партиям отправлений для сверки с оператором
История статусов	Полная трек-история отправления для трансляции покупателю
Виджет для витрины	Готовый элемент интерфейса на витрине магазина

Практические следствия для реализации:

Асинхронное подтверждение. Запрос confirm не гарантирует мгновенный результат: система должна хранить состояние «создано, ждём подтверждения» и обрабатывать итог позже.
Идентификатор оффера. Расчёт возвращает оффер, на который ссылается создание отправления; использовать устаревший оффер рискованно, лучше пересчитать.
Виджет или собственный UI. Виджет закрывает витринный сценарий быстрее, собственный UI нужен при нестандартном checkout.

Сценарий интеграции по шагам

Шаг	API-этап	Что проверяет магазин
Расчёт	Pricing calculator	Тариф и срок вписываются в обещание витрине
Создание	offers/create	Данные отправления (точка выдачи, габариты) приняты
Подтверждение	offers/confirm	Стоимость подтверждена оператором; статус приходит асинхронно
Ярлык	Печатные формы	Наклейка на упаковку до передачи оператору
Сдача	Забор или сдача на склад	Отправления в реестре оператора
Трекинг	История статусов	Трансляция в единый внутренний статус
Сверка	Акты	Фактические отправления против выставленного счёта

Сценарий вписывается в сквозной процесс из интеграции доставки; таблица выше — его проекция на возможности API конкретно Яндекс Доставки.

Три детали, которые легко упустить в реализации:

Срок жизни оффера. Создание отправления должно ссылаться на свежий оффер; долгий разрыв между расчётом и созданием — типичный источник расхождения тарифа.
Подтверждение по итогу, не по времени. Отправление считается подтверждённым по приходу статуса, а не по прошествии «обычного» срока ожидания.
Разделение ролей виджета и сервера. Виджет решает выбор точки и сроков на витрине, серверная логика отвечает за создание и статусы; подмена одного другим ломает checkout.

Ограничения

Оплата при получении имеет ограничения; актуальные условия (для каких типов доставки и регионов доступна, какие категории товаров) проверяйте в документации для бизнеса до выбора модели оплаты. Если предоплата обязательна, вопрос «оплата при получении» снимается с витрины для этого оператора.
Весогабариты ограничивают состав заказа: постамат принимает только мелкие отправления, и один большой заказ может потребовать альтернативного канала.

Маппинг статусов и опыт покупателя

История статусов оператора — источник для витрины, но покупателю нужны не внутренние коды оператора, а понятные состояния и ожидания:

Внутренний статус	Понятно покупателю	Действие магазина
Собран	«Собираем заказ»	Готовить отправление, ярлык
Передан оператору	«Передано в доставку»	Фиксировать расчётный срок вручения
В пути / в пункте выдачи	«Поступило в пункт выдачи»	Напомнить о сроке хранения
Доставлен	«Заказ получен»	Закрыть вручение, запустить пост-продажу
Проблемная отгрузка	«Не удалось получить заказ»	Связаться с покупателем, вернуть товар на склад

Механика перевода статусов оператора в единый внутренний слой описана в технических требованиях интеграции, связь статусов с заказом — в заказах и остатках.

Акты и сверка

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

Проблемная отгрузка против клиентского возврата

Это различие — частая причина путаницы:

Невручение до статуса «Доставлен» — проблемная отгрузка оператора: срок хранения ПВЗ истёк, покупатель не открыл дверь, отправление уходит обратно. Она фиксируется в процессах магазина и не является заявленной покупателем причиной возврата.
Клиентский возврат после вручения — отдельный процесс: покупатель получил товар и хочет вернуть. Он проходит по процессу возврата Яндекс Доставки (возврат заказов) и по общим правилам магазина из фулфилмента и возвратов.

Смешивать их нельзя: у них разные триггеры, разные статусы и разное влияние на деньги (жизненный цикл платежа).

Аспект	Проблемная отгрузка (невручение)	Клиентский возврат
Инициатор	Покупатель не забрал / не принял	Покупатель хочет вернуть товар
Когда	До статуса «Доставлен»	После вручения
Товар	Возвращается оператором	Доставка обратно отдельным отправлением
Роль оператора	Фиксирует неудачу вручения	Исполняет обратную отправку по процессу возврата
Деньги	Возврат предоплаты при отмене (платёжный контур)	Возврат средств по решению по заявке

Критерии выбора Яндекс Доставки

Нужны и курьерская доставка, и сеть ПВЗ/постаматов в одном договоре.
Витрине важен готовый виджет выбора точки и сроков.
Основной поток — посылочные отправления с предоплатой, поскольку оплата при получении ограничена (см. выше).
Проект не требует фулфилмента от этого оператора: складская обработка описана отдельно.

Чего Яндекс Доставка не описывает

Фулфилмент — это услуга складской обработки: приёмка, хранение, сборка, упаковка, отгрузка. Не приписывайте сервису фулфилмент Яндекс Маркета без отдельного источника: Яндекс Доставка и сервисы Маркета — разные продукты с разными условиями. Если проекту нужен фулфилмент, см. предложения, где такая услуга заявлена явно (например, у СДЭК), и общее описание складских операций в фулфилменте и возвратах.

Связанные страницы

Обзор контура логистики — карта операторов и критерии выбора канала.
Интеграция доставки — сквозной процесс, в который вписывается API оператора.
Фулфилмент и возвраты — различие проблемной отгрузки и заявленного возврата.
Жизненный цикл платежа — что происходит с деньгами при отмене и невыкупе.

Материалы и источники

Яндекс Доставка для бизнеса — продукты, сценарии и условия работы оператора.
API Яндекс Доставки — расчёт (pricing-calculator), сценарий offers/create → offers/confirm, ярлыки, акты, статусы.
Виджеты для витрины — готовые элементы интерфейса на витрине магазина.
Возврат заказов Яндекс Доставки — процесс клиентского возврата после вручения.