API обробка замовлень
URL для запитів – https://toysi.ua/api.php
Кодування всіх запитів та відповідей – UTF-8
Форма для тестування – https://toysi.ua/api-test.html
JSON-відповідь на запит створення замовлення
Коди відповіді на запит створення замовлення
JSON-відповідь на запит статусу замовлення
Коди відповідей на запит статусу замовлення
Коди товарів та поточні залишки товарів можна отримати з XML-експорту (посилання на посібник з XML-експорту видає персональний менеджер). Код товару в XML – це атрибу id тегу <offer> (враховуйте зсув id, якщо ви використовуєте параметр shift у посиланні експорту)
Параметри POST-запиту:
|
Назва змінної |
Значення змінної |
|
api_version (integer) |
1 |
|
api_method |
"order_create" |
|
auth_user (string) |
Ідентифікатор користувача API, який можна знайти в особистому кабінеті |
|
auth_key (string) |
Секретний ключ користувача API, який можна знайти в особистому кабінеті |
|
internal_order_id (string) |
До 25 символів. Унікальний номер замовлення у вашій базі даних. (Кінцеві пробіли видаляйте - вони будуть сприйматися як частина номера замовлення) |
|
positions_count (integer) |
Кількість позицій (не товарів) замовлення. Максимальна кількість – 1000 |
|
positions_quantity (array) |
Масив кількості товару у позиціях замовлення. Ключами масиву є коди товарів нашого магазину. Приклад: array (11623=>1, 11638=>10). При обробці вхідних даних кількість приводиться до integer |
|
comment (string) |
Необов'язковий. Коментар до замовлення. Максимальна довжина коментаря – 500 символів |
|
shipping_warehouse_id (integer) |
Числовий номер складу перевізника. Повинен дорівнювати 0, якщо доставка на адресу, а не на склад/відділення |
|
shipping_carrier_name (string) |
Назва перевізника – довільний рядок. Для "самовивозу" потрібно вказувати рядок "toysi" у поєднанні з shipping_warehouse_id=1 |
|
shipping_city (string) |
Місто доставки. Бажано з областю та районом, щоб унеможливити ситуації, коли місто клієнта може виявитися не тим, що у перевізника (при створенні ТТН), хоча назва міст однакова |
|
shipping_city_id (string) |
Ідентифікатор міста за довідником міст перевізника. Необов'язковий у разі адресної доставки. У разі доставки на відділення перевізника обов'язково вказувати (для того, щоб коректно знайти місто та відділення) |
|
shipping_address (string) |
Обов'язковий параметр. Але може бути порожнім рядком, якщо shipping_warehouse_id>0 |
|
shipping_firstname (string) |
Ім'я одержувача |
|
shipping_lastname (string) |
Прізвище одержувача |
|
shipping_middlename (string) |
Необов'язковий. По батькові одержувача |
|
shipping_phone (string) |
Телефон одержувача – 12 цифр, перші три з яких "380". Приклад: 380501234567 |
|
shipping_dt (string) |
Бажані дата та час доставки за київським часом. Приклад:"2018-12-31 15:30:00" |
|
shipping_moneyback (float) |
Сума післяплати в гривнях. Десятковий роздільник – крапка. Приклад: 100.99 |
|
shipping_declared_value (integer) |
Необов'язковий. Оголошена цінність посилки у гривнях. Впливає на вартість доставки транспортною компанією. Якщо параметр не вказано або не є числом або числом менше мінімально допустимого, то при створенні ТТН буде використано мінімально допустиме (на цей час це число 200) |
|
redirect_url (string) |
Необов'язковий. Якщо запит виконує браузер, то після створення замовлення можна перенаправити користувача на будь-який URL. В кінець redirect_url будуть додані GET-параметри (всі параметри з json-відповіді, крім масивів), тому обов'язково завершуйте redirect_url знаком ? або &. Приклад: https://example.com/? |
|
api_mode (string) |
Необов'язковий. Якщо дорівнює " test", то замовлення не оброблятиметься менеджером. Наявне тестове замовлення видаляється при створенні звичайного замовлення з тим самим internal_order_id. Тестові замовлення, якому більш як 41 день, видаляються автоматично |
|
ttn (string) |
Необов'язковий. Номер ТТН (для Нової Пошти – 14 цифр) |
Усі параметри є обов'язковими, крім тих, які оголошені необов'язковими.
Усі речові числа віддаються у вигляді рядків. Розділювач – крапка.
Опис елементів масиву:
|
Ключ |
Значення |
|
response_code (integer) |
Код відповіді. Таблиця можливих кодів представлена нижче |
|
response_msg (string) |
Текст відповіді |
|
internal_order_id (string) |
Унікальний номер замовлення у вашій базі даних |
|
order_id (integer) |
Номер замовлення Toysi |
|
sum (string) |
Сумарна вартість замовлення без урахування знижки, у гривнях |
|
sum_with_discount (string) |
Сумарна вартість замовлення з урахуванням знижки |
|
personal_discount (string) |
Персональна знижка. "0.15" означає 15%. (До деяких товарів магазину знижка не застосовується або застосовується частково) |
|
shipping_moneyback (string) |
Сума післяплати у гривнях |
|
positions_price (array) |
Масив цін замовлених товарів, без урахування знижки. Ключами масиву є коди товарів |
|
positions_discount_price (array) |
Масив цін замовлених товарів з урахуванням знижки. Ключами масиву є коди товарів |
|
positions_name (array) |
Масив назв замовлених товарів, у форматі "[артикул] Назва товару". Ключами масиву є коди товарів |
|
positions_quantity (array) |
Масив кількості замовлених товарів. Ключами масиву є коди товарів |
Приклади JSON-відповіді
{
"response_code":2,
"response_msg":"Ви вже створили раніше замовлення з таким номером internal_order_id.",
"internal_order_id":"тест1",
"order_id":100022030,
"sum":"3187.59",
"personal_discount":"0.15",
"sum_with_discount":"2709.43",
"shipping_moneyback":"0",
"positions_price":{
"50485":"74.13",
"50489":"74.13"
},
"positions_discount_price":{
"50485":"63.01",
"50489":"63.01"
},
"positions_name":{
"50485":"[SM1585] Іграшка - Антистрес з ароматом "Squishy Панда"",
"50489":"[SM1588] Іграшка - Антистрес з ароматом "Squishy Смайл""
},
"positions_quantity":{
"50485":33,
"50489":10
}
}
При фатальних response_code, масив містить тільки response_code та response_msg
{
"response_code":3,
"response_msg":"Не вдалося створити замовлення, спробуйте ще раз."
}
Усі, крім кодів 1 та 2 – фатальні помилки. Код 3 передбачає повторну спробу.
Якщо response_code=2 (а це можливо через дублювання http-запиту), то JSON-відповідь така сама, як при response_code=1 – містить інформацію про замовлення на момент його створення (див. приклад JSON-відповіді). Проте, початкова інформація про замовлення – те, що було на момент його створення – зберігається 40 днів. Якщо пізніше 40 днів спробувати повторно створити замовлення з таким самим internal_order_id, то відповідь буде містити тільки response_code=2, response_msg, internal_order_id, order_id.
|
response_code |
response_msg |
|
0 |
Неправильна версія API або метод API |
|
1 |
Замовлення прийняте |
|
2 |
Ви вже створили замовлення з таким номером internal_order_id |
|
3 |
Не вдалося створити замовлення, спробуйте ще раз |
|
4 |
У запиті немає одного або декількох обов'язкових параметрів POST |
|
5 |
Неправильний користувач або ключ API |
|
6 |
Дуже довгий internal_order_id |
|
7 |
Неправильна або занадто велика кількість позицій замовлення (максимум 1000) |
|
8 |
positions_quantity не масив чи порожній |
|
9 |
Довжина масиву positions_quantity не відповідає числу позицій positions_count |
|
11 |
Один або кілька кодів товарів відсутні в нашій базі даних або неправильні |
|
12 |
Один або кілька ключів масиву positions_quantity не є integer |
|
13 |
Неправильна кількість товару в одній із позицій |
|
14 |
Порожнє ім'я отримувача |
|
15 |
Порожнє прізвище отримувача |
|
16 |
Неправильний телефон отримувача |
|
17 |
Неправильний час доставки |
|
18 |
Неправильна сума післяплати |
|
19 |
Порожня назва перевізника |
|
20 |
Порожня адреса доставки |
|
21 |
Порожнє місто доставки |
Будь ласка, зверніть увагу на можливість отримання статусу відразу 500 замовлень методом "order_status". Якщо ви не будете використовувати цю можливість і надсилатимете запит по кожному замовленню окремо, то під час досить активних продажів ви зіткнетеся з тим, що ваша програма буде тільки й робити, що надсилати запити. Наш сервер налаштований приймати не більше 5 запитів в секунду (з допустимими сплесками 10 запитів у сек), а на запити, що не вписуються в ці межі, віддається відповідь 503 Service Unavailable. Функція PHP array_chunk() допоможе дуже просто розбити на частини масив номерів замовлень
Параметри POST-запиту:
|
Назва змінної |
Значення змінної |
|
api_version (integer) |
1 |
|
api_method (string) |
"order_status" – статуси та основна інформація "order_positions" – відповіді цього методу будуть масиви інформації про поточні позиції замовлення, плюс вся інформація з відповіді методу "order_status" |
|
auth_user (string) |
Ідентифікатор користувача API, який можна знайти в особистому кабінеті |
|
auth_key (string) |
Секретний ключ користувача API, який можна знайти в особистому кабінеті |
|
order_id (string) |
Номери замовлень Toysi, розділені комами. Для методу "order_positions" можна вказати лише один номер замовлення. Для методу "order_status" – до 500 номерів |
|
search_in (string) |
Необов'язковий. Якщо параметр дорівнює "all_orders", то пошук буде здійснюватися за всіма замовленнями, інакше - тільки за замовленнями, створеними методами цього API |
Усі дійсні числа віддаються у вигляді рядків.
Опис елементів масиву:
|
Ключ |
Значення |
|
order_id (integer) |
Номер замовлення Toysi |
|
status (integer) |
Код статусу замовлення. Таблиця кодів наведена нижче |
|
last_sum_update_dt (string) |
Дата та час останньої зміни кількості товарів або кількості позицій чи персональної знижки, що впливає на ціни товарів та загальну вартість замовлення. Якщо ці параметри замовлення не редагувалися менеджером, то last_sum_update_dt="0000-00-00 00:00:00". Приклад:"2018-12-31 23:01:59" |
|
order_is_paid (integer) |
0 – замовлення поки не відмічено як оплачене 1 – замовлення відмічено як оплачене Процес обробки замовлення побудований так, що order_is_paid може стати рівним 1 не раніше ніж замовлення отримає статус Упакований. Тому значення 0 не означає, що оплата не надійшла |
|
place_count (integer) |
Кількість місць посилки. Стає відомо після упаковки |
|
sum (string) |
Сумарна вартість замовлення без урахування знижки, у гривнях |
|
sum_with_discount (string) |
Сумарна вартість замовлення з урахуванням знижки |
|
personal_discount (string) |
Персональна знижка. "0.15" означає 15%. (До деяких товарів знижка не застосовується або застосовується частково) |
|
shipping_moneyback (string) |
Сума післяплати у гривнях |
|
positions_price (array) |
Масив цін замовлених товарів, без урахування знижки. Ключами масиву є коди товарів |
|
positions_discount_price (array) |
Масив цін замовлених товарів з урахуванням знижки. Ключами масиву є коди товарів |
|
positions_name (array) |
Масив назв замовлених товарів у форматі "[артикул] Назва товару". Ключами масиву є коди товарів |
|
positions_quantity (array) |
Масив кількості замовлених товарів. Ключами масиву є коди товарів |
|
shipping_carrier_name (string) |
(в розробці) Назва перевізника. Реалізовано тільки для Нової Пошти. Коли номер ТТН вже визначено, віддається рядок "Нова Пошта", інакше віддається порожній рядок |
|
TTN (string) |
(в розробці) Номер ТТН. Реалізовано тільки для Нової Пошти. Коли номер ТТН вже визначено, надається номер ТТН, інакше віддається порожній рядок |
Приклад JSON-відповіді (метод order_status)
{
"100022020":{
"order_id":100022020,
"status":503
},
"100022030":{
"order_id":100022030,
"status":0,
"last_sum_update_dt":"2018-12-31 23:01:05",
"order_is_paid":0,
"place_count":0,
"shipping_carrier_name":"",
"TTN":"",
"sum":"3187.59",
"personal_discount":"0.15",
"sum_with_discount":"2709.43",
"shipping_moneyback":"0"
},
"100022032":{
"order_id":100022032,
"status":0,
"last_sum_update_dt":"0000-00-00 00:00:00",
"order_is_paid":0,
"place_count":0,
"shipping_carrier_name":"",
"TTN":"",
"sum":"1482.6",
"personal_discount":"0.15",
"sum_with_discount":"1260.2",
"shipping_moneyback":"101"
}
}
Приклад JSON-відповіді (метод order_positions)
{
"100022030":{
"order_id":100022030,
"status":0,
"last_sum_update_dt":"2018-12-31 23:01:05",
"order_is_paid":0,
"place_count":0,
"shipping_carrier_name":"",
"TTN":"",
"sum":"3187.59",
"personal_discount":"0.15",
"sum_with_discount":"2709.43",
"shipping_moneyback":"0",
"positions_price":{
"50485":"74.13",
"50489":"74.13"
},
"positions_discount_price":{
"50485":"63.01",
"50489":"63.01"
},
"positions_name":{
"50485":"[SM1585] Іграшка - Антистрес з ароматом "Squishy Панда"",
"50489":"[SM1588] Іграшка - Антистрес з ароматом "Squishy Смайл""
},
"positions_quantity":{
"50485":33,
"50489":10
}
}
}
При фатальних response_code, масив містить тільки response_code та response_msg
{
"response_code":404,
"response_msg":"Замовлення не знайдено."
}
Якщо пошук по всіх номерах замовлень не дав жодного результату, буде видано фатальний response_code=404. Якщо у запиті декілька номерів і хоча б одне замовлення знайдено, відповідь не міститиме response_code і response_msg. У цьому випадку відповідь матиме інформацію лише про знайдені замовлення. Якщо в масиві немає жодного з номерів замовлень із запиту, це замовлення не знайдено
|
response_code |
response_msg |
|
0 |
Неправильна версія API або метод API |
|
4 |
У запиті немає одного або декількох обов'язкових параметрів POST |
|
400 |
Неправильний номер замовлення або багато номерів (максимум 500 для запиту статусу, максимум 1 для запиту позицій) |
|
404 |
Замовлення не знайдено |
На будь-якому з етапів замовлення може відкотитися до будь-якого з попередніх етапів або перейти до будь-якого з наступних.
|
status |
Назва |
Коментар |
|
0 |
Невизначений |
Замовлення щойно прийняте або знаходиться між якимись двома етапами |
|
10 |
Скасовано |
|
|
20 |
Частково зарезервований |
Деяких товарів не виявилося на складі у потрібній кількості, але їх ще можуть знайти. Якщо не знайдуть, менеджер дзвонитиме і погоджуватиме зменшення їх кількості |
|
30 |
Повністю зарезервовано |
За всіма позиціями замовлення товар зарезервований на складі |
|
40 |
На збиранні |
|
|
50 |
Запакований |
|
|
60 |
Відвантажений |
|
|
70 |
Доставлено |
(в розробці) На даний момент цей статус не віддається ніколи |
|
80 |
Повернутий |
(в розробці) Замовлення скасовано після того, як було відвантажено. На даний момент цей статус не віддається ніколи |
|
503 |
Замовлення дуже старе |
Замовлення створено понад 40 днів, тому воно більше не обслуговується API. Якщо у замовлення цей статус, то опитування статусу цього замовлення слід припинити. У масиві JSON-відповіді для замовлень з такими статусами немає жодної інформації, крім номера (див. приклад JSON-відповіді для методу order_status) |