Як підключити ERC за API: склад, валюта й курс ERC

Що вміє інтеграція з ERC

• Завантажує каталог ERC — назви, коди, ціни дилера й РРЦ, штрихкоди, гарантію, вагу й габарити, фото. Колонки розмічені заздалегідь.
• Бере наявність і кількість — загальні по складах ERC без налаштувань або тільки вашого складу.
• Тримає гривневі й доларові ціни в одному прайсі — валюту кожного товару визначає ознака ERC.
• Перераховує доларові ціни за курсом ERC на день завантаження.
• Підтягує характеристики й додаткові фото з окремого сервісу ERC за токеном.
• Відправляє замовлення постачальнику в ERC і забирає назад статус відвантаження й номер ТТН.

Категорія й підкатегорія ERC приходять у кожному товарі, і їх зіставляють із вашими категоріями так само, як у будь-якого прайсу (зіставлення категорій).

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

Меню

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

Нове джерело ERC

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

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

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

Наявність і кількість

картка джерела: секція «Колонки» і вкладка «Наявність»

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

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

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

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

Підготувати

доступ до API від менеджера ERC, e-mail і пароль B2B-порталу ERC

Що попросити в менеджера ERC

Доступ до API ERC видає не Elbuz, а сам ERC. За документацією ERC («ERC API. Загальна інструкція», версія 1.40) порядок такий.

1. Попросіть доступ до API у свого ведучого дилер-менеджера ERC. Окремого логіна для API немає: вхід іде тими самими e-mail і паролем, що й на B2B-портал ERC.
2. Передайте менеджеру статичну IP-адресу, з якої йтимуть запити: запит з іншої адреси ERC не обслуговує. Адресу копіюйте з вікна параметрів доступу (де вона написана): у різних акаунтів сервери різні.
3. Якщо наявність потрібна з одного складу — уточніть його номер. Номери з документації — у таблиці нижче, але який склад працює для вашого договору, знає тільки менеджер.
4. За бажанням — токен сервісу характеристик і фото. У загальній інструкції API ERC цього сервісу немає, тож токен теж просять у менеджера (навіщо).
5. Якщо збираєтеся відправляти замовлення — доступ до створення замовлень через API. Це окреме право в ERC: без нього каталог приходить, а замовлення ERC відхиляє (помилки 105 і 110).

Які параметри запиту ERC змінити

У майстрі нового джерела на кроці «Звідки» оберіть плитку «API» і ERC у списку. Адресу сервісу https://connect.erc.ua/connectservice/api/specprice/DoExport, формат XML і колонки програма ставить сама (що робить привʼязка). У вікні доступу в «Логін» впишіть e-mail B2B-порталу, у «Пароль (токен)» — пароль від нього.

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

1

Посилання на API для атрибутів і фото

2

Завантажувати курс валют

3

Замовлення: режим

1. Посилання на API для завантаження атрибутів і фото — сюди вставляють посилання з токеном ERC для характеристик і фото.
2. Завантажувати курс валют — значення 1 означає, що до цін у доларах застосовується курс ERC.
3. Замовлення: режим — від цього рядка й нижче йдуть налаштування відправлення замовлення в ERC.

Що приходить від ERC і як рахується наявність

Один запит — увесь каталог, доступний вашому акаунту, в XML. Відбору за брендом, категорією чи складом у запиті немає, тому фільтрують уже прийняті дані. На відповідь програма чекає до 300 секунд.

Колонки, які привʼязка розмічає сама. У джерел, підключених раніше, набір може бути коротшим: колонки ставляться один раз, у момент привʼязки.

Наявність за замовчуванням означає «є десь у ERC», зокрема на складі, звідки вам не відвантажать:

• Статус береться з тегу stock: true стає «В наявності», false — «Немає на складі», без налаштувань. Якщо ERC тег не надіслав, програма ставить його сама за сумою складів.
• Кількість — тег stock_qty: сума залишків усіх складів, крім 44, 55, 100_44 і 100_55 (товар з ушкодженнями й пошкодженою упаковкою). Градацію >50 програма рахує як 50.
• Товар лише на складі уцінки буде «В наявності» з кількістю 0: stock враховує склади уцінки, а stock_qty — ні. Якщо це заважає, поставте в рядок «Статус наявності (з прайсу)» адресу stock_qty.

Залишки по окремих складах лежать поруч, у блоці whs:

<whs><wh id="1" q="7" /><wh id="44" q="0" /><wh id="100" q=">50" />…</whs>

У id — номер складу, у q — залишок мінус резерв мінус товар у збиранні. До 50 включно — точне число, далі градація рядком: >50 (51–100), >100 (101–300), >300 (301–500), >500 (від 501).

Номери складів ERC

Склади з документації API ERC версії 1.40. Довідки зі складами ERC через API не віддає, тож з якого складу відвантажують саме вам, підкаже менеджер; у відповіді може бути й інший номер.

Виробник

Назва виробника в каталозі ERC стоїть один раз над групою його товарів, і програма переносить її в кожен товар тегом vendor. Якщо колонка «Виробник» у товарах прайсу порожня, впишіть у рядок «Виробник» секції «Колонки» адресу vendor і запустіть завантаження.

Як брати наявність тільки з одного складу ERC

Потрібно, коли вам відвантажують тільки з одного складу. У прикладах — склад 100; для свого замініть число.

Крок 1. Адреса складу в колонках

У секції «Колонки» картки джерела в рядках «Статус наявності (з прайсу)» і «Кількість» впишіть у «Адреса стовпця» //wh[@id='100']/@q. Рядка «Кількість» немає — додайте кнопкою «Додати поле».

Програма шукає адресу всередині кожного товару окремо, тож кожен товар отримає свій залишок. Номер беріть в одинарні лапки завжди: склади на кшталт 100_44 без лапок не знайдуться. Із градацій >50, >100 програма лишає цифри, тож кількість понад 50 — нижня межа: >100 дасть 100.

1

Адреса статусу наявності

2

Адреса кількості

3

Ціна в USD

1. Номер складу в одинарних лапках: //wh[@id='100']/@q.
2. Кількість береться з того самого складу, що й статус наявності.
3. Ціна в доларах — до неї застосовується курс ERC.

Самої адреси досить, щоб статуси стали правильними: число від 1 стає «В наявності», нуль — «Немає на складі». Але товари з нулем лишаються в прайсі, а помилка в номері складу пройде непоміченою — для цього крок 2.

Крок 2. Правила на вкладці «Наявність»

На вкладці «Наявність» картки джерела додайте два правила кнопкою «Додати».

1

Значення наявності з прайсу

2

Завантажувати тільки з цим статусом

3

{EMPTY}

1. Підказка «Значення наявності отримані з прайсу» — видно, що програма вже читає залишки складу 100, а не true/false.
2. Галка «Завантажувати товари тільки з цим статусом» у правила «В наявності» — товари з нулем на складі йдуть із прайсу.
3. Значення {EMPTY} у правила «Немає на складі» — страховка від неправильного номера складу.

Перед порівнянням програма прибирає з q пробіли й знаки >, <, =, тому >50 потрапляє в діапазон як 50. Верхню межу заповнюйте обовʼязково: діапазон «від 1 до 0» не спрацює ніколи. Діапазон замість переліку «1, 2, …, 9»: перелік порівнюється точно і пропустить залишок 12 чи >50.

Потрібен увесь каталог ERC, а наявність лише з одного складу — не вмикайте в першому правилі «Завантажувати товари тільки з цим статусом»: товари з нулем лишаться зі статусом «Немає на складі». Як перемикач діє на базовий каталог — у статті про статуси наявності.

Крок 3. Перевірка

Після зміни адреси запустіть завантаження джерела: значення наявності лишаються від старої адреси, доки ERC не віддасть каталог заново. Кнопка «Визначити наявність для товарів» на вкладці «Наявність» перевіряє правила на вже завантажених рядках, але не зміну складу.

Над сіткою правил підказка «Значення наявності отримані з прайсу:» показує написання з останнього завантаження. Для одного складу це числа до 50 і градації >50, >100, >300, >500; true і false — адреса з кроку 1 не збереглася. На сайт залишки потраплять після оновлення базового каталогу.

Як не помилитися з валютою цін ERC

ERC продає частину товарів за долари, частину — за гривні, і ціна дилера sprice приходить у валюті товару. Яка саме, каже тег ddp: 1 — гривня, 0 — долар. Так пояснив ERC офіційно; в API замовлень ERC те саме поле називається IsDDP.

Без налаштування ddp програма вважає всі ціни доларовими, і товар за 780 гривень опиняється в прайсі приблизно в 41 раз дорожчим. Перевірте секцію «Колонки»: має бути рядок «Валюта» з адресою ddp, а в рядка «Ціна» — правило мультивалюти для UAH. Немає — налаштуйте один раз:

1. Кнопкою «Додати поле» додайте рядок «Валюта» і впишіть у «Адреса стовпця» ddp.
2. У рядку «Ціна» в колонці «Валюта» має стояти USD — валюта товарів з ddp 0. Не EUR: тоді доларові товари порахуються як євро.
3. У тому ж рядку натисніть значок долара в колонці «Мультивалюту» — відкриється «Налаштування визначення валюти в прайс-листі».
4. Кнопкою «Додати валюту» оберіть UAH, у «Текст для пошуку» впишіть 1. «Адреса стовпця» лишіть порожньою, «Курс валюти» — нулем: курс гривні програма візьме з довідника валют.
5. Запустіть завантаження джерела.

1

Додати валюту

2

Текст для пошуку: 1

3

Код валюти: UAH

1. Додати валюту — з випадаючого списку обирають UAH.
2. Текст для пошуку зі значенням 1 — так ERC позначає гривневі товари в тезі ddp.
3. Код валюти UAH — валюта, яку отримують товари з позначкою 1.

Правило «0 → USD» не обовʼязкове: усе, що не 1, іде за валютою рядка «Ціна». «Ціна РРЦ» це не зачіпає: RRP_UAH завжди в гривнях.

Курс ERC для доларових цін

Коли «Завантажувати курс валют» дорівнює 1, після отримання каталогу програма окремим запитом бере в ERC курс виписування на сьогодні (курс у Києві й курс зарахування не використовуються). Курс записується в «Курс валюти» рядків «Ціна» й «Ціна РРЦ» з валютою USD — його видно в секції «Колонки».

• ERC курс не віддав або курс на сьогодні ще не визначено — лишається попередній.
• ERC відповів помилкою — у журналі рядок «Помилка API постачальника: …».
• У довіднику валют немає USD — курс не записується, у журналі «Курс постачальника не записано: у довіднику валют немає USD. Курс: ‹число›».
• Потрібен свій курс — поставте в параметрі 0 і задайте курс у колонках.

Як отримати характеристики й фото ERC

Основний прайс ERC дає назву, ціни, наявність і одне фото. Характеристики, опис і додаткові фото ERC віддає окремим сервісом за окремим токеном — не тим, що в полі «Пароль (токен)».

1. Попросіть токен у менеджера ERC — доступ до сервісу характеристик і фото товарів (wares.xml). Самостійно в кабінеті його не знайти.
2. Складіть посилання: https://api.erc.ua/api/erc/wares.xml?token=ВАШ_ТОКЕН, токен без пробілів.
3. Вставте посилання в параметр «Посилання на API для завантаження атрибутів і фото» (параметри запиту).
4. Завантажте прайс і перевірте характеристики й фото в товарах прайсу.

З посиланням кожне завантаження робить другий запит: групи характеристик, виробник, опис і фото привʼязуються до товарів прайсу за кодом ERC (code). Порожній параметр нічого не ламає — каталог, ціни й залишки приходять першим запитом.

Неправильний або застарілий токен теж не зупиняє завантаження: прайс приходить, а характеристики й фото пропускаються. У журналі тоді рядок «Помилка API постачальника: характеристики та фото не завантажено (перевірте токен у «Посилання на API для завантаження атрибутів і фото»)» з відповіддю ERC після двокрапки. Попросіть новий токен і вставте посилання з ним.

Як відправити замовлення в ERC

Замовлення постачальнику, створене в Elbuz на контрагента ERC, відправляється в ERC з самого документа. ERC отримує справжнє замовлення, тож програма просить підтвердження. Відправляти можна й непроведений документ.

Налаштування замовлення

Рядки «Замовлення:» у картці «Параметри запиту» джерела ERC. Програма бере їх з першого активного API-джерела контрагента, на якого виписано документ. ІПН, ID платника й ID договору показує кнопка «Отримати довідкові дані» в тому ж вікні — вона нічого в ERC не створює.

Відправка

Відкрийте документ «Замовлення постачальнику», натисніть «Відправити постачальнику» і підтвердіть. Результат зʼявляється повідомленням і записується в історію документа.

1

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

2

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

3

Не проведено

1. Відправити постачальнику — після підтвердження відправляє замовлення в ERC.
2. Оновити статус від постачальника — запитує в ERC статус замовлення та ТТН.
3. Не проведено — відправити можна і непроведене замовлення.

Програма нічого не відправляє, якщо:

• у позиції немає коду ERC — товар не зіставлений з прайсом ERC; назви таких позицій є в повідомленні;
• у режимі дропшипу в документі порожній номер ТТН;
• у режимі самовивозу не заповнено «Замовлення: ІПН вантажоодержувача»;
• увімкнено бухгалтерські документи, а платника не вказано ні через ID, ні через ЄДРПОУ;
• у документі немає позицій з кількістю більше нуля.

• Позиції з однаковим кодом ERC складаються в один рядок замовлення.
• Дропшип. ТТН ви створюєте самі, як для будь-якого відправлення з документа; в ERC іде тільки її номер.
• Повтор не створює дубль. Якщо в ERC вже є замовлення з номером цього документа, нове не створюється, а приходить «Замовлення з цим номером уже є в ERC — повторно не створено». Тож два документи з однаковим номером ERC вважатиме одним замовленням.
• «На погодженні» — не помилка. Замовлення створене, повідомлення жовте — «Замовлення в ERC на погодженні: …», статус документа від постачальника — «На погодженні». Далі погодження йде на боці ERC.

Статус і ТТН від ERC

Статус сам не оновлюється — тільки пунктом «Оновити статус від постачальника» в меню біля кнопки відправки. У повідомленні — номер замовлення в ERC і скільки відвантажено із замовленого. Після відвантаження статус від постачальника стає «Відвантажено частково» або «Відвантажено». Номер ТТН від ERC записується в документ, якщо там він порожній.

Коли ERC відхиляє замовлення

Відмову ERC видно в повідомленні: код і текст помилки. Найчастіші, за документацією ERC:

Сценарії

Склад, з якого брали товар, більше не відвантажує

Що зробити. Уточніть у менеджера ERC номер нового складу. У рядках «Статус наявності (з прайсу)» і «Кількість» поставте //wh[@id='‹номер›']/@q, на вкладці «Наявність» — два правила з кроку 2. Запустіть завантаження.

Що вийде. У прайсі лишаться тільки товари, яких на новому складі більше нуля, з кількістю цього складу. Решта зникне з прайсу при цьому ж завантаженні.

Потрібен весь асортимент ERC, а наявність — з одного складу

Що зробити. Те саме, що вище, але в першому правилі не вмикайте «Завантажувати товари тільки з цим статусом».

Що вийде. Усі товари каталогу ERC у прайсі: із залишком на вашому складі — «В наявності», без нього — «Немає на складі». Залишки інших складів до вашого не додаються.

Ціни в гривнях за курсом ERC

Що зробити. Залиште «Завантажувати курс валют» = 1, у секції «Колонки» — долар у рядку «Ціна» і валюту за ddp, як у розділі про валюту.

Що вийде. Перед кожним завантаженням доларові ціни перераховуються за курсом виписування ERC на поточний день, гривневі лишаються як є.

Що робити, коли прайс ERC не приїхав або наявність неправильна

Коли каталог не приїхав: коди помилок ERC

Якщо сервер ERC недоступний, у журналі завантаження зʼявиться «Помилка API постачальника: cURL Error #:…» з причиною від мережі. Якщо ERC відмовив, рядок той самий, а після двокрапки — код і текст ERC:

В обох випадках прогін іде на попередньому файлі: ціни й наявність не свіжі (чому так).

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

Чи можна вибрати склад ERC у параметрах API?

Ні. В API ERC немає параметра складу, каталог приходить з усіма складами. Склад вибирається адресою колонки — як брати наявність з одного складу.

Чому кількість товару 50 або 100, хоча на складі ERC більше?

Понад 50 штук ERC віддає не число, а градацію: «>50», «>100», «>300», «>500». Програма лишає цифри, тож кількість — нижня межа: «>100» означає від 101 до 300 штук, а в прайсі буде 100.

Чи можна підсумувати залишки двох вибраних складів?

Ні. Кількість — або сума всіх складів придатного товару (stock_qty), або один склад адресою колонки.

Чи можна завантажувати з ERC тільки певні бренди чи категорії?

На боці ERC — ні, каталог приходить цілим. Зайве відсікають уже в Elbuz правилами ігнорування.

Змінив склад, а наявність у прайсі стара. Чому?

Значення наявності беруться з файлу під час завантаження. Запустіть завантаження джерела заново; кнопка «Визначити наявність для товарів» перераховує тільки вже завантажені значення (перевірка).

Суміжні теми

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