Настройка модуля «5Post (Пятёрочка)»

Модуль 5Post подключает доставку в точки выдачи X5 к ADWOS CMS. Он нужен площадкам, которые продают физические товары и хотят передавать заказы в 5Post, показывать покупателю доступные пункты выдачи и получать статусы отправлений.

Что делает модуль

• Проверяет партнёрский API key и получает JWT через официальный метод 5Post.
• Загружает активные точки выдачи через `POST /api/v1/pickuppoints/query`.
• Создаёт заказ в 5Post через `POST /api/v1/createOrder`.
• Запрашивает статус заказа через `POST /api/v1/getOrderStatus` по `orderId` или `senderOrderId`.
• Отменяет заказ по `orderId` или `senderOrderId` через актуальные v2-методы отмены.

Что подготовить до настройки

• Партнёрский `apikey` 5Post. Его выдаёт менеджер или партнёрский кабинет 5Post.
• `partnerLocationId` склада или точки отгрузки. Без него нельзя корректно оформить отправление.
• Понимание рабочей среды: preprod для тестов или production для боевых заказов.
• Согласованный бренд отправителя для уведомлений покупателю.
• Тестовый заказ с реальными габаритами, весом, телефоном получателя и выбранной точкой выдачи.

Настройка в ADWOS CMS

• Откройте админку ADWOS, раздел «Каталог», затем «Маркетплейс».
• Найдите модуль «5Post (Пятёрочка)» и установите его, если он ещё не установлен.
• Откройте управление модулем и перейдите в настройки.
• Заполните поле «API key». Это защищённое поле, в обычном интерфейсе ключ не должен отображаться открытым текстом.
• Включите «Тестовая среда (preprod)», если проверяете интеграцию до боевого запуска. Для production оставьте переключатель выключенным.
• Заполните «ID склада отгрузки (partnerLocationId)» значением, которое подтвердил 5Post.
• Заполните «Бренд отправителя» коротким понятным названием магазина или проекта.
• Сохраните настройки и включите модуль.

Проверка после установки

• Сначала проверьте `/jwt`. Успешный ответ означает, что API key принят и модуль может получать JWT.
• Затем проверьте `/pickup-points`. Если тело запроса пустое, модуль использует безопасный базовый запрос с `pageSize: 1000` и `pageNumber: 0`.
• Создайте тестовый заказ через `/orders` в той среде, которую согласовали с 5Post.
• Проверьте статус через `/order-status`. Для контроля используйте тот же `senderOrderId`, который передали при создании заказа.
• Проверьте отмену через `/cancel-order` только на тестовом отправлении.

Частые ошибки

• Использовать production API key в preprod-среде или наоборот. Среда и ключ должны соответствовать друг другу.
• Передавать заказ без `partnerLocationId`. 5Post не сможет определить точку отгрузки.
• Ожидать отдельную кнопку скачивания PDF или ZIP-этикеток. Формат этикетки согласуется с менеджером 5Post и зависит от партнёрского процесса.
• Обновлять справочник точек выдачи слишком часто. Для большинства площадок достаточно одного обновления в сутки после 05:00 по Москве.
• Запускать боевые заказы до проверки статуса и отмены в тестовой среде.

Когда переводить в production

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