Довідковий центр продавця

Налаштування API

Support EVA.UA

Останнє оновлення 7 днів тому

EVA Merchant Center API v1 — це API для автоматизації роботи із замовленнями на EVA.UA. За допомогою API продавець або технічний інтегратор може:

отримувати список замовлень;
переглядати деталі замовлення;
змінювати статус замовлення;
передавати ТТН разом зі зміною статусу;
передавати причину скасування замовлення.

Документація API:

https://merchant-api.eva.ua/api/docs
Префікс методів:
/api/v1/

Важливо! Поточна версія API не підтримує керування товарами, цінами, залишками або XML-фідами.

1. Коротка інструкція

Крок	Що зробити	Endpoint / дія
1	Отримати доступ до API: username/password для мерчанта	логін та пароль від особистого кабінету
2	Отримати JWT-токени	POST /api/v1/token
3	Передавати access token у кожному захищеному запиті	Authorization: Bearer <access_token>
4	Отримати список замовлень	GET /api/v1/orders
5	Отримати повну деталізацію замовлення	GET /api/v1/orders/{id}
6	Оновити статус замовлення	PATCH /api/v1/orders/{id}/status
7	При скасуванні передати reason_id	status = 9 або 10 + reason_id
8	При підтвердженні з ТТН передати tracking_number	status = 12 + tracking_number
9	Оновлювати access token через refresh token	POST /api/v1/token/refresh

Важливо про ТТН

Окремого методу для створення або оновлення ТТН у поточній версії API немає. ТТН передається у полі tracking_number разом зі зміною статусу замовлення через PATCH /api/v1/orders/{id}/status

# Мінімальний сценарій
1. POST /api/v1/token -> отримати access та refresh
2. GET /api/v1/orders?status=1&limit=20&offset=0 -> отримати нові замовлення
3. GET /api/v1/orders/{id} -> отримати деталі замовлення
4. PATCH /api/v1/orders/{id}/status {"status": 11} -> підтвердити продавцем
5. PATCH /api/v1/orders/{id}/status {"status": 12, "tracking_number": "20400000000000"} -> передати ТТН

2. Повна інструкція

2.1 Авторизація.

API використовує JWT Bearer Authorization. Для всіх захищених методів необхідно передавати access token у заголовку Authorization.

Час життя токенів

access token — 1 день
refresh token — 7 днів

2.2 Отримання токена

Метод	Endpoint	Призначення
POST	/api/v1/token	Приймає username/password і повертає пару токенів access та refresh

curl -X POST "https://merchant-api.eva.ua/api/v1/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
{
  "access": "ACCESS_JWT_TOKEN",
  "refresh": "REFRESH_JWT_TOKEN"
}

2.3. Використання access token

Authorization: Bearer ACCESS_JWT_TOKEN
curl -X GET "https://merchant-api.eva.ua/api/v1/orders" \
-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Accept: application/json"

2.4. Оновлення access token

Метод	Endpoint	Призначення
POST	/api/v1/token/refresh	Приймає refresh token і повертає новий access token, якщо refresh token валідний

curl -X POST "https://merchant-api.eva.ua/api/v1/token/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "REFRESH_JWT_TOKEN"
  }'

Важливо про оновлення: при кожному рефреші ACCESS_TOKEN кожен раз буде отримано новий REFRESH_TOKEN

3. Робота із замовленнями

3.1. Отримати список замовлень

Метод	Endpoint	Призначення
GET	/api/v1/orders	Повертає пагінований список замовлень мерчанта

Параметр	Тип	Dolor
date_from	datetime	Фільтр замовлень, створених після цієї дати
date_to	datetime	Фільтр замовлень, створених до цієї дати
updated_from	datetime	Фільтр замовлень, оновлених після цієї дати
updated_to	datetime	Фільтр замовлень, оновлених до цієї дати
status	string	Фільтр за статусом замовлення
limit	integer	Кількість результатів на сторінку: min=20, max=100
offset	integer	Початковий індекс для пагінації

Код	Статус
1	Нове замовлення
11	Підтверджене продавцем
12	Підтверджене покупцем
9	Скасовано покупцем
10	Скасовано продавцем

curl -X GET "https://merchant-api.eva.ua/api/v1/orders?status=1&limit=20&offset=0" \
-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Accept: application/json"

curl -X GET "https://merchant-api.eva.ua/api/v1/orders?updated_from=2026-05-01T00:00:00Z&limit=100&offset=0" \

-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Accept: application/json

Пагінація
Список замовлень повертається у форматі count, next, previous, results. Інтеграція має обробляти всі сторінки, доки next не стане null.

3.2. Отримати деталі конкретного замовлення

Метод	Endpoint	Призначення
GET	/api/v1/orders/{id}	Повертає повну інформацію про конкретне замовлення

curl -X GET "https://merchant-api.eva.ua/api/v1/orders/ORDER_ID"; \
-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Accept: application/json"

Поле	Опис
id	ID замовлення
status	Поточний статус
created	Дата створення
updated	Дата оновлення
customer	Дані покупця
price	Загальна сума
comment	Коментар покупця
payment	Дані оплати
tracking_number	ТТН, якщо є
recipient	Дані отримувача
shipping	Дані доставки
items	Товари в замовленні

4. Структури даних замовлення

4.1. Товари в замовленні

Поле	Опис
id	ID позиції
article	Артикул
sku	SKU
quantity	Кількість
price	Ціна
name	Назва товару

4.2. Оплата

payment.method	Ipsum
CASH_ON_DELIVERY	Оплата при отриманні
LIQPAY	LIQPAY

payment.status	Опис
pending	Очікує оплати
authorized	Оплачено
failed	Помилка оплати

4.3. Доставка

shipping.method	Опис
novaposhta_warehouse	Нова пошта - відділення
novaposhta_packstation	Нова пошта - поштомат
ukrposhta_postoffice	Укрпошта

{
"method": "novaposhta_warehouse",
"address": {},
"recipient": {},
"price": "80.00"
}

5. Оновлення статусу замовлення

Метод	Endpoint	Призначення
PATCH	/api/v1/orders/{id}/status	Оновлює статус замовлення в межах дозволених переходів

Поле	Коли потрібно	Опис
status	Завжди	Новий статус замовлення
reason_id	Для статусів 9 або 10	Причина скасування
tracking_number	Для статусу 12	ТТН. Передається разом зі зміною статусу. Окремого методу для ТТН немає.

5.1. Дозволені переходи статусів через API

Поточний статус	Можна перевести в	Коментар
1 Нове замовлення	9, 10, 11	Можна скасувати або підтвердити продавцем
11 Підтверджене продавцем	12, 9, 10	Можна підтвердити покупцем або скасувати
12 Підтверджене покупцем	9, 10	Можна скасувати
9 Скасовано покупцем		Фінальний статус
10 Скасовано продавцем	-	Фінальний статус

Обмеження щодо статусу 5 (Відправлено)
Статус 5 не потрібно використовувати в інтеграції мерчанта. Через API він недоступний для переведення через те, що замовлення отримує статус 5 виключно системою під час трекингу ТТН.

5.2. Приклади зміни статусів

Підтвердити замовлення продавцем: 1 ->11

curl -X PATCH "https://merchant-api.eva.ua/api/v1/orders/ORDER_ID/status" \
-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Content-Type: application/json" \
d '{
"satus": 11
}'

Підтвердити покупцем і передати ТТН: 11 -> 12

curl -X PATCH "https://merchant-api.eva.ua/api/v1/orders/ORDER_ID/status" \
-H "Authorization: Bearer ACCESS_JWT_TOKEN" \
-H "Content-Type: application/json" \

-d '{
"status": 12,
"tracking_number": "20400000000000"
}'

Скасувати замовлення продавцем: -> 10

6. Причини скасування

Поле reason_id є обовʼязковим для статусів 9 та 10.

reason_id	Причина
1000	Невірні дані клієнта
1001	Передумав
1002	Вибрав інший товар
1003	Купив в іншому місці
1004	Не підходять умови доставки
1005	Не підходять умови оплати
1006	Відмова при отриманні
1007	Не прийшов за посилкою
1008	Дубль замовлення
1009	Некоректна контактна інформація
1010	Товар пошкоджено службою логістики
1011	Товар втратила служба логістики
1012	Інше
1014	Оптовий покупець
1015	Замовлення покупця з низьким рейтингом
2000	Немає в наявності
2001	Не додзвонився до клієнта
2002	Змінилась ціна
2003	Невірні характеристики товару на сайті
2004	Бракований товар

7. Рекомендований flow інтеграції

Отримати access/refresh token через POST /api/v1/token.
Зберегти access token на backend-стороні.
Періодично викликати GET /api/v1/orders з фільтром updated_from.
Для нових або оновлених замовлень викликати GET /api/v1/orders/{id}.
Зберігати замовлення у внутрішній системі мерчанта.
Після обробки замовлення оновлювати статус через PATCH /api/v1/orders/{id}/status.
Якщо замовлення скасовується - передавати reason_id.
Якщо замовлення підтверджене покупцем і є ТТН - передавати tracking_number разом зі статусом 12.
Якщо access token протермінувався - оновити його через POST /api/v1/token/refresh.

7.1. Приклад синхронізації через updated_from

GET /api/v1/orders?updated_from=2026-05-02T08:00:00Z&limit=100&offset=0

Логіка:

while next is not null:
виконати GET
обробити response.results
перейти на response.next

8. Безпека

Правило	Пояснення
Не зберігати JWT у frontend	Запити до EVA API мають виконуватись із backend-сторони
Не передавати токен у URL	Токени не мають потрапляти у browser history, proxy logs або аналітику
Не логувати повний access/refresh token	У логах потрібно маскувати значення
Не комітити токени в GitHub	Credentials мають зберігатись у secret storage або змінних середовища
Обмежити доступ до інтеграційних налаштувань	Доступ мають мати тільки відповідальні технічні ролі

Правильно:
ERP / CRM / CMS backend -> EVA Merchant API

Неправильно:

Browser frontend -> EVA Merchant API

9. Тестовий чекліст перед запуском

Блок	Що перевірити
Acces	Отримано username/password; виконано POST /api/v1/token; отримано access/refresh; перевірено refresh token.
Orders list	Виконано GET /api/v1/orders; перевірено status, date_from/date_to, updated_from/updated_to, limit/offset; реалізовано next/previous.
Order details	Виконано GET /api/v1/orders/{id}; отримано customer, recipient, shipping, payment, items, tracking_number.
Status update	Перевірено 1 -> 11; 11 -> 12 з tracking_number; скасування 9/10 з reason_id; фінальні статуси не оновлюються далі.
Error handling	Обробляється неправильний token, неіснуючий order id, заборонений status transition, відсутній reason_id, відсутній tracking_number для status 12.

10. Що не підтримується в поточній версії

Функція	Статус у поточній версії
Керування товарами	Не описано в поточному API
Оновлення цін	Не описано в поточному API
Оновлення залишків	Не описано в поточному API
Керування XML-фідами	Не описано в поточному API
Окремий метод для ТТН	Немає. ТТН передається разом зі зміною статусу
Перехід у статус 5	Недоступний через API

Чи була ця стаття корисною?

2 з 2 сподобалась ця стаття