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

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

Увага: ми оновили Отримання списку замовлень - додано новий блок delivery_data, у якому передаватимуться всі дані про доставку.

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

Новий блок даних про джерело замовлення analytics

Новий блок customer_details в Отримання списку замовлень для b2b проєктів

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

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 запиту

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "from": "01.04.2021",
    "to": "03.04.2021",
    "additionalData": true
}

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

{
  "status": "OK",
  "response": {
    "orders": [
      {
        "order_id": 7,
        "user": 6,
        "delivery_name": "John Doe",
        "delivery_email": "john.doe@gmail.com",
        "delivery_phone": "+38 (055) 555-55-55",
        "delivery_city": "Киев",
        "delivery_address": "Отделение №13 (до 30 кг на одно место): ул. Оранжерейная, 3 (метро Дорогожичи)",
        "delivery_type": {
          "id": 3,
          "title": "Новой почтой"
        },
        "delivery_price": -1,
        "comment": "Комментарий к заказу",
        "payment_type": {
          "id": 13,
          "title": "Наличными"
        },
        "payment_price": 0,
        "payed": 0,
        "total_default": 3413,
        "total_sum": 3413,
        "total_quantity": 2,
        "discount_percent": 0,
        "discount_value": 0,
        "coupon_code": "",
        "coupon_percent": 0,
        "coupon_discount_value": 0,
        "coupon_type": 0,
        "stat_status": 2,
        "stat_created": "2021-04-09 12:09:01",
        "currency": "UAH",
        "order_without_callback": false,
        "products": [
          {
            "title": "Товар 1",
            "article": "10000001",
            "price": 1001,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "gift_parent",
            "storage_id": 41,
            "parent_storage_id": null,
            "total_price": 1001
          },
          {
            "title": "Товар 13",
            "article": "10000013",
            "price": 0,
            "quantity": 1,
            "discount_marker": "DISCOUNT_NONE",
            "type": "gift",
            "storage_id": 42,
            "parent_storage_id": 41,
            "total_price": 0
          },
          {
            "title": "Тестовый комплект",
            "article": "test_set_123",
            "price": 2412,
            "quantity": 1,
            "discount_marker": "PRODUCTS_SET",
            "type": "set_main",
            "storage_id": 43,
            "parent_storage_id": null,
            "total_price": 2412
          },
          {
            "title": "Товар 1",
            "article": "10000001",
            "price": 1001,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 44,
            "parent_storage_id": 43,
            "total_price": 1001
          },
          {
            "title": "Товар 5",
            "article": "10000005",
            "price": 1005,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 45,
            "parent_storage_id": 43,
            "total_price": 1005
          },
          {
            "title": "Товар 9",
            "article": "10000009",
            "price": 1009,
            "quantity": 1,
            "discount_marker": "PRICE_OLD",
            "type": "set_item",
            "storage_id": 46,
            "parent_storage_id": 43,
            "total_price": 1009
          }
        ],
        "additional_data": {
          "np_ref": "8d8ecd29-9913-11eb-8513-b88303659df5",
          "np_number": 12345678912345,
          "sender_warehouse_ref": "0d545f63-e1c2-11e3-8c4a-0050568002cf",
          "recipient_warehouse_ref": "39931b8c-e1c2-11e3-8c4a-0050568002cf"
        }
         "analytics": {
          "utm_source": "google",
          "utm_medium": "google_cpc",
          "utm_campaign": "brand_1",
          "utm_term": (none),
          "utm_content": "banner_3",
          "google_client_id": "GA1.3.391577864.1662575866"
        }
      }
    ]
  }
}

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

"delivery_data": 
{
    "deliveryOperatorType": "nova_poshta",
    "tnId": "a3a24ec9-632e-11ec-8513-b88303659df5",
    "tnNumber": "20450492106170",
    "tnStatusName": "Создан",
    "tnTrackingUpdateDate": null,
    "estimatedDeliveryDate": "2021-12-24",
    "departure": {
        "sender": {
            "id": "60cd854f-580c-11eb-8513-b88303659df5",
            "title": "Приватна особа",
            "contactPerson": {
                "id": "9bc4f232-580c-11eb-8513-b88303659df5",
                "name": "Александр Анатолиевич Коваль (380915554433)",
                "phone": "380915554433"
            }
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "db5c88e0-391c-11dd-90d9-001a92567626",
                "name": "Харьков"
            },
            "warehouse": {
                "id": "169227f4-e1c2-11e3-8c4a-0050568002cf",
                "name": "Отделение №1: ул. Полевая, 67"
            }
        }
    },
    "destination": {
        "recipient": {
            "name": "Наталья",
            "surname": "Ткаченко",
            "patronymic": null,
            "phone": "380914443322"
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "f706237a-4078-11de-b509-001d92f78698",
                "name": "Яворов"
            },
            "warehouse": {
                "id": "16922828-e1c2-11e3-8c4a-0050568002cf",
                "name": "Отделение №1: ул. А. Маковея, 62"
            }
        }
    },
    "payment": {
        "type": "Cash",
        "payer": "Sender"
    },
    "redelivery": {
        "cost": "54000",
        "payer": "Sender"
    }
}

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

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

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

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

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

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

Портал підтримки

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

Related pages