Налаштування обміну товарами та замовленнями між 1С-Бітрікс та Prom.ua

Втрата замовлень, розсинхронізація залишків та складнощі з двомовним контентом — типові проблеми магазинів на 1С-Бітрікс при виході на Prom.ua. Ми виконали понад 15 інтеграцій для українських ритейлерів, скоротивши ручні операції на 40% і прискоривши обробку замовлень у 2 рази. Нижче — технічні деталі, які допоможуть уникнути помилок.

Чому інтеграція з Prom.ua відрізняється від стандартної?

Prom.ua приймає фід у форматі YML або власному CSV. YML переважніший — підтримує більше полів і структуровану передачу характеристик. Ціни передаються в українських гривнях (UAH). Відмінність від стандартного YML для Яндекс.Маркета: Prom.ua підтримує тег <keywords> для кожного оффера — список ключових слів для внутрішнього пошуку платформи. Заповнення цього тегу безпосередньо впливає на видимість товару при пошуку на Prom.ua. Також підтримується тег <country_of_origin> для товарів з маркуванням походження та <barcode> для EAN-кодів.

Як влаштований API замовлень Prom.ua?

Базовий URL: https://my.prom.ua/api/v1/. Аутентифікація через токен: заголовок Authorization: Bearer {token}.

Ключові методи:

• GET /orders/list — список замовлень з фільтрами за статусом та датою
• GET /orders/{id} — деталі замовлення
• POST /orders/set_status — оновлення статусу замовлення

Статуси замовлень: pending (новий), received (підтверджений), delivered (доставлений), canceled (скасований), draft (чернетка).

Адаптація під український ринок

Мова контенту. Prom.ua — переважно україномовна аудиторія. Описи товарів у фіді краще давати українською. Якщо 1С-Бітрікс налаштований для російськомовного контенту, потрібно або зберігати україномовні описи в окремих властивостях інфоблоку, або використовувати машинний переклад як тимчасове рішення. Ми використовуємо властивість UF_UA_DESCRIPTION в інфоблоці та автоматично заповнюємо його з основного опису за допомогою API перекладу.

Ціни в UAH. Якщо магазин веде ціни в USD, потрібна конвертація за курсом НБУ. API НБУ: https://bank.gov.ua/NBU_Exchange/exchange_site?start=...&end=...&sort=exchangedate&order=desc&json. Оновлюємо курс щоденно агентом Бітрікс. Типова похибка — не більше 0.5% за рахунок крос-курсу.

Нова Пошта як основний перевізник. При обробці замовлень з Prom.ua більшість доставок йдуть через Нову Пошту. Якщо в Бітрікс налаштована інтеграція з API НП — адреса відділення із замовлення Prom.ua маппірується на поле доставки в Бітрікс автоматично. Ми налаштовуємо маппінг типів доставки за 1 день.

Як налаштувати отримання замовлень: покрокова інструкція

1. Отримайте токен API в особистому кабінеті Prom.ua.
2. Створіть в Бітрікс користувацьке поле UF_PROM_ORDER_ID для зберігання ID замовлення.
3. Налаштуйте агент на періодичний виклик GET /orders/list з фільтром за статусом pending.
4. При отриманні нового замовлення перевірте його за UF_PROM_ORDER_ID та створіть замовлення в Бітрікс.
5. Після обробки оновіть статус на Prom.ua через POST /orders/set_status.

Приклад коду агента:

$response = $httpClient->get('https://my.prom.ua/api/v1/orders/list', [ 'status' => 'pending', 'date_from' => date('Y-m-d\TH:i:s', strtotime('-10 minutes')), ]); foreach ($response['orders'] as $promOrder) { $existingOrder = findOrderByPromId($promOrder['id']); if (!$existingOrder) { createBitrixOrder($promOrder); } } 

Синхронізація залишків через фід

Prom.ua не має прямого API для оновлення залишків у реальному часі — все через фід. Частота оновлення фіду: раз на годину для магазинів з високим оборотом. Товари з нульовим залишком виставляємо з available=false — вони залишаються в каталозі, але не показуються в лістингу активних офферів. Для магазинів з низьким оборотом достатньо оновлення раз на 3-4 години — економія ресурсів сервера без втрати актуальності.

Типові помилки при інтеграції

Що входить в роботу

• Документація: опис схеми обміну, маппінг полів, інструкція для оператора.
• Доступи: налаштування токена, прав доступу до API Prom.ua та адміністративної частини Бітрікс.
• Навчання: демонстрація роботи інтеграції, відповіді на питання менеджерів.
• Підтримка: гарантійне обслуговування 1 місяць (виправлення помилок, консультації).

Орієнтири за термінами

Вартість розраховується індивідуально після аналізу каталогу та вимог до контенту. Для точної оцінки зв'яжіться з нами — ми підготуємо комерційну пропозицію за один день. Наші інженери мають 10+ років досвіду в Бітрікс та сертифікати з інтеграції з Prom.ua. Отримайте консультацію просто зараз.