CdekIntegrate

Компонент интеграции заказов MiniShop3 с сервисом доставки СДЭК. Расширяет msCDEK — добавляет создание заказов в СДЭК, отслеживание статусов, генерацию накладных и штрихкодов, приём вебхуков.

Внимание

Данная документация актуальна для версии компонента 1.0.0 и выше (MODX 3 + MiniShop3).

Требования

1. MODX 3.x
2. PHP >= 8.1
3. MiniShop3
4. msCDEK 3.x (расчёт доставки, выбор ПВЗ)

Возможности

1. Автоматическое создание заказа в СДЭК при смене статуса в MiniShop3.
2. Автоматическая отмена заказа в СДЭК при переводе в статус отмены.
3. Ручное управление заказами из панели администратора (отправка, отмена, повторная отправка).
4. Отслеживание статусов через вебхуки СДЭК с маппингом на статусы MS3.
5. Генерация и скачивание накладных (PDF).
6. Генерация и скачивание штрихкодов (PDF).
7. Vue-панель в карточке заказа: статус, кнопки управления, документы, история.
8. Поддержка тестового режима (тестовая среда API СДЭК).
9. Поддержка наложенного платежа.

Быстрый старт

Информация

Перед настройкой CdekIntegrate убедитесь, что msCDEK уже установлен и настроен (логин/пароль СДЭК, тарифы, способы доставки).

1. Установка

Установите пакеты msCDEK и CdekIntegrate через пакетный менеджер MODX.

2. Настройка точки отправления

Укажите, откуда отправляются заказы. Есть два варианта:

Вариант A — через ПВЗ отправления (приоритетнее):

Укажите код ПВЗ в настройке cdekintegrate_shipment_point. Код можно найти на сайте СДЭК.

Вариант B — через адрес:

Заполните cdekintegrate_from_location в формате JSON:

{"country_code": "RU", "city": "Москва", "address": "ул. Примерная, 1"}

3. Настройка автоматического создания заказов

По умолчанию заказ автоматически отправляется в СДЭК при переходе в статус 2 (Оплачен).

Если нужны другие статусы — измените cdekintegrate_create_statuses:

[2, 3]

4. Настройка вебхуков (опционально)

Для автоматического обновления статусов заказов:

1. Укажите URL вебхука в cdekintegrate_webhook_url:

https://yoursite.ru/api/v1/cdekintegrate/webhook

2. Настройте маппинг статусов СДЭК на статусы MS3 в cdekintegrate_status_mapping:

{"DELIVERED": 5, "RECEIVED_AT_SHIPMENT_WAREHOUSE": 3}

5. Готово

Теперь при смене статуса заказа в MiniShop3:

• Заказ автоматически отправляется в СДЭК
• Статусы обновляются через вебхуки
• В карточке заказа появляется вкладка управления СДЭК

Панель в карточке заказа

При редактировании заказа в админке MiniShop3 на вкладке СДЭК Интеграция доступны:

• Статус — текущий статус заказа в СДЭК с трекинг-номером
• Действия — кнопки «Отправить», «Отменить», «Повторить» (для отменённых)
• Документы — скачивание накладной и штрихкода в PDF
• История — хронология всех статусов заказа

Хранение данных

Данные СДЭК сохраняются в двух местах:

• msOrder.properties.cdekintegrate — текущее состояние: cdek_uuid, cdek_number, status_code, status_name, invoice_uuid, barcode_uuid
• Таблица cdekintegrate_history — полная история статусов: order_id, cdek_uuid, status_code, city, event_time