Інтеграція

1 Варіанти роботи з сервісом для інтегрованих користувачів та що потрібно для початку?

Для користувачів, які бажають працювати інтегровано, існує 2 варіанти інтеграції з сервісом EDIN Market:

  1. API (інтерфейс програмування застосунків) — це набір правил і протоколів, що дозволяють одній програмі взаємодіяти з іншою. API визначає способи, якими одна програма може запитувати дані або функції з іншої програми. Це дозволяє створювати інтеграції між різними програмами або системами.

Основні характеристики API:

  • Взаємодія: API дозволяє програмам обмінюватися даними та функціоналом без необхідності знати про внутрішню роботу один одного.

  • Автоматизація: API дозволяє автоматизувати процеси, зменшуючи ручну працю.

  • Реальний час: Обмін даними через API зазвичай відбувається в режимі реального часу.

  • Гнучкість: API можуть бути налаштовані під різні потреби та інтеграції.

Опис методів взаємодії з API сервісу EDIN Market доступний за посиланням.

  1. FTP (протокол передачі файлів) — це стандартний мережевий протокол, що використовується для передачі файлів між комп’ютерами в мережі. FTP дозволяє користувачам завантажувати (завантажувати) і завантажувати (викачувати) файли з одного комп’ютера на інший через Інтернет.

Основні характеристики FTP:

  • Передача файлів: FTP використовується виключно для передачі файлів.

  • Простота: FTP є простим у використанні, що робить його популярним для передачі великих обсягів даних.

  • Автоматизація: Завдання з передачі файлів через FTP можна автоматизувати, наприклад, за допомогою скриптів.

Отже, API — це спосіб взаємодії систем та програм, а FTP — це метод передачі файлів між комп’ютерами (серверами).

Для того, щоб розпочати свою роботу Вам потрібно мати логін та пароль доступу до сервісу https://edo-v2.edin.ua/, а також звернутись до технічної підтримки або аккаунт менеджера для відкриття доступу до обміну FTP/API.

Також наша компанія має готові інтеграційні рішення для типових облікових систем, що дозволить значно зменшити час на впровадження та налаштування інтеграції.

Контакти:

+38 (044) 359-01-12 / +38 (099) 333-67-70 / +38 (097) 333-67-70 / support@edin.ua

2 Як продавцю завантажити прайс-лист та на що звернути увагу?

Існує кілька способів завантаження прайс-листа для покупця:

  • Вебінтерфейс. Цей спосіб актуальний для користувачів, що не використовують інтеграцію. Цей спосіб може бути актуальним для користувачів, в яких не так часто оновлюється асортимент або параметри позицій в прайс-листі. Опис процесу завантаження детально описаний в інструкції за посиланням.

  • API. Це один з варіантів інтегрованої роботи, що також дозволяє продавцю працювати з прайс-листами. Для використання цього методу потрібно мати логін та пароль доступу на платформу, а також за допомогою програмних інструментів що дозволяють працювати по API користувачу необхідно пройти Авторизацію в сервісі. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на створення Прайс-листа.

  • Опис методів для роботи з прайс-листами за посиланням

  • Опис та приклад тіла Прайс-листа який що потрібно передавати в запитах за посиланням

  • FTP. Це ще один з варіантів інтегрованої роботи що дозволяє продавцю працювати з прайс-листами. Відмінність від способу обміну по API полягає в, тому що прайс-лист вивантажується у вигляді файлу в XML форматі. Для використання цього методу потрібно мати логін та пароль доступу на платформу. Користувач за допомогою FTP клієнта (спец. програмне забезпечення) підключається до сервера та розміщує готовий XML файл прайс-листа в каталог Outbox. Приклад структури тіла документа з описом за посиланням.

Параметри підключення за посиланням.

3 На що особливо важливо звернути увагу при вивантаженні прайс-листа API / FTP?

  1. Наявність обов’язкових полів що передбачені структурою документа.

  • Обов’язкові поля позначаються в документації, як “М”

  • Опційні поля зазначаються в документації, як “О”

  1. Коректність обраного ACTION для вузлового тега PRICAT (для FTP).

  2. Коректність обраного ACTION для вузлового тега POSITION (для FTP).

  3. Якщо працюєте з Обмеженнями, то обов’язково зверніть увагу чи заповнені поля в прайс-листі за якими виконуються перевірки обмежень.

  4. Прайс-лист має ознаку (тип) - «з ПДВ» або «без ПДВ». До кожної позиції може бути зазначено мінімум 1 ну ціну (відповідно до типу прайс-листа (з / без ПДВ).

  5. Прайс-лист може містити 4-ри типи ціни по позиції. В зв’язку з чим застосовується логіка визначення “Головної ціни” (якщо всі 4-ри ціни по позиції вказані). Відповідно до головної ціни застосовуються перевірки та обмеження.

Пріоритет для головної ціни:

  • Ціна одиниці зі знижкою з ПДВ

  • Ціна одиниці зі знижкою без ПДВ

  • Ціна одиниці з ПДВ

  • Ціна одиниці без ПДВ

4 Як отримати актуальний прайс-лист по API / FTP?

Для користувачів що використовують API інструменти для інтеграції потрібно авторизуватись в сервісі використовуючи запит. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на отримання актуального прайс листа. В тілі відповіді на запит ви отримаєте набір даних прайс-листа з описом параметрів позицій.

Для користувачів, що реалізували обмін документами за допомогою FTP для отримання актуального прайс листа потрібно:

  • Сформувати документ прайс-лист в XML форматі без заповненого блока CATALOGUE (приклад за посиланням).

  • В тег ACTION вказати значення “19” (запит прайс-листа на поточну дату).

  • Розмістити файл на FTP в каталозі Outbox.

  • Система опрацює отриманий документ поверне та у відповідь Актуальний прайс-лист.

  • Актуальний прайс-лист буде розміщено в каталозі Inbox.

5 Що таке «Обмеження» та які обмеження існують?

Обмеження — це набір правил які встановлює Продавець для своїх покупців (можуть бути встановлені для кожного індивідуально). Обмеження застосовуються до конкретної позиції або замовлення загалом. Відповідно до встановлених обмежень на етапі формування та відправки виконується перевірка замовлення та у випадку помилки інформування користувача.

Які існують обмеження:

  • Мін. сума замовлення без ПДВ

  • Мін. сума замовлення з ПДВ

  • Макс. сума замовлення без ПДВ

  • Макс. сума замовлення з ПДВ

  • Кредитний ліміт

  • Тариф для надбавки

  • Макс. кіл-ть днів для повернення товару

  • Макс. кіл-ть товарних позицій

  • Макс. вага замовлення, кг

  • Макс. кіл-ть коробок/ящиків

  • Макс. кіл-ть паллет

  • Контроль залишків та квот

  • Кратність коробці/ящику

  • Кратність мін. кіл-ті одиниць

6 Як перевіряється замовлення на відповідність встановленим обмеженням?

При отриманні замовлення виконується перевірка на наявність обов’язкових полів (згідно зі специфікацією). Перевірка замовлення на відповідність лімітам виконується за певними правилами та відповідним тегам в документі та прайс-листі.

Для інтегрованих користувачів, які вивантажують документи методами API / FTP працює логіка доповнення. Якщо для Покупця, від якого в систему надійшло замовлення є встановлені обмеження то система окрім перевірки обов’язкових полів перевіряє наявність в замовленні полів що використовуються для перевірки конкретного Обмеження.

  • Якщо поля в замовленні вказані, то запускається процес перевірки замовлення на відповідність обмеженням.

  • Якщо поле / поля відсутні, то виконується логіка доповнення. Тіло замовлення автоматично доповнюється полями які потрібні для перевірки обмеження.

Логіки, за якою виконується перевірка на відповідність обмеження та доповнення тіла замовлення (ордера) в разі необхідності:

  1. Мін. сума замовлення без ПДВ

  • Сума без ПДВ = Кількість одиниць * Ціна одиниці без ПДВ.

  • Сумуємо значення по всім позиціям ордера та звіряємо з встановленим лімітом:

    • Загальна сума замовлення без ПДВ ≥ Мін. сума замовлення без ПДВ - Якщо значення більше або дорівнює ліміту, то перевірка успішна

  • Для розрахунку в ордері Тег: ORDERPRICE

  1. Мін. сума замовлення з ПДВ

  • Сума з ПДВ = Кількість одиниць * Ціна одиниці з ПДВ.

  • Сумуємо значення по всім позиціям ордера та звіряємо з встановленим лімітом:

    • Загальна сума замовлення з ПДВ ≥ Мін. сума замовлення з ПДВ - Якщо значення більше або дорівнює ліміту, то перевірка успішна

    • Для розрахунку в ордері Тег: PRICEWITHVAT

  1. Макс. сума замовлення без ПДВ

  • Сума без ПДВ = Кількість одиниць * Ціна одиниці без ПДВ.

  • Сумуємо значення по всім позиціям ордера та звіряємо з встановленим лімітом:

    • Загальна сума замовлення без ПДВ ≤ Макс. сума замовлення без ПДВ — Якщо значення менше або дорівнює ліміту, то перевірка успішна

    • Для розрахунку в ордері Тег: ORDERPRICE

  1. Макс. сума замовлення з ПДВ

  • Сума з ПДВ = Кількість одиниць * Ціна одиниці з ПДВ.

  • Сумуємо значення по всім позиціям ордера та звіряємо з встановленим лімітом:

    • Загальна сума замовлення з ПДВ ≤ Макс. сума замовлення з ПДВ — Якщо значення менше або дорівнює ліміту, то перевірка успішна

    • Для розрахунку в ордері Тег: PRICEWITHVAT

  1. Макс. кіл-ть товарних позицій

  • Кількість товарних позицій (POSITIONNUMBER) в замовленні має бути ≤ менше або дорівнювати встановленому обмеженню по максимальній кількості позицій — Перевірка успішна. Якщо більше встановленого ліміту — помилка.

  • Доповнення тіла ордера не відбувається.

  1. Макс. вага замовлення, кг

  • Перевірка по тегу ордера : UNITWEIGHT

  • Доповнюється Ордер значеннями з прайс-листа: UNITWEIGHT

  • Розраховується Сума всіх значень по позиційно.

    • Загальна вага позиції = Вага одиниці * Кількість одиниць

    • Загальна Вага замовлення = Сума всіх значень Загальна Вага позиції

  • Загальна вага всіх позицій замовлення має бути ≤ менше або дорівнювати встановленому обмеженню по максимальній Вазі — Перевірка успішна. Якщо більше встановленого ліміту — помилка.

  1. Макс. кіл-ть коробок

  • Перевірка по тегу Ордера: BOXESCOUNT

  • Якщо покупець не передав тег BOXESCOUNT, то перевіряється наявність поля QUANTITYOFCUINTU в прайс-листі:

    • якщо є, то BOXESCOUNT розраховується та додається ордер.

    • якщо немає, то BOXESCOUNT не розраховується не додається ордер.

  • Якщо покупець передає тег BOXESCOUNT, то перевіряємо наявність поля QUANTITYOFCUINTU в прайс-листі:

    • якщо немає, то помилка.

  • Доповнюється ордер значеннями з прайс-листа Одиниць в коробці: QUANTITYOFCUINTU (прайс) в тег COUNTPIECESINBOX (ордер)

  • Загальна Кількість коробок розраховується як: Сума всіх значень Кількість коробок (по позиційно)

  • Загальна кількість коробок всіх позицій в ордері має бути ≤ менше або дорівнювати встановленому обмеженню по максимальній кількості — Перевірка успішна. Якщо більше встановленого ліміту — помилка.

  1. Макс. кіл-ть паллет

  • Перевірка по тегу Ордера: PALLETS

  • Якщо покупець не передав тег PALLETS, то перевіряємо наявність полів QUANTITYOFCUINTU та BOXINPALLET в прайс-листі:

    • якщо якогось поля або двох полів немає, то PALLETS не розраховується та не додається до ордера.

    • якщо обидва поля є, то PALLETS розраховується та додається до ордера

  • Якщо покупець передає тег PALLETS, перевіряємо наявність полів QUANTITYOFCUINTU та BOXINPALLET в прайс-листі:

    • якщо якогось поля або двох полів немає, то помилка

  • Доповнюється ордер значеннями з прайс-листа Одиниць в коробці: BOXINPALLET в тег COUNTPERPALLET

  • Загальна Кількість палет розраховується як: Сума всіх значень Кількість палет (по позиційно)

  • Загальна кількість палет всіх позицій в ордері має бути ≤ менше або дорівнювати встановленому обмеженню по максимальній кількості — Перевірка успішна. Якщо більше встановленого ліміту — помилка.

  1. Контроль залишків та квот

  • Не перевіряємо дані з ордера що передав клієнт Перевірка по тегу з ордера - ORDEREDQUANTITY

  • MAXIMUMORDERQUANTITY Не доповнюємо з прайса та не перевіоряємо значення яке передав клієнт в ордері. Перевірка тільки по значенням в прайсі. Тоб то клієнт може не передати або передати невірне значення і помилки при цьому не буде якщо ми перевірили відповідність Обмеження в прайсі та кількість яка зазначена в замовленні.

  • Перевірка на рівні позиції в прайс-листі по тегу: QUOTA (Квота) та ACTUALQUANTITY (залишок). Контроль максимальної кількості доступної до замовлення по позиції — Кількість одиниць в замовленні має бути ≤ менше або дорівнювати встановленому обмеженню.

  1. Кратність коробці/ящику

  • Для розрахунку в тіло ордера доповнюємо COUNTPIECESINBOX

    • Розраховується як: Кількість одиниць (з ордера) / Од. в коробці (з прайса). Тег в прайсі: QUANTITYOFCUINTU

  • Якщо результат ділення: [Замовлена кількість одиниць / Од. в коробці] по будь-якій з товарних позицій ордера не ціле число то Помилка. Якщо результат Ціле число - Перевірка успішна.

  1. Кратність мін. кіл-ті одиниць

  • Перевірка виконується по полю в прайс-листі Мінімальна кількість одиниць MINORDERQUANTITY

  • Якщо результат ділення Замовлена кількість одиниць / Мінімальна кількість одиниць по одній з позицій /= «0» то користувач отримує помилку.

7 Що потрібно передавати в замовленні, щоб виконувались перевірки по обмеженнях?

Перелік обмежень та обов’язкових тегів:

  1. Мін. сума замовлення без ПДВ

    • Обов’язково в замовленні Тег: ORDERPRICE та ORDEREDQUANTITY

  2. Мін. сума замовлення з ПДВ

    • Обов’язково в замовленні Тег: ORDEREDQUANTITY та PRICEWITHVAT

  3. Макс. сума замовлення без ПДВ

    • Обов’язково в замовленні Тег: ORDERPRICE та ORDEREDQUANTITY

  4. Макс. сума замовлення з ПДВ

    • Обов’язково в замовленні Тег: ORDEREDQUANTITY та PRICEWITHVAT

  5. Макс. кіл-ть товарних позицій

    • Обов’язково в замовленні Тег: POSITIONNUMBER

  6. Макс. вага замовлення, кг

    • Обов’язково в замовленні Тег: UNITWEIGHT та ORDEREDQUANTITY

  7. Макс. кіл-ть коробок

    • Обов’язково в замовленні Тег: BOXESCOUNT

  8. Макс. кіл-ть паллет

    • Обов’язково в замовленні Тег: PALLETS

  9. Контроль залишків та квот

    • Обов’язково в замовленні Тег: ORDEREDQUANTITY

  10. Кратність коробці/ящику

  • Обов’язково в замовленні Тег: ORDEREDQUANTITY та COUNTPIECESINBOX

  1. Кратність мін. кіл-ті одиниць

  • Обов’язково в замовленні Тег: ORDEREDQUANTITY

8 Як продавець інтегровано може додати Обмеження?

Для користувачів що використовують API методи інтеграції потрібно авторизуватись в сервісі використовуючи запит. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на додавання обмеження. В тілі запиту обов’язково вказати GLN покупця для якого потрібно додати ці обмеження, а також вказати їх перелік. Опис приклад запиту за посиланням.

Для користувачів що використовують FTP методи інтеграції потрібно:

  • Сформувати XML документ в якому буде зазначено GLN Покупця та перелік обмежень (приклад за посиланням).

  • Використовуючи Логін та Пароль приєднатися до FTP сервера та розмістити файл в каталозі Outbox.

  • Система опрацює отриманий документ та на web платформі будуть оновлені дані по обмеженнях для покупця.

9 Що потрібно для відправки замовлення по API / FTP?

Для відправки замовлення перш за все потрібно:

  1. Отримати актуальний прайс-лист з набором даних позиції

    • API - потрібно авторизуватись в сервісі використовуючи запит. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на отримання актуального прайс листа. В тілі відповіді на запит ви отримаєте набір даних прайс-листа з описом параметрів позицій.

    • FTP - Сформувати документ прайс-лист в XML форматі без заповненого блока CATALOGUE (приклад за посиланням). В тег ACTION вказати значення “19” (запит прайс-листа на поточну дату). Розмістити файл на FTP в каталозі Outbox. Система опрацює отриманий документ поверне та у відповідь Актуальний прайс-лист. Актуальний прайс-лист буде розміщено в каталозі Inbox.

  2. Отримати актуальний перелік обмежень

    • API - потрібно авторизуватись в сервісі використовуючи запит. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на отримання обмежень. Приклад тіла відповіді з обмеженнями за посиланням.

    • FTP - станом на зараз інтегрованим шляхом отримати обмеження можливість відсутня.

  3. Сформувати відповідно до отриманих даних з прайс-листа та враховуючи встановлені обмеження максимально наповнене замовлення (обов’язкові та опційні поля) з переліком бажаних позицій.

  4. За допомогою обраного типу інтеграції вивантажити замовлення на платформу EDIN Market

    • API - потрібно авторизуватись в сервісі використовуючи запит. Після успішної авторизації використовуючи отриманий ключ “Токен” виконати запит на створення кошика замовлення або запит на автоматичну відправку замовлення без попереднього створення кошика на web платформі.

    • FTP - Сформувати документ XML документ Замовлення (приклад тіла документа за посиланням). Використовуючи Логін та Пароль приєднатися до FTP сервера та розмістити файл в каталозі Outbox.

10 На що звернути увагу при формуванні / відправці замовлення?

При формуванні замовлення необхідно дотримуватися наступних рекомендацій:

  • Дані позиції що заповнюються в замовлення повинні відповідати даним з прайс-листа на підставі якого формується замовлення.

  • Мінімальна наявність даних позиції = Обов’язкові поля за специфікацією. Однак ми також рекомендуємо передавати максимально можливий набір даних в замовлення для коректного розрахунку та перевірки відповідності до встановлених обмежень.

  • Ключовим елементом в замовленні є ознака сервісу. Для того, щоб замовлення було відправлено в сервіс “Маркет” і тілі документа обов’язково має бути тег <DISTRIBUTOR> значення за замовчуванням “1”.

  • Для виконання контролю по встановленим обмеженням обов’язково мають бути вказані теги за яким виконується перевірка (перелік тегів та лімітів за посиланням)

  • Якщо при відправці замовлення було виявлено помилку — то користувач отримує інформаційне сповіщення:

    • API в тілі відповіді на виконання запиту (відповідь сервера)

    • FTP надсилається лист з описом помилки на пошту користувача який відправляє замовлення.