Интеграция WooCommerce со СДЭК: доставка и ПВЗ

Когда магазин на WooCommerce начинает получать больше заказов, доставка быстро превращается в отдельный ручной процесс: менеджер копирует адрес, уточняет габариты, выбирает тариф, создаёт отправление, затем вручную переносит трек-номер и следит за статусом.

Интеграция WooCommerce со СДЭК нужна, чтобы связать оформление заказа на сайте с расчётом доставки, выбором ПВЗ, созданием отправления и обновлением статусов. В этой статье — практическая архитектура такой связки, без привязки к одному конкретному плагину.

Архитектура интеграции WooCommerce и СДЭК

Корзина и checkoutWooCommerce передаёт состав заказа, вес, габариты и адрес покупателя.
Расчёт доставкиИнтеграционный слой запрашивает доступные варианты доставки и рассчитывает стоимость.
Выбор ПВЗ или курьераПокупатель выбирает подходящий способ получения до оформления заказа.
Создание отправленияПосле нужного события заказ регистрируется в системе доставки с устойчивым внешним идентификатором.
Статусы и трекингИзменения доставки возвращаются в магазин и отображаются менеджеру или покупателю.

Главный принцип: WooCommerce остаётся источником данных о продаже, а СДЭК — источником данных о доставке. Между ними нужен слой, который хранит соответствия ID, валидирует данные и не создаёт дублей.

Какие задачи имеет смысл автоматизировать

Минимальная полезная интеграция обычно начинается не с «отправить заказ в СДЭК», а с определения, где именно автоматизация экономит ручную работу.

расчёт стоимости доставки до оплаты или оформления заказа;
получение актуального списка пунктов выдачи;
выбор ПВЗ на checkout;
передача веса и габаритов товаров;
создание отправления после нужного статуса заказа;
сохранение идентификатора отправления и трек-номера в заказе WooCommerce;
синхронизация транспортных статусов;
журнал ошибок и повторная отправка при временном сбое.

На официальной странице интеграционного модуля СДЭК для InSales перечислены похожие базовые возможности: расчёт стоимости с учётом габаритов, актуальный список ПВЗ, создание заказа в информационной системе СДЭК и автоматическая синхронизация статусов. Это хороший ориентир для того, что обычно ожидают от интеграции интернет-магазина с доставкой.

Что проверить в WooCommerce до разработки

Вес и габариты товаров

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

Единицы измерения

В WooCommerce можно хранить вес и размеры в разных единицах. Интеграционный код должен приводить их к формату, который ожидает внешняя система. Конвертацию лучше делать централизованно, а не размазывать по шаблонам checkout и обработчикам заказа.

Источник адреса

Для курьерской доставки нужны адресные данные, а для ПВЗ — выбранная точка. Эти два сценария не стоит смешивать в одном текстовом поле. Идентификатор ПВЗ лучше хранить отдельно в метаданных заказа вместе с человекочитаемым адресом.

Как встроить расчёт доставки в checkout

На этапе корзины или оформления заказа интеграция получает содержимое корзины, собирает общий вес и габариты, определяет город или адрес покупателя и запрашивает доступные варианты доставки. Результат преобразуется в методы доставки WooCommerce.

Важно не превращать внешний API в жёсткую зависимость всего checkout. Если транспортный сервис временно отвечает медленно, магазин не должен зависать без объяснения. Для расчёта полезны ограниченный timeout, понятная ошибка пользователю и контролируемый fallback — например, скрыть недоступный метод вместо бесконечного ожидания.

ПВЗ: что хранить после выбора

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

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

Это помогает пережить ситуацию, когда название или справочник изменились после оформления заказа.

Когда создавать отправление в СДЭК

Одна из частых ошибок — отправлять заказ в службу доставки сразу при создании записи WooCommerce. Но новый заказ ещё может не быть оплачен, клиент может вернуться на страницу оплаты, платёжный шлюз может прислать повторный callback, а менеджер — изменить состав заказа.

Триггер лучше выбирать по бизнес-процессу: например, после подтверждённой оплаты или после ручного перевода заказа в согласованный статус. Само событие должно быть идемпотентным: повторный запуск не создаёт второе отправление, если внешний ID уже сохранён.

Webhooks WooCommerce и фоновая обработка

WooCommerce умеет отправлять webhooks при событиях заказов, товаров, клиентов и других сущностей. В настройках webhook указывается URL доставки и секрет, который используется для подписи запроса. WooCommerce также хранит журналы доставок webhook — это удобно для диагностики.

Если интеграция вынесена в отдельный сервис, webhook может быстро принять событие, проверить подпись, положить задачу в очередь и вернуть успешный HTTP-ответ. Тяжёлую работу с внешним API лучше выполнять отдельно от пользовательского запроса checkout.

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

Как не создавать дубли отправлений

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

Практичный подход:

использовать ID заказа WooCommerce как часть внутреннего idempotency key;
до создания отправления проверять сохранённый внешний идентификатор;
после успешного создания сразу фиксировать внешний ID в заказе или отдельной таблице;
при неопределённом результате сначала попытаться найти уже созданную сущность, а не слепо отправлять POST повторно;
вести журнал запросов без секретов и персональных данных сверх необходимого.

Синхронизация статусов: не копируйте их один в один

Статус доставки и статус продажи — разные вещи. «Передано курьеру» не означает, что заказ в WooCommerce должен автоматически стать Completed, а транспортная отмена не всегда означает возврат оплаты.

Лучше сделать явную карту соответствий. Например, часть транспортных статусов только записывается в метаданные и показывается клиенту, а изменение основного статуса WooCommerce происходит только для заранее согласованных событий.

Что делать при ошибках API

Ситуация	Правильная реакция
Временный 5xx или timeout	Повторить задачу с ограниченным retry и увеличивающейся задержкой.
Невалидный адрес или габариты	Не повторять бесконечно; сохранить понятную ошибку для менеджера.
Неизвестный результат создания	Проверить наличие отправления по сохранённому внешнему ключу перед повторным созданием.
Webhook не дошёл	Использовать периодическую сверку как страховочный механизм, если процесс этого требует.

Безопасность интеграции

не передавать API-ключи в JavaScript браузера;
хранить секреты на сервере или в защищённой конфигурации;
проверять подписи входящих webhook, если источник их поддерживает;
ограничивать доступ к служебным endpoint;
не писать токены, пароли и полные персональные данные в обычные debug-логи;
разделять тестовую и рабочую конфигурации.

Если текущий магазин уже сильно кастомизирован, сначала полезно провести аудит и доработку WordPress, а затем подключать доставку. Для магазинов с нестандартной логикой подходит кастомная разработка WooCommerce.

Когда готового плагина достаточно

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

Когда нужна кастомная интеграция

Свой интеграционный слой оправдан, если есть несколько складов, нестандартные правила упаковки, B2B-цены, кастомные статусы, частичные отгрузки, отдельная CRM/ERP или нужно объединить СДЭК с другими службами доставки. Тогда лучше один раз описать модель данных и события, чем наращивать цепочку несвязанных хуков.

Такую работу логично рассматривать как часть автоматизации бизнес-процессов, а не как установку ещё одного плагина.

Чек-лист перед запуском

У всех доставляемых товаров есть корректный вес и габариты.
Определено, какие единицы измерения используются и где выполняется конвертация.
Для ПВЗ сохраняется устойчивый идентификатор, а не только текст адреса.
Определён точный статус WooCommerce, после которого создаётся отправление.
Повторная обработка одного заказа не создаёт дубль.
Есть явная карта транспортных статусов и статусов магазина.
API-секреты находятся только на серверной стороне.
Настроены журнал ошибок и контролируемый retry.
Проверены сценарии отмены, возврата и изменения заказа.
Тестовый заказ пройден от checkout до финального транспортного статуса.

Частые вопросы

Можно ли подключить СДЭК к WooCommerce без собственного сервера?

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

Обязательно ли показывать карту ПВЗ?

Нет. Можно использовать список или поиск по городу. Важно, чтобы выбранный пункт был однозначно идентифицирован и сохранён в заказе.

Когда передавать заказ в службу доставки?

Не существует универсального статуса. Триггер выбирается по процессу магазина: после оплаты, подтверждения менеджером или другого согласованного события.

Почему нельзя просто синхронизировать все статусы один в один?

Потому что транспортный статус описывает движение отправления, а статус WooCommerce — состояние коммерческого заказа. Их семантика различается.

Что делать, если API СДЭК временно недоступен?

Не блокировать бизнес-процесс бесконечным ожиданием. Использовать timeout, журналирование, очередь и ограниченный retry для временных ошибок.

Как защититься от двойного создания отправления?

Хранить внешний ID и использовать идемпотентную обработку: один и тот же заказ при повторном событии должен находить существующее отправление, а не создавать новое.

Вывод

Хорошая интеграция WooCommerce со СДЭК — это не одна кнопка «отправить заказ». Она начинается с качественных данных товара, разделяет продажу и доставку, хранит внешние ID, переживает повторные события и не заставляет менеджера вручную восстанавливать состояние после сбоя.

Если нужно связать доставку с кастомным checkout, CRM или складской логикой, можно описать текущий процесс A.S Groups и спроектировать интеграцию под него.

Официальные источники

Следующий шаг

Нужно решить похожую задачу?

Предложить проектирование или доработку интеграции доставки под нестандартный WooCommerce-магазин.

Обсудить задачу