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

Функція orders/get (<http://<DOMAIN>>/api/orders/get/)

Параметры для тела запроса:

• token — ключ авторизации полученный через функцию auth.

• from — показать заказы от указанной даты (включительно). Необязательный параметр.
  Формат даты:

  • YYYY-MM-DD

  • DD.MM.YYYY

  • Начиная с версии 3.30

  • YYYY-MM-DD HH:mm:ss

  • DD.MM.YYYY HH:mm:ss

• to — показать заказы до указанной даты (включительно). Необязательный параметр.
  Формат даты:

  • YYYY-MM-DD

  • DD.MM.YYYY

  • Начиная с версии 3.30

  • YYYY-MM-DD HH:mm:ss

  • DD.MM.YYYY HH:mm:ss

• ids[] — номера заказов для отображения

• status — показать заказы с выбранными статусами (выгрузить все статусы можно через функцию orders/get_available_statuses). Необязательный параметр. Параметр можно передавать как массив или переменную (status=1 или status[]=1&status[]=2, {status:1}, {status:[1, 2]}). Возможные значения:

  • 1 — новый

  • 2 — в обработке

  • 3 — доставлен

  • 4 — не доставлен

  • 6 — доставляется

• additionalData — boolean значение (true или false). Позволяет выгрузить дополнительную информацию о заказе, например, данные о ТТН Новой Почты, складе получателя и отправителя.

• Начиная с версии 3.30

• offset — смещение относительно начала выборки заказов (работает только в паре с параметром limit)

• limit — количество выводимых заказов

Ответ:

• status

  • OK — заказы успешно найдены

  • EMPTY — заказы не найдены

• response.orders — массив, содержащий заказы

  • response.orders[i]

    • order_id — номер заказа

    • user — идентификатор пользователя в системе (уникален для каждого пользователя)

    • delivery_name — ФИО получателя

    • delivery_email — email (уникален для каждого пользователя внутри системы, дублирование невозможно)

    • delivery_phone — номер телефона

    • delivery_city — город

    • delivery_address — адрес доставки (при выборе варианта доставки УкрПочтой поля разбиваются символом @)

    • delivery_type — тип доставки

      • delivery_type.id — идентификатор доставки в API. Получить информацию о вариантах доставки можно через функции: delivery/export и delivery/exportTypes.

        • 3 — Новой почтой

        • 8 — Самовывоз

        • 9 — Укрпочтой

        • и т. д. (на каждом проекте идентификаторы вариантов доставки могут отличаться)

      • delivery_type.title — название варианта доставки

    • delivery_price — стоимость доставки ("delivery_price": -1 — означает, что стоимость доставки рассчитывается по тарифам перевозчика)

    • comment — комментарий покупателя к заказу

    • payment_type — тип оплаты. Получить информацию о вариантах оплаты можно через функции: payment/export и payment/exportMethods.

      • payment_type.id — идентификатор оплаты в API

        • 11 — Оплата курьеру

        • 12 — Безналичный расчет

        • 13 — Наличными

        • 14 — Онлайн-оплата кредитной картой

        • 15 — Оплата при получении (наложенный платеж)

        • и т. д.

      • payment_type.title — название варианта оплаты

    • payment_price — комиссия за оплату

    • payed — оплачено (1 — да; 0 — нет)

    • total_default — стоимость товаров (без учета скидок)

    • total_sum — итоговая стоимость (с учетом всех скидок, но без учета стоимости доставки)

    • total_quantity — общее количество товаров в заказе

    • discount_percent — относительная скидка

    • discount_value — сумма скидки

    • coupon_code — код купона на скидку

    • coupon_percent — относительная скидка купона

    • coupon_discount_value — сумма скидки по купону

    • coupon_type — тип купона

      • 0 — без купона

      • 1 — сертификат на сумму

      • 2 — многоразовый купон на скидку

    • stat_status — статус заказа. Получить информацию о всех статусах заказов можно через функцию orders/get_available_statuses (доступно начиная с версии 4.0).

      • 1 — новый

      • 2 — в обработке

      • 3 — доставлен

      • 4 — не доставлен

    • stat_created — дата и время оформления заказа (пример: 2021-04-09 12:09:01)

    • currency — валюта в которой был оформлен заказ (в формате ISO, например: UAH — гривна, USD — доллар, EUR — евро и т. д.). Получить информацию о всех валютах можно через функцию currency/export.

    • order_without_callback — boolean значение (true или false). Нужно ли перезванивать покупателю (добавлено в версии 3.32).

    • manager_id - id менеджера который обрабатывал заказ

    • manager_comment - комментарий менеджера

    • manager_discount - скидка от менеджера

    • manager_discount_title - название скидки от менеджера

    • delivery_country - страна доставки (если включена функция выбора стран на странице оформления заказа)

    • products[i] — товары в заказе

      • title — название товара

      • article — артикул товара

      • price — стоимость единицы товара для пользователя

      • quantity — количество заказанных единиц товара

      • total_price — итоговая стоимость товара с учетом заказанного количества

      • discount_marker — маркер использованной скидки на товар

        • PRICE_OLD — старая цена / относительная скидка на товар

        • PAGE_DISCOUNT — скидка на раздел

        • DISCOUNT_CARD — накопительная скидка

        • DISCOUNT_NONE — отсутствие скидки (при условиях акций и т. д.)

        • NONE — без скидки

      • type — данный параметр появился в v4.7.0 и может содержать такие значения (как определить какой товар относиться к комплекту, или к какому товару относится подарок можно на примере этого скриншота):

        • gift_parent — товар, к которому был добавлен подарок

        • gift — сам подарок

        • set_main — товар, к которому был добавлен комплект

        • set_item — товар, входящий в комплект

      • storage_id — уникальный идентификатор, который в последствии передаётся в следующий параметр parent_storage_id, для указания связи между товарами на уровни комплектов / подарков

      • parent_storage_id — если значение null — значит, что к товару был добавлен подарок или товары в комплект (на данном скриншоте показан пример связи между товарами).

    • additional_data — дополнительная информация о заказе (отображается только в том случае, если в теле запроса передать ключ "additionalData": true)

      • np_ref — идентификатор электронной накладной (далее ЭН) для API Новой Почты v.2

      • np_number — номер ЭН

      • sender_warehouse_ref — идентификатор склада отправителя в API Новой Почты

      • recipient_warehouse_ref — идентификатор склада получателя в API Новой Почты для способа доставки “Новая почта” (на отделение)

      • recipient_address — данные об адресе получателя для способа доставки “Курьером Новой почты”(адресная доставка):

        • recipient_address.street_id –– идетнификатор улицы получателя в API Новой Почты

        • recipient_address.street_name –– название улицы

        • recipient_address.building_number –– номер дома

        • recipient_address.flat –– номер квартиры

• delivery_data - массив данных о способе доставки

  • deliveryOperatorType- тип оператора доставки. Возможные значения: nova_poshta, ukrposhta

  • tnID — уникальный идентификатор ЭН

  • tnNumber — номер ЭН

  • tnStatusName — текст статуса накладной у оператора

  • tnTrackingUpdateDate — время последнего изменения статуса у оператора

  • estimatedDeliveryDate — предполагаемая дата доставки

  • departure

    • sender — массив данных по отправителю

      • id — уникальный идентификатор отправителя в базе оператора доставки

      • title — название отправителя

      • contactPerson — массив данных по контактному лицу (передается только для deliveryOperatorType= **nova_poshta)

        • id — уникальный идентификатор контактного лица в базе оператора доставки

        • name — имя контактного лица

        • phone — телефон контактного лица

      • type — тип отправителя (ключ передается только для deliveryOperatorType= **ukrposhta) . Возможные значения:

        • COMPANY — Юридическое лицо

        • PRIVATE_ENTREPRENEUR — ФЛП

        • INDIVIDUAL — Физическое лицо

      • phone — телефон отправителя (ключ передается только для deliveryOperatorType= **ukrposhta)

  • address

    • type — тип адреса отправителя. Возможные значения: warehouse

    • geoObject — массив данных о складе отправителя

      • id — уникальный идентификатор города отправителя в базе оператора доставки

      • name — город отправителя

    • warehouse (передается для type = warehouse)

      • id — идентификатор склада отправителя в базе оператора доставки

      • name — склад отправителя

  • destination

    • recipient — массив данных о получателе

      • name— имя получателя

      • surname— фамилия получателя

      • patronymic— отчество получателя

      • phone — телефон получателя

    • address — массив данных об адресе получателя

      • type — тип адреса отправителя. Возможные значения: warehouse / doors

      • geoObject — данные о городе

        • id — уникальный идентификатор города в базе оператора доставки

        • name — город получателя

      • warehouse — данные о складе (передается для type = warehouse)

        • id — уникальный идентификатор склада получателя в базе оператора доставки

        • name — склад получателя

      • street — данные о адресе для курьерской доставки (передается для type = doors)

        • id — уникальный идентификатор улицы в базе оператора доставки

        • name — название улицы

      • buildingNumber — номер дома получателя (передается для type = doors)

      • flatNumber — номер квартиры получателя (передается для type = doors)

  • payment — данные об оплате услуг за доставку

    • type — тип оплаты услуг доставки (ключ передается только при ****deliveryOperatorType= ****nova_poshta)

    • payer — плательщик за услуги доставки

  • redelivery — данные об обратной доставке

    • cost — сумма обратной доставки

    • payer — плательщик за обратную доставку

Примечание: передача информации о заказе осуществляется на языке той версии сайта, на которой он был сделан.

Параметри для тіла запиту:

• token - ключ авторизації отриманий через функцію auth.

• from - показати замовлення від зазначеної дати (включно). Необов'язковий параметр. Формат дати:

  • YYYY-MM-DD

  • DD.MM.YYYY

  • Починаючи з версії 3.30

  • YYYY-MM-DD HH:mm:ss

  • DD.MM.YYYYY HH:mm:ss

• to - показати замовлення до зазначеної дати (включно). Необов'язковий параметр. Формат дати:

  • YYYY-MM-DD

  • DD.MM.YYYY

  • Починаючи з версії 3.30

  • YYYY-MM-DD HH:mm:ss

  • DD.MM.YYYYY HH:mm:ss

• ids[] - номери замовлень для відображення

• status - показати замовлення з обраними статусами (вивантажити всі статуси можна через функцію orders/get_available_statuses). Необов'язковий параметр. Параметр можна передавати як масив або змінну (status=1 або status[]=1&status[]=2, {status:1}, {status:[1, 2]}). Можливі значення:

  • 1 - новий

  • 2 - в обробці

  • 3 - доставлено

  • 4 - не доставлено

  • 6 - доставляється

• additionalData - boolean значення (true або false). Дозволяє вивантажити додаткову інформацію про замовлення, наприклад, дані про ТТН Нової Пошти, склад одержувача і відправника.

• Починаючи з версії 3.30

• offset - зміщення щодо початку вибірки користувачів (працює тільки в парі з параметром limit)

• limit - кількість виведених замовлень

Відповідь:

• status

  • OK - замовлення успішно знайдено

  • EMPTY - замовлення не знайдено

• response.orders - масив, що містить замовлення

  • response.orders[i]

    • order_id - номер замовлення

    • user - ідентифікатор користувача в системі (унікальний для кожного користувача)

    • delivery_name - ПІБ одержувача

    • delivery_email - email (унікальний для кожного користувача всередині системи, дублювання неможливе)

    • delivery_phone - номер телефону

    • delivery_city - місто

    • delivery_address - адреса доставки (при виборі варіанту доставки Укрпоштою поля розбиваються символом @)

    • delivery_type - тип доставки

      • delivery_type.id - ідентифікатор доставки в API. Отримати інформацію про варіанти доставки можна через функції: delivery/export і delivery/exportTypes.

        • 3 - Новою поштою

        • 8 - Самовивіз

        • 9 - Укрпоштою

        • і т. д. (на кожному проєкті ідентифікатори варіантів доставки можуть відрізнятися

  • delivery_type.title - назва варіанта доставки

  • delivery_price - вартість доставки ("delivery_price": -1 - означає, що вартість доставки розраховується за тарифами перевізника)

  • comment - коментар покупця до замовлення

  • payment_type - тип оплати. Отримати інформацію про варіанти оплати можна через функції: payment/export і payment/exportMethods.

    • payment_type.id - ідентифікатор оплати в API

      • 11 - Оплата кур'єру

      • 12 - Безготівковий розрахунок

      • 13 - Готівкою

      • 14 - Онлайн-оплата кредитною карткою

      • 15 - Оплата при отриманні (накладений платіж)

      • тощо.

  • payment_type.title - назва варіанта оплати

  • payment_price - комісія за оплату

  • paided - оплачено (1 - так; 0 - ні)

  • total_default - вартість товарів (без урахування знижок)

  • total_sum - підсумкова вартість (з урахуванням усіх знижок, але без урахування вартості доставки)

  • total_quantity - загальна кількість товарів у замовленні

  • discount_percent - відносна знижка

  • discount_value - сума знижки

  • coupon_code - код купона на знижку

  • coupon_percent - відносна знижка купона

  • coupon_discount_value - сума знижки за купоном

  • coupon_type - тип купона

    • 0 - без купона

    • 1 - сертифікат на суму

    • 2 - багаторазовий купон на знижку

  • stat_status - статус замовлення. Отримати інформацію про всі статуси замовлень можна через функцію orders/get_available_statuses (доступно починаючи з версії 4.0).

    • 1 - новий

    • 2 - в обробці

    • 3 - доставлено

    • 4 - не доставлено

  • stat_created - дата і час оформлення замовлення (приклад: 2021-04-09 12:09:01)

  • currency - валюта, у якій було оформлено замовлення (у форматі ISO, наприклад: UAH - гривня, USD - долар, EUR - євро тощо). Отримати інформацію про всі валюти можна через функцію currency/export.

  • order_without_callback - boolean значення (true або false). Чи потрібно передзвонювати покупцеві (додано у версії 3.32).

  • manager_id - id менеджера, який обробляв замовлення

  • manager_comment - коментар менеджера

  • manager_discount - знижка від менеджера

  • manager_discount_title - назва знижки від менеджера

  • delivery_country - країна доставки (якщо ввімкнено функцію вибору країн на сторінці оформлення замовлення)

  • products[i] - товари в замовленні

    • title - назва товару

    • article - артикул товару

    • price - вартість одиниці товару для користувача

    • quantity - кількість замовлених одиниць товару

  • total_price - підсумкова вартість товару з урахуванням замовленої кількості

  • discount_marker - маркер використаної знижки на товар

    • PRICE_OLD - стара ціна / відносна знижка на товар

    • PAGE_DISCOUNT - знижка на розділ

    • DISCOUNT_CARD - накопичувальна знижка

    • DISCOUNT_NONE - відсутність знижки (за умов акцій тощо)

    • NONE - без знижки

  • type - цей параметр з'явився у v4.7.0 і може містити такі значення (як визначити, який товар належить до комплекту, або до якого товару належить подарунок, можна на прикладі цього скріншота):

  • gift_parent - товар, до якого було додано подарунок

  • gift - сам подарунок

  • set_main - товар, до якого було додано комплект

  • set_item - товар, що входить до комплекту

  • storage_id - унікальний ідентифікатор, який надалі передається в наступний параметр parent_storage_id, для вказівки зв'язку між товарами на рівні комплектів / подарунків

  • parent_storage_id - якщо значення null - значить, що до товару було додано подарунок або товари в комплект (на цьому скріншоті показано приклад зв'язку між товарами).

  • additional_data - додаткова інформація про замовлення (відображається тільки в тому випадку, якщо в тілі запиту передати ключ "additionalData": true)

    • np_ref - ідентифікатор електронної накладної (далі ЕН) для API Нової Пошти v.2

    • np_number - номер ЕН

    • sender_warehouse_ref - ідентифікатор складу відправника в API Нової Пошти

    • recipient_warehouse_ref - ідентифікатор складу одержувача в API Нової Пошти для способу доставки "Нова пошта" (на відділення)

    • recipient_address - дані про адресу одержувача для способу доставки "Кур'єром Нової пошти" (адресна доставка):

    • recipient_address.street_id -- йденіфікатор вулиці одержувача в API Нової Пошти

    • recipient_address.street_name -- назва вулиці

    • recipient_address.building_number -- номер будинку

    • recipient_address.flat -- номер квартири

  • delivery_data - масив даних про спосіб доставки

    • deliveryOperatorType -- тип оператора доставки. Можливі значення: nova_poshta, ukrposhta

    • tnID - унікальний ідентифікатор ЕН

    • tnNumber - номер ЕН

    • tnStatusName - текст статусу накладної в оператора

    • tnTrackingUpdateDate - час останньої зміни статусу в оператора

    • estimatedDeliveryDate - передбачувана дата доставки

      • departure

        • sender - масив даних щодо відправника

          • id - унікальний ідентифікатор відправника в базі оператора доставки

          • title - назва відправника

          • contactPerson - масив даних щодо контактної особи (передається тільки для deliveryOperatorType= **nova_poshta)

          • id - унікальний ідентифікатор контактної особи в базі оператора доставки

          • name - ім'я контактної особи

          • phone - телефон контактної особи

        • type - тип відправника (ключ передається тільки для deliveryOperatorType= **ukrposhta) . Можливі значення:

          • COMPANY - Юридична особа

          • PRIVATE_ENTREPRENEUR - ФЛП

          • INDIVIDUAL - Фізична особа

        • phone - телефон відправника (ключ передається тільки для deliveryOperatorType= **ukrposhta)

        • address

          • type - тип адреси відправника. Можливі значення: warehouse

          • geoObject - масив даних про склад відправника

          • id - унікальний ідентифікатор міста відправника в базі оператора доставки

          • name - місто відправника

          • warehouse (передається для type = warehouse)

          • id - ідентифікатор складу відправника в базі оператора доставки

          • name - склад відправника

    • destination

      • recipient - масив даних про одержувача

        • name- ім'я одержувача

        • surname- прізвище одержувача

        • patronymic- по батькові одержувача

        • phone - телефон одержувача

        • address - масив даних про адресу одержувача

        • type - тип адреси відправника. Можливі значення: warehouse / doors

        • geoObject - дані про місто

          • id - унікальний ідентифікатор міста в базі оператора доставки

          • name - місто одержувача

        • warehouse - дані про склад (передається для type = warehouse)

        • id - унікальний ідентифікатор складу одержувача в базі оператора доставки

        • name - склад одержувача

        • street - дані про адресу для кур'єрської доставки (передається для type = doors)

        • id - унікальний ідентифікатор вулиці в базі оператора доставки

        • name - назва вулиці

        • buildingNumber - номер будинку одержувача (передається для type = doors)

        • flatNumber - номер квартири одержувача (передається для type = doors)

    • payment - дані про оплату послуг за доставку

      • type - тип оплати послуг доставки (ключ передається тільки при ****deliveryOperatorType= ****nova_poshta)

      • payer - платник за послуги доставки

      • redelivery - дані про зворотне доставлення

      • cost - сума зворотної доставки

      • payer - платник за зворотну доставку

Примітка: передача інформації про замовлення здійснюється мовою тієї версії сайту, на якій воно було зроблено.

• analytics - масив даних про джерело замовлення (utm-мітки) і покупця

  • utm_source - ідентифікатор джерела трафіку;

  • utm_medium - конкретного маркетингового каналу;

  • utm_campaign - ідентифікатор рекламної кампанії;

  • utm_term - ідентифікатор ключового слова;

  • utm_content - ідентифікатор конткертного оголошення;

  • google_client_id - унікальний ідентифікатор користувача.

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

• customer_details - масив додаткових даних про покупця для b2b-проектів

  • group

    • id - id групи покупців, до якої належить покупець

    • title - назва групи покупців, до якої належить покупець

  • price_level

    • id - id типу ціни для групи покупця

    • title - назва типу ціни для групи покупця

Приклад PUT запиту

Приклад відповіді на запит

Приклад блоку відповіді з новими даними доставки

Приклад адреси відправника для type = doors

Приклад відповіді при доставці Укрпоштою з типом склад-двері

deliveryOperatorType=ukrposhta, departure.address=warehouse и destination.address=doors

Приклад тіла запиту з використанням offset та limit

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

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