Опис API сервісу Edibox

Опис типової взаємодії між клієнтами через api сервісу Edibox та принципів обміну повідомленнями.

Технічний опис API Edibox також доступний у форматі Edibox OpenApi .

Типова схема обміну

Обмін відбувається за допомогою повідомлень, які зберігаються у сервісі Edibox.

Сторона 1 створює повідомлення у сервісі використовуючи HTTP API - такі повідомлення отримують статус NEW. У повідомленні можуть бути будь-які документи: замовлення, скасування замовлення, рахунок тощо.

Сторона 2 може перевірити наявність нових повідомлень та завантажити їх до себе в систему. Після обробки отриманих повідомлень сторона 2 створює нові повідомлення з відповідними документами та відправляє їх на сервер Edibox, наприклад, відповідь на замовлення.

Згодом Сторона 1 перевіряє наявність нових повідомлень на сервері Edibox і отримує їх.

Далі наведено можливу схему обміну на прикладі створення замовлення покупцем.

Покупець створює замовлення: повідомлення з документом ORDERS.
Через певний час постачальник перевіряє нові повідомлення та отримує повідомлення з документом ORDERS.
Після оброблення повідомлення у себе в системі постачальник створює повідомлення у відповідь з документом відповідь на замовлення - ORDRSP.
Згодом покупець отримує це повідомлення з документом ORDRSP.

Статуси повідомлення

При створенні нового повідомлення воно отримує статус NEW. Коли отримувач перевіряє вхідні повідомлення, то у відповідь будуть надіслані усі повідомлення: і нові, і вже оброблені - оскільки сервіс Edibox не орієнтується, які з отриманих повідомлень отримувач дійсно обробив і зберіг у себе в системі.

Щоб уникнути додаткової обробки старих повідомлень, отримувач може змінювати статуси повідомлень після їх обробки. Найпростіший варіант: ставити статус PROCESSED, тобто оброблено. В такому випадку отримувач зможе швидко отримувати лише нові повідомлення.

Детально про роботу зі статусами можна почитати на окремій сторінці.

Зміна статус не є обов’язковою, однак може істотно полегшити роботу отримувачу при великій кількості повідомлень.

Відправник в будь-який момент може легко розуміти, які з його надісланих повідомлень вже оброблені, а які ще ні.

Авторизація

Всі запити до API повинні використовувати http заголовок (HTTP Header) Authorization: Bearer <API_KEY>, де API_KEY це ключ, який отримано при реєстрації у системі.

Наприклад, Authorization: Bearer edi:OI3usd884nM0

Повідомлення про помилки

Якщо під час запиту до API виникає помилка, то відповідь буде слідувати формату RFC-7807, тобто матиме заголовок Content type: application/problem+json і тіло у форматі json.

Приклад відповіді у разі помилки

{
  "type": "about:blank",
  "title": "Incorrect EDI standard provided",
  "status": 400,
  "detail": "'XML_02' standard is not valid can not be used",
  "instance": "/api/v1/messages"
}

У полі type зазвичай буде значення: about:blank - його можна ігнорувати. Однак інколи поле type міститиме посилання на сторінку з детальним описом вказаної проблеми або з інформацією, яка стосується описаної помилки.

Приклад відповіді з деталізацією у type

{
  "type": "https://edibox.com.ua/docs/api/errors/different-key-msg-sender.html",
  "title": "Некоректний ключ відправника",
  "status": 400,
  "detail": "Ключ API не належить вказаному відправнику.",
  "instance": "/api/v1/messages"
}

У цьому випадку можна відкрити у браузері адресу https://edibox.com.ua/docs/api/errors/different-key-msg-sender.html та прочитати детальний опис та контекст помилки, що виникла.

Перевірка роботи сервісу

GET /api/v1/ping - метод для зручної перевірки роботи сервісу та авторизації. При успішному виконанні метод завжди повертає значення PONG. Метод не потребує передачі жодних додаткових параметрів та об’єктів.

Це зручно для перевірки правильності використання токена та з’єднання з сервером.

Приклад запита з використанням curl

curl -H "Authorization: Bearer edi:1234567890"  https://edibox.com.ua/api/v1/ping

# edi:12345678 - замінити на свій токен
# У відповідь буде отримано текст PONG

Створити повідомлення

POST /api/v1/messages - адреса для створення нових повідомлень. Повідомлення відправляється як тіло цього запиту. При цьому використовується відповідний Content-Type, наприклад, для GS1_XML це application/xml.

Таб. 1. Доступні параметри
`dry_run`	boolean	Активація режиму валідації: `/api/v1/messages?dry_run=true`

Створюючи повідомлення потрібно обов’язково в заголовках запиту через X-Edi-Standard вказати стандарт обміну, якому слідує повідомлення. Зазвичай це GS1_XML.

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

Authorization: Bearer <API_KEY>
X-Edi-Standard: GS1_XML

Решта даних - отримувач, відправник, тип документа і т.д. - містяться всередині самого повідомлення.

Повідомлення можна відправити самому собі, тобто отримувач та відправник - це одна й та ж компанія. Це може бути корисно у період впровадження та тестування. Також в цьому випадку зручно використовувати "нестандартні" статуси.

При використанні формата GS1_XML система валідує XML і у разі помилки повідомляє про неї без збереження повідомлення у системі.

При успішному створенні повідомлення, буде повернуто json з унікальним ідентифікатором цього повідомлення в системі.

Приклад відповіді на успішне створення повідомлення

{ "uuid": "c6a4321f-2673-4ac3-b25d-cd0bf531a4c2" }

Режим валідації повідомлень

dry_run - необов’язковий параметр, що дозволяє виконати лише валідацію повідомлення без збереження у системі. Для активації режиму валідації необхідно передати значення true: POST /api/v1/messages?dry_run=true.

Це може бути корисно у процесі налагодження обміну. Якщо повідомлення коректне, то у відповідь буде отримано Http status 200 та json з пустим uuid.

Відповідь для тестового запиту

{ "uuid": "00000000-0000-0000-0000-000000000000" }

У разі помилки валідації у відповіді буде отримано 400 з відповідним описом помилки у json.

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

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

Змінити статус повідомлення

Всі нові повідомлення автоматично отримують статус NEW. Змінити статус може тільки отримувач.

PUT /api/v1/messages/status - поновлення статусів для вказаних повідомлень. Сюди надсилається масив у вигляді Json, що дозволяє одночасно поновити декілька повідомлень.

Детально про статуси та їхнє значення можна прочитати на сторінці Статуси повідомлень. Специфікацію API можна переглянути тут: Edibox OpenApi

Обов’язкове використання заголовку Content-Type: application/json

Таб. 2. Структура Json для поновлення статусу
Властивість	Тип	Опис
`msg_uuid`	String	Унікальний ідентифікатор повідомлення
`status`	String	Новий статус повідомлення. Обов’язкове використання у верхньому регістрі: не `internal_type_1`, а INTERNAL_TYPE_1

Json для поновлення статусу для одного повідомлення

[
  {
    "msg_uuid": "40c0c4ae-270a-4d67-ad74-ec542bc7982e",
    "status": "PROCESSED"
  }
]

Таб. 3. Перелік доступних статусів:
Статус	Опис
NEW	Усі нові повідомлення отримують цей статус.
PROCESSING	Повідомлення обробляється отримувачем; "в процесі", "в обробці".
PROCESSED	Отримувач обробив повідомлення.
INVALID	Можна позначити некоректне з точки зору отримувача повідомлення, яке отримувач не обробляв взагалі.
INTERNAL_STATUS_1 INTERNAL_STATUS_2 INTERNAL_STATUS_3	Нестандартні статуси для внутрішнього використання сторонами. Можуть мати будь-яке значення в залежності від домовленостей.

Статус повідомлення може змінити тільки отримувач.

Отримати повідомлення

Цей розділ містить загальну інформацію щодо отримання даних від сервісу. Детальний опис API та повний перелік об’єктів json можна побачити на окремій сторінці: Edibox OpenApi

Вхідні повідомлення

GET /api/v1/messages/inbox - всі повідомлення, які було надіслано користувачу

Вихідні/надіслані повідомлення

GET /api/v1/messages/outbox - всі повідомлення, які надіслав користувач

Таб. 4. Параметри для отримання вхідних/надісланих повідомлень
`from_date`*	date	Дата початку пошуку повідомлень в системі: `from_date=2023-06-06`. Обов’язковий параметр. Формат дати: YYYY-MM-DD. Це обов’язковий параметр. Сервіс поверне усі повідомлення створенні починаючи від цієї дати (включно з нею).
`to_date`	date	Дата, включно до якої здійснюється пошук повідомлень в системі: `to_date=2023-06-06`. Формат дати: YYYY-MM-DD.
`status`	string[]	Статус повідомлень, які потрібно отримати. Можна вказати декілька значень через кому: `status=new,processing`. Якщо нічого не вказано, то повертаються повідомлення з усіма статусами.
`type`	string[]	Тип повідомлень, які потрібно отримати. Можна вказати декілька значень через кому: `type=orders,ordrsp`. Якщо нічого не вказано, то повертаються повідомлення усіх типів.
`page_size`	integer	Кількість повідомлень на сторінку. Значення повинно буди в діапазоні [1..100]. Якщо параметр не вказано, то використовується значення за замовченням: 50
`page_token`	string	Використовується для отримання наступної сторінки з повідомленнями. Використовуючи цей токен потрібно повторити параметри запиту, у якому цей токен було отримано. Детально: Токен наступної сторінки.
`sender_gln`	string	GLN номер відправника. Дозволяє отримувачу вибрати повідомлення тільки від конкретного відправника. Має сенс тільки для вхідних повідомлень /api/v1/messages/inbox
`receiver_gln`	string	GLN номер отримувача. Дозволяє відправнику вибрати повідомлення відіслані тільки вказаному отримувачу. Має сенс тільки для надісланих повідомлень /api/v1/messages/outbox

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

Дата створення в системі - завжди правильна і встановлюється в момент створення повідомлення в базі.

Дата повідомлення - це дата, яку в повідомленні вказав відправник. Теоретично тут можу бути будь-яка дата.

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

{
  "data": [ {
    "uuid": "c6a4321f-2673-4ac3-b25d-cd0bf531a4c2",
    "msg": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>...",
    "msg_identifier": "MSG-1000022",
    "msg_datetime": "2023-05-17T19:32:01+03:00",
    "msg_type": "ORDERS",
    "edi_standard": "GS1_XML",
    "sender": {},
    "receiver": {},
    "status": "PROCESSED",
    "created_at": "2023-06-15T17:26:51+03:00",
    "updated_at": "2023-06-15T18:02:39+03:00"
  }],
  "next_page_token": "Y6eh4d9"
}

data - масив, що містить перелік повідомлень. Може бути пустим, якщо запит не повернув повідомлень.
next_page_token - токен для отримання наступної сторінки з результатами. null означає, що наступної сторінки не існую.

Таб. 5. Опис структури повідомлення
`uuid`	Унікальний ідентифікатор повідомлення в сервісі.
`msg`	Безпосередньо надіслане повідомлення.
`msg_identifier`	Ідентифікатор повідомлення, який було присвоєно відправником та вказано в тілі повідомлення.
`msg_type`	Тип повідомлення: замовлення, відповідь на замовлення тощо. Може бути `null`.
`msg_datetime`	Дата та час створення повідомлення, які вказані відправником в тілі повідомлення.
sender	Об’єкт відправника. Повертається тільки для отриманих повідомлень /api/v1/messages/inbox.
receiver	Об’єкт отримувача. Повертається тільки для надісланих повідомлень /api/v1/messages/inbox.
`status`	Статус повідомлення.
`created_at`	Дата та час створення повідомлення в системі.
`updated_at`	Коли повідомлення востаннє було поновлено. Зазвичай це час коли змінювався статус повідомлення. Може бути `null`.
`next_page_token`	Токен для отримання наступної сторінки з результатами запиту. Може бути `null`.

Токен наступної сторінки

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

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

Щоб використати значення next_page_token у запиті, потрібно повністю повторити всі параметри запиту, в якому цей токен наступної сторінки було отримано.

Розмір сторінки відповідей залежить від параметра page_size. Якщо параметр не вказано, то використовується значення за замовченням. Максимальне значення для page_size та значення за замовленням можна перевірити в описі Edibox OpenApi

Наприклад:

Отримання нових (NEW) повідомлень починаючи з 01.06.2023 з розбиттям по 80 повідомлень на сторінку.
GET /api/v1/messages/inbox?from_date=2023-06-01&page_size=80&status=new

Результат запиту

{
  "data": [
    // масив повідомлень
  ],
  "next_page_token": "Y6eh4d9"
}

Наявність токена означає, що отримано 80 повідомлень, і результат цього запиту має ще наступні сторінки.

Для отримання наступної порції слід використати попередній запит і додати до нього токен наступної сторінки:
GET /api/v1/messages/inbox?from_date=2023-06-01&page_size=80&status=new&page_token=Y6eh4d9

Цей запит поверне наступну порцію/сторінку повідомлень. Якщо у результаті знову буде токен next_page_token, то це означатиме, що є ще одна сторінка з наступною порцією повідомлень.

На останній сторінці значення next_page_token дорівнюватиме null.

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

Приклади

GET /api/v1/messages/inbox?from_date=2023-06-01
Отримання всіх вхідних повідомлень починаючи з 2023-06-01.

GET /api/v1/messages/inbox?from_date=2023-09-04?to_date=2023-09-10
Отримання всіх вхідних повідомлень починаючи за тиждень 04.09.2023 - 10.09.2023.

GET /api/v1/messages/inbox?from_date=2023-06-01&status=new
Дозволяє отримати тільки нові вхідні повідомлення, які адресовані отримувачу. Цей запит має сенс тільки у випадку, якщо отримувач використовує поновлення статусів.

GET /api/v1/messages/inbox?from_date=2023-09-01&type=PRODAT&status=new&sender_gln=1234567890123
Повертає тільки нові вхідні специфікації на товари від постачальника з GLN 1234567890123, які надійшли отримувачу починаючи з дати 1 вересня 2023.

Щоб розрізнити нові повідомлення отримувач повинен використовувати поновлення статусів.

GET /api/v1/messages/outbox?from_date=2023-06-01&status=new
Якщо отримувач використовує поновлення статусів, то відправник може таким чином перевірити, чи всі його надіслані повідомлення вже оброблено. Якщо цей запит верне якісь повідомлення, то це означає, що отримувач їх ще не обробив.

GET /api/v1/messages/outbox?from_date=2023-06-01&status=processing,processed
Повертає тільки ті надіслані повідомлення, які вже оброблені отримувачем або ще ним обробляються. Цей запит має сенс тільки у випадку, якщо отримувач використовує поновлення статусів.