Войти
  • Каталог
  • Блог
  • Документация
    • Тема оформления
    Войти

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

    Woo & CDEK — интеграция woocommerce с ТК СДЭК

    Полная интеграция WooCommerce с транспортной компанией СДЭК: расчёт доставки через CDEK API v2, выбор пункта выдачи на карте Яндекс прямо на чекауте, оформление отправлений, автообновление статусов по вебхукам, наложенный платёж, трекинг для покупателя.

    Версия 1.2.1  Требует WooCommerce  PHP 7.4+  CDEK API v2

    00О плагине

    «WooCommerce CDEK» подключает магазин к CDEK API v2 и закрывает весь цикл работы с транспортной компанией СДЭК — от расчёта стоимости на чекауте до печати накладной:

    • считает стоимость и сроки доставки СДЭК на чекауте в реальном времени — два варианта: пункт выдачи (ПВЗ) и курьер до двери, тариф каждого типа CDEK подбирает автоматически (самый дешёвый или самый быстрый — по настройке);
    • показывает покупателю интерактивную карту Яндекс с пунктами выдачи СДЭК прямо на чекауте — работает и в классическом, и в блочном (Cart & Checkout Blocks) оформлении заказа;
    • создаёт заказ в СДЭК из заказа WooCommerce — вручную или автоматически по статусу, и автоматически отменяет его, если заказ WooCommerce отменён или возвращён;
    • поддерживает наложенный платёж с гибкой настройкой, кто оплачивает доставку;
    • обновляет статус и трек-номер по вебхукам СДЭК — без опроса вручную;
    • печатает накладную прямо из карточки заказа;
    • показывает покупателю статус и трек-номер в личном кабинете и присылает письмо, когда трек-номер становится доступен.
    Быстрый стартКоротко: установите плагин → активируйте лицензию → на вкладке настроек «СДЭК» укажите Account/Secure password, город отправителя, ключ Яндекс Карт → добавьте способ доставки «СДЭК» в нужную зону WooCommerce → подключите вебхуки одной кнопкой. Товары можно не трогать — если у них не заданы вес/габариты, используются значения по умолчанию из настроек. Подробности — по каждому шагу ниже.

    01Что нужно перед началом

    1. Активный WooCommerce версии 6.0 или новее.
    2. Учётные данные CDEK API v2 — Account (client_id) и Secure password (client_secret), выдаёт СДЭК при подключении интеграции. У CDEK есть отдельный публичный тестовый контур (api.edu.cdek.ru) — можно настроить и проверить плагин ещё до получения боевых данных.
    3. Город и адрес склада-отправителя.
    4. Ключ Яндекс Карт JS API — с включённым JavaScript API и HTTP Геокодером, нужен для карты выбора пункта выдачи на чекауте.
    5. Лицензионный ключ WordPlace — для активации автообновлений плагина.

    02Установка и активация

    1. Скачайте архив плагина из личного кабинета покупателя на WordPlace (вкладка «Мои покупки»).
    2. В админке WordPress: Плагины → Добавить новый → Загрузить плагин, выберите zip-архив, «Установить».
    3. Нажмите «Активировать». Без активного WooCommerce плагин покажет предупреждение и не включится.

    После активации настройки СДЭК появляются отдельной вкладкой внутри стандартных настроек WooCommerce: WooCommerce → Настройки → СДЭК.

    03Активация лицензии

    Раздел «Лицензия» находится в самом низу вкладки настроек WooCommerce → Настройки → СДЭК. Ключ вы получили при покупке плагина на WordPlace — личный кабинет покупателя, вкладка «Лицензии и ключи».

    1. Вставьте ключ (формат XXXXX-XXXXX-XXXXX-XXXXX) и нажмите «Активировать».
    2. Активация привязывает лицензию к текущему домену и открывает автоматические обновления плагина.
    3. Кнопки «Деактивировать» и «Проверить обновления» появляются после активации.
    ВажноБез активной лицензии плагин продолжает работать в полном объёме — ограничивается только доступ к автоматическим обновлениям.

    04Настройка плагина

    Все настройки собраны на одной вкладке — WooCommerce → Настройки → СДЭК, семь разделов подряд.

    Доступ к API СДЭК

    ПолеЧто указать
    Режим API«Тестовый контур» (api.edu.cdek.ru) для проверки или «Боевой контур» (api.cdek.ru) для реальной работы.
    Account (client_id)Выдаётся в личном кабинете СДЭК при подключении интеграции.
    Secure password (client_secret)Выдаётся вместе с Account.

    Ниже — кнопка «Проверить подключение к CDEK API»: сразу показывает, действительны ли введённые учётные данные (получает тестовый токен), не дожидаясь первого реального расчёта на чекауте.

    Отправитель

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

    Адрес склада-отправителя — только улица, дом, офис (например, «ул. Ленина, д. 10, оф. 5»), город указывать не нужно — он берётся из поля выше.

    Упаковка по умолчанию

    Вес (в граммах) и габариты (в сантиметрах), которые плагин подставляет для товаров, у которых не заданы вес и/или габариты в карточке товара. Значения по умолчанию: 500 г, 20×15×10 см.

    Отличие от точного расчётаВ отличие от интеграций, которые вообще отказываются считать доставку без заполненных веса/габаритов, здесь это не обязательно: не заполнили карточку товара — подставится значение по умолчанию из этих полей. Для точного расчёта стоимости всё же лучше указывать реальные вес и габариты в самих товарах.

    Ключ Яндекс Карт

    Ключ Яндекс Карт JS API — API-ключ с включённым JavaScript API и HTTP Геокодером. Нужен для показа карты выбора пункта выдачи на чекауте (см. главу «Выбор пункта выдачи на чекауте»).

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

    Создание заказа в СДЭК

    Создавать заказ в СДЭК при статусе — заказ в CDEK API будет создан автоматически при переходе заказа WooCommerce в выбранный статус (по умолчанию — «Выполняется»). Создать заказ можно и вручную кнопкой в карточке заказа в любой момент — оба способа работают одновременно.

    Автоматически, без настройкиЕсли заказ WooCommerce переходит в статус «Отменён» или «Возвращён», а заказ в СДЭК уже был создан — плагин сам отправляет его отмену в CDEK API. Отдельно включать это не нужно, работает всегда.

    Наложенный платёж

    • Считать наложенным платежом заказы, оплаченные способом — список способов оплаты WooCommerce (по умолчанию — только штатный «Наложенный платёж»). Для заказов с выбранными здесь способами оплаты в СДЭК передаётся сумма к получению с покупателя за товар — курьер соберёт деньги при вручении. Остальные заказы считаются предоплаченными.
    • При наложенном платеже — доставку оплачивает — «Отправитель» (по договору, как обычно) или «Получатель» (курьер добавит стоимость доставки к наложенному платежу). Применяется только к заказам с наложенным платежом; на предоплаченные заказы не влияет — по ним доставку всегда оплачивает отправитель, так как её стоимость уже вошла в оплату на сайте.

    Вебхуки

    Вебхуки позволяют статусу и трек-номеру заказа обновляться автоматически, без ручной кнопки «Обновить статус» в каждом заказе.

    1. На вкладке настроек показан готовый URL вебхука (с уникальным секретным токеном в самой ссылке — так СДЭК подтверждает, что запрос подлинный).
    2. Нажмите «Подключить вебхуки» — плагин сам, через API, подпишется на оба нужных типа событий (изменение статуса заказа и готовность печатной формы). Заходить в личный кабинет СДЭК не нужно.
    3. Кнопка «Проверить текущие подписки» покажет список активных подписок и их URL — полезно, если вебхуки, кажется, перестали приходить.

    05Способ доставки в зонах WooCommerce

    Плагин регистрирует способ доставки «СДЭК». Как и любой другой способ WooCommerce, добавьте его в нужные зоны доставки вручную:

    1. Откройте WooCommerce → Настройки → Доставка, выберите зону (или создайте новую).
    2. «Добавить способ доставки» → выберите «СДЭК».
    3. В настройках метода:Название способа доставки — что видит покупатель (по умолчанию «СДЭК»).Какой тариф предлагать — «Самый дешёвый» или «Самый быстрый». Плагин не даёт выбрать конкретный тариф СДЭК вручную — среди тарифов, которые CDEK API вернул на конкретный расчёт, он сам берёт лучший по этому критерию, отдельно для ПВЗ и отдельно для курьера.Пункт выдачи — предлагать ли самовывоз из ПВЗ, и Название варианта «Пункт выдачи» — как он называется на чекауте.Курьер — предлагать ли доставку до двери, и Название варианта «Курьер» — как он называется на чекауте.
    4. Название способа доставки — что видит покупатель (по умолчанию «СДЭК»).
    5. Какой тариф предлагать — «Самый дешёвый» или «Самый быстрый». Плагин не даёт выбрать конкретный тариф СДЭК вручную — среди тарифов, которые CDEK API вернул на конкретный расчёт, он сам берёт лучший по этому критерию, отдельно для ПВЗ и отдельно для курьера.
    6. Пункт выдачи — предлагать ли самовывоз из ПВЗ, и Название варианта «Пункт выдачи» — как он называется на чекауте.
    7. Курьер — предлагать ли доставку до двери, и Название варианта «Курьер» — как он называется на чекауте.

    06Выбор пункта выдачи на чекауте

    Если покупатель выбирает вариант «Пункт выдачи», на чекауте под способами доставки появляется карта Яндекс с пунктами СДЭК в указанном городе. Работает одинаково в классическом и в блочном (Cart & Checkout Blocks) оформлении заказа — плагин определяет тип чекаута автоматически.

    1. Покупатель кликает по маркеру нужного пункта на карте.
    2. Появляется карточка выбранного ПВЗ — название и адрес, с галочкой подтверждения.
    3. Оформить заказ с выбранным тарифом «Пункт выдачи» без выбранного ПВЗ нельзя — плагин остановит оформление и попросит выбрать точку на карте.

    07Что видит покупатель

    После ввода города доставки на чекауте появляются варианты СДЭК — до двух одновременно, в зависимости от настроек метода в зоне: вариант «Пункт выдачи» (с картой выбора, см. выше) и/или вариант «Курьер» с ценой и сроком доставки до двери.

    После оформления и на странице заказа в личном кабинете покупателя (когда трек-номер уже присвоен) появляется блок «Доставка СДЭК» со статусом и ссылкой на трекинг на сайте cdek.ru.

    08Обработка заказа

    В карточке заказа справа — блок «СДЭК» (показывается только если в заказе выбран способ доставки СДЭК). Пока заказ в СДЭК не создан:

    После создания (вручную или автоматически по статусу) блок показывает статус, UUID заказа СДЭК и трек-номер (ссылкой на трекинг), а также кнопки:

    • «Обновить статус» — подтянуть актуальные данные из СДЭК вручную (обычно не нужно, статус и так обновляется по вебхуку);
    • «Печать накладной» — открывает готовый PDF в новой вкладке;
    • «Отменить заказ в СДЭК» — аннулирует заказ в СДЭК.
    На заметкуНакладная формируется на стороне СДЭК асинхронно. Если сразу после создания заказа нажать «Печать накладной» и она ещё не готова, плагин сообщит «Накладная ещё формируется, попробуйте ещё раз через несколько секунд» — это нормально, повторное нажатие через 10–15 секунд обычно уже открывает готовый PDF.

    09Технические логи

    Все запросы и ответы CDEK API плагин пишет в штатный журнал WooCommerce: WooCommerce → Статус → Журналы, источник woo-cdek. Там видны точные ответы CDEK по расчёту тарифов, созданию заказов и вебхукам.  

    10Частые проблемы

    На чекауте не появляется ни один тариф СДЭК

    Проверьте по порядку: город отправителя задан в настройках (без него расчёт вообще невозможен); в зоне доставки метод «СДЭК» действительно добавлен и включён; хотя бы одна из галочек «Пункт выдачи» / «Курьер» включена в его настройках; город/индекс покупателя указан и вообще существует в справочнике СДЭК. Подробности всегда есть в журнале woo-cdek.

    Не показывается карта выбора пункта выдачи

    Чаще всего не задан «Ключ Яндекс Карт JS API» в настройках (см. «Ключ Яндекс Карт») — администратор увидит об этом предупреждение внизу страницы чекаута, обычные покупатели нет. Проверьте также, что у ключа включены JavaScript API и HTTP Геокодер.

    Ошибка при создании заказа: «номер отправления ИМ не уникальный»

    СДЭК требует, чтобы номер отправления был уникален для аккаунта навсегда — если один и тот же аккаунт CDEK используется несколькими магазинами или сайт переносился с повторным использованием чужого номера, возможен конфликт. Обратитесь в поддержку с этим текстом ошибки.

    Заказ не создаётся: «В заказе не указан адрес доставки» / «не выбран пункт выдачи»

    Для курьерского тарифа СДЭК требует точный адрес доставки в заказе; для тарифа «пункт выдачи» — обязательно выбранный на карте ПВЗ (см. «Выбор пункта выдачи на чекауте»), не просто город. Если заказ оформлен без этого (например, вручную администратором), автоматическое создание в СДЭК завершится ошибкой с понятным текстом.

    Наложенный платёж не собирается / доставка не входит в наложенный платёж

    Проверьте, что способ оплаты заказа действительно выбран в настройке «Считать наложенным платежом заказы, оплаченные способом» (см. «Наложенный платёж»), и что переключатель «доставку оплачивает» выставлен так, как вам нужно.

    Статус в заказе не обновляется сам

    Проверьте на вкладке настроек, раздел «Вебхуки», кнопкой «Проверить текущие подписки» — подписки действительно активны и указывают на ваш текущий домен. Если сайт переехал на другой адрес, подписки со старым URL нужно подключить заново кнопкой «Подключить вебхуки». Как запасной вариант — кнопка «Обновить статус» в карточке заказа тянет статус вручную.

    11Технические ограничения

    • Все товары заказа упаковываются в одну условную коробку — её габариты берутся как максимальные среди товаров, а не считаются точной 3D-упаковкой по нескольким местам.
    • Город покупателя должен быть распознан в справочнике СДЭК — оригинальное написание с опечаткой или очень маленький населённый пункт без своего кода СДЭК может не резолвиться, и способ доставки просто не появится.
    • Вебхуки СДЭК не подписываются криптографически — подлинность запроса обеспечивается секретным токеном прямо в URL вебхука, а не проверкой подписи.
    • Печатная форма накладной формируется на стороне СДЭК асинхронно — сразу после создания заказа первый клик может потребовать повторного нажатия через несколько секунд.
    • Плагин не даёт выбрать конкретный тариф СДЭК вручную — только стратегию «самый дешёвый»/«самый быстрый» отдельно для ПВЗ и для курьера.