Интеграция: Службы доставки + ЮKassa

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

Типовые системы на этом конце: СДЭК, Boxberry, Почта России, DPD, Яндекс Доставка, 5Post, собственная курьерская служба.

ЮKassa — российский платёжный провайдер: карты, СБП, кошелёк ЮMoney, рассрочка, рекуррентные платежи, чеки и возвраты. Часто закрывает сразу и приём платежей, и фискализацию.

Как с ней работать технически: REST API с идемпотентными ключами, вебхуками по событиям платежа и возврата, отдельной тестовой средой. Есть готовые SDK для PHP и документация по сценариям холдирования и двухстадийной оплаты.

В службу доставки уходят габариты и вес, адрес, состав заказа и объявленная ценность; обратно — тариф, срок, номер отправления, статусы и сумма к оплате при получении.

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

«Службы доставки» и «ЮKassa» отвечают за разные участки процесса, поэтому прямой коннектор между ними нужен не всегда — чаще они сходятся в одной из систем контура. Платёжный провайдер участвует только в денежном контуре: суммы и статусы уходят в платёжную систему, подтверждение приходит вебхуком с подписью. Обязательны проверка подписи, идемпотентность и ежедневная сверка с отчётом провайдера — иначе расхождение обнаружится в конце месяца.

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

Статусы приходят асинхронно и с задержкой, а список пунктов выдачи и тарифы меняются регулярно — их нужно обновлять по расписанию, а не «один раз при запуске». Возврат при невыкупе и корректный возврат денег покупателю — отдельный сценарий, который чаще всего забывают.

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

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

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

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

Сроки обычно определяет не разработка, а согласования: доступы к системе, тестовый контур, договор с провайдером, правила расчёта и требования бухгалтерии. Мы выносим эти пункты в чек-лист подготовки, чтобы они не останавливали работы в середине проекта.

Первый шаг — обследование: смотрим, какие данные уже ведутся, кто владелец каждой сущности и какие ограничения есть у API. Затем делаем прототип обмена на тестовом контуре, проверяем нештатные сценарии (повтор, отмена, частичное выполнение) и только после этого выводим интеграцию в продуктив.

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