Як підключити Юг-Контракт за API: ключ, дозволений IP, картки й резерв

Що вміє інтеграція з Юг-Контрактом

• Завантажує прайс Юг-Контракту — код, артикул, назву українською, бренд, штрихкод, ціну дилера й РРЦ, гарантію, вагу, категорію, наявність, фото, короткий опис і посилання на товар.
• Заповнює повні картки товарів — HTML-опис, усі характеристики й усі фото.
• Розрізняє стани наявності — в наявності, у резерві, очікується, під запит.
• Відправляє замовлення в Юг-Контракт з документа: Юг-Контракт створює замовлення й резервує товар.

Де це і хто має доступ

Меню

Довідники → Обробка прайс-листів → Список прайс-листів

Нове джерело Юг-Контракту

майстер нового джерела, крок «Звідки» → плитка «API» → «Юг-Контракт»

Доступ і параметри запиту

картка джерела, секція «Джерело» → «Налаштування параметрів API»

Відправка замовлення

документ «Замовлення постачальнику» → «Відправити постачальнику»

Право доступу

вікно «Список прайс-листів» і «Налаштування завантаження: файл із прайс-листом»; для замовлення — редагування документів

Підготувати

ключ і секрет API з кабінету Юг-Контракту, IP-адресу Elbuz у переліку дозволених

Ключ API і дозволена IP-адреса в кабінеті Юг-Контракту

1. Ключ і секрет API. У кабінеті Юг-Контракт B2B відкрийте «Налаштування API» і натисніть «Згенерувати» — зʼявиться нова пара ключів. Ключ вписується в «Логін», секрет — у «Пароль (токен)».
2. IP-адреса Elbuz у переліку дозволених. Юг-Контракт пускає в API тільки з адрес, внесених у тому ж розділі «Налаштування API». Адресу скопіюйте з вікна параметрів доступу джерела, рядок «IP-адреса сервера Elbuz Jumper, яку необхідно передати постачальнику для надання доступу:» (де саме).

Без цих двох кроків Юг-Контракт відмовляє з помилкою 403 (коли прайс не приїхав).

Які параметри запиту Юг-Контракту задати

У майстрі нового джерела на кроці «Звідки» оберіть плитку «API» і «Юг-Контракт». Адресу https://b2b.yugcontract.ua/api/, формат CSV і колонки програма ставить сама (що робить привʼязка). Кнопка «Отримати довідкові дані» для Юг-Контракту показує лише «У цієї інтеграції немає довідкових даних…»: коди контрагентів і договорів для замовлення дивіться в кабінеті Юг-Контракту, розділ API, опис методу post-order.

1

Повні картки товарів

2

Замовлення: оплата

3

Замовлення: пріоритет складів

1. Повні картки товарів: 1 — опис, характеристики й фото з Юг-Контракту.
2. Замовлення: оплата: cash — готівка, bank — безготівка.
3. Замовлення: пріоритет складів: 0 — спочатку склад регіону.

У джерел, підключених раніше, «Повні картки товарів» вимкнені (0). У нових джерел картки увімкнені одразу.

Що приходить від Юг-Контракту: колонки за номерами

Юг-Контракт віддає прайс через API, а програма складає з нього CSV-файл: кожен товар — рядок, кожне поле — колонка за номером. Колонки, які привʼязка розмічає сама:

Решту колонок беруть вільним рядком секції «Колонки», вписавши номер у «Адреса стовпця»:

• 3 і 4 — коди підгрупи й категорії; 12 — код стану наявності;
• 9 — ціна за мінімальну упаковку; 11 — контрольна РРЦ; 18 — ціна без ПДВ; 19 і 20 — ставка ПДВ;
• 16 — назва англійською; 17 — стан (Новий або ДУ); 22 — країна; 23 — код УКТ ЗЕД;
• 25 — вага мінімальної упаковки; 26 — обʼєм.

Ціна і РРЦ у гривнях

Ціна дилера (колонка 8) і РРЦ (колонка 10) у Юг-Контракті в гривнях, тож у рядках «Ціна» і «Ціна РРЦ» має стояти UAH; нові джерела розмічаються так самі. Курсу Юг-Контракт не віддає, перераховувати нічого не треба.

Колонка 11 — контрольна РРЦ: сума, нижче якої Юг-Контракт просить не продавати товар; 0 — контролю немає. Прайс приходить з товарами в стані «Новий» і «ДУ», уцінених товарів у ньому немає.

Як отримати повні картки товарів Юг-Контракту

У прайсі Юг-Контракт дає одне фото й короткий опис. Повні картки він віддає окремо, і не по товару, а цілими категоріями. Тому програма робить так:

• Просить тільки потрібні категорії — ті, де є товар без картки або з карткою, старшою за 30 днів. Перший раз це майже весь каталог, кілька хвилин; далі — зазвичай жодної категорії.
• Зберігає картки окремо від прайсу. Кнопка «Завантажити» їх не стирає.
• Бере картки тільки товарам у наявності й у резерві. Товари «очікується» й «під запит» приходять без карток.
• Запамʼятовує відсутність картки. Такі товари програма не перепитує 30 днів, а фото їм ставить з прайсу.
• Оновлює картки раз на 30 днів. Списку змін Юг-Контракт не віддає, тож виправлена вчора картка оновиться, коли їй мине 30 днів.

Як увімкнути

1. Увімкніть картки: у параметрах запиту в рядку «Повні картки товарів» впишіть 1. Окремого входу не треба: картки беруться тим самим ключем.
2. За бажанням — як показувати характеристики: «Обʼєднувати значення характеристик» і «Розділювач значень характеристик». Змінили — завантажте прайс ще раз, картки заново не качаються.
3. Завантажте прайс кнопкою «Завантажити». Коли програма дозапитує картки, у журналі зʼявляється «Повні картки Юг-Контракту: запит по ‹скільки› категоріях».
4. Перевірте опис, характеристики й фото в товарах прайсу.

Фото й характеристики привʼязуються за кодом Юг-Контракту (колонка 6), окремих адрес колонок не треба. Товар з карткою отримує всі її фото, решта — одне фото з колонки 29.

Під час додавання товару з прайсу в базовий каталог картка приходить заповненою (характеристики товарів, фото товарів). Якщо Юг-Контракт не віддав картки, у журналі — «Повні картки Юг-Контракту не отримано (…) — прайс завантажується з уже збереженими картками»; нові доберуться наступного разу.

Як розрізнити «очікується» і «під запит»

Привʼязка бере наявність з колонки 13 — залишку. Точних штук там немає: Юг-Контракт віддає залишок ступенями (1, 2 … 10, 50, 100, 500), і більше нуля він тільки в товарів у наявності. У товарів «у резерві», «очікується» й «під запит» залишок — 0. Стандартні статуси розпізнають це без налаштувань: від 1 — «В наявності», 0 — «Немає на складі».

Щоб розрізняти стани, візьміть код стану з колонки 12:

Поставте в рядку «Статус наявності (з прайсу)» адресу 12 і додайте правила для потрібних статусів на вкладці «Наявність» джерела (наявність товару в прайсі постачальника). Без своїх правил коди 2, 3 і 4 — як і будь-яке число від 1 — стануть «В наявності».

Рядок «Кількість» привʼязка не розмічає. Якщо вписати туди 13, кількість буде ступенем, а не точним числом.

Як відправити замовлення в Юг-Контракт з резервом

Замовлення постачальнику, створене в Elbuz на контрагента Юг-Контракту, відправляється з документа; Юг-Контракт створює справжнє замовлення й резервує товар. Налаштування — рядки «Замовлення: …» у параметрах запиту; програма бере їх з першого активного API-джерела контрагента документа.

Що відбувається після натискання

Відкрийте документ «Замовлення постачальнику», натисніть «Відправити постачальнику» і підтвердіть. Програма:

1. перевіряє, чи немає вже в Юг-Контракті замовлення з цього документа;
2. відправляє позиції за кодом Юг-Контракту; однакові товари складаються в один рядок;
3. передає внутрішній ID документа Elbuz (за ним Юг-Контракт потім знаходить це замовлення), коментар «Elbuz ‹номер документа›», тип оплати й пріоритет складів, а контрагента й договір — тільки якщо вони задані.

Номер замовлення Юг-Контракту записується в документ, статус від постачальника — «Резерв», результат — у повідомленні й історії документа.

1

Відправити постачальнику

2

Оновити статус від постачальника

1. Відправити постачальнику — замовлення з резервом у Юг-Контракті.
2. Оновити статус від постачальника — показує, скільки в резерві.

Коли зарезервовано не все

Замовлення створюється, навіть якщо частину товару Юг-Контракт не зарезервував. Програма перелічує такі позиції після слова «Увага:», статус від постачальника — «Резерв частково»:

• «‹товар› — зарезервовано ‹скільки› з ‹скільки›» — товару на складах не вистачило;
• «‹товар› — Юг-Контракт не знайшов товар за кодом, у замовлення не додано» — зіставте товар з актуальним прайсом.

Дозамовлення й заміну відсутнього робіть у кабінеті Юг-Контракту або окремим документом.

Коли нічого не відправляється

• у позиції немає коду Юг-Контракту — товар не зіставлений з прайсом; назви таких позицій є в повідомленні (зіставлення товарів);
• у документі немає позицій з кількістю більше нуля;
• Юг-Контракт не пустив програму — неправильний ключ чи секрет або IP-адреси немає серед дозволених (повідомлення з «403»).

Повтор не створює друге замовлення. Юг-Контракт знає замовлення за ID документа Elbuz, тож повторне натискання показує «Замовлення вже є в Юг-Контракті — повторно не створено.» і стан наявного замовлення.

Стан замовлення

Стан сам не оновлюється — тільки пунктом «Оновити статус від постачальника» в меню біля кнопки відправки. Він показує «Юг-Контракт: замовлення ‹номер›, у резерві ‹скільки› шт.», статус від постачальника — «Резерв» або «Без резерву», якщо в резерві нічого не лишилося.

Відправку замовлення ми перевірили на імітації сервера Юг-Контракту, а не на справжньому замовленні. Перше замовлення відправте невелике й звірте результат у кабінеті.

Сценарії

Додавати товари Юг-Контракту в каталог одразу з описом і фото

Що зробити. «Повні картки товарів» = 1, завантаження джерела, далі — додавання товарів з прайсу в базовий каталог, як звичайно.

Що вийде. Нові товари в каталозі отримують опис, характеристики й фото з Юг-Контракту. Наступні завантаження оновлюють ціни й наявність і добирають картки для нових товарів.

Продавати не нижче контрольної РРЦ

Що зробити. У секції «Колонки» додайте вільний рядок з адресою 11. Рядок «Ціна РРЦ» лишіть з адресою 10: контрольна РРЦ є далеко не в кожного товару.

Що вийде. У прайсі зʼявиться контрольна РРЦ Юг-Контракту; 0 означає, що контролю для товару немає.

Безготівкове замовлення на конкретний договір

Що зробити. У параметрах API поставте «Замовлення: оплата» = bank, а в «Замовлення: договір (ID)» — код договору з кабінету Юг-Контракту.

Що вийде. Замовлення з Elbuz створюються на цей договір з безготівковою оплатою.

Що робити, коли Юг-Контракт відповідає 403 або прайс неповний

Коли прайс не приїхав

Прайс Юг-Контракт збирає довше за більшість постачальників — до кількох хвилин, а перше завантаження з картками ще довше. У журналі робота з ним видно рядками «Отримуємо файл за API», «Підключення до API сервера» й «Отримано файл: ‹розмір› МБ».

На неправильний ключ або відсутню IP-адресу Elbuz у журналі — «Помилка API постачальника: Yugcontract auth: 403 Error: Forbidden», а за ним «Для завантаження не отримано новий файл, використовується попередній». Ціни й наявність тоді лишаються вчорашніми (чому так).

Часті запитання

Чому Юг-Контракт відповідає 403?

Юг-Контракт пускає в API тільки з IP-адрес, внесених у «Налаштування API» його кабінету, і тільки з чинною парою ключів. Внесіть адресу з вікна параметрів доступу і перевірте, що в джерелі стоять ключ і секрет останньої згенерованої пари.

Чи прийдуть фото без повних карток?

Так, одне фото на товар — з колонки фото прайсу. З повними картками товар, у якого є картка, отримує всі її фото.

Чи створиться дубль, якщо натиснути «Відправити постачальнику» двічі?

Ні. Юг-Контракт знає замовлення за ID документа Elbuz, тож повторне натискання лише покаже стан наявного замовлення.

Чи можна підтвердити відвантаження або видалити замовлення Юг-Контракту з Elbuz?

Ні. Доставку, підтвердження відвантаження й видалення замовлення оформлюють у кабінеті Юг-Контракту.

Чи можна завантажити уцінені товари Юг-Контракту?

Ні. Прайс за API містить тільки товари в стані «Новий» і «ДУ».

Суміжні теми

• Якщо треба зрозуміти, що програма робить з будь-яким джерелом за API і де вписати доступи, — Як підключити постачальника за API.
• Якщо стани з колонки 12 треба розкласти на свої статуси, — Наявність товару в прайсі постачальника.
• Якщо треба взяти додаткову колонку Юг-Контракту, — Розмітка колонок прайсу.
• Якщо замовлення постачальнику ще треба зібрати з замовлень покупців, — Замовлення постачальнику.