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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 — плательщик за обратную доставку

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

Новый блок в ответе analytics — массив данных о источнике заказа и client_id

analytics — массив данных источнике заказа (utm-метки) и покупателе
- utm_source — идентификатор источника трафик;
- utm_medium — конкретного маркетингового канала;
- utm_campaign — идентификатор рекламной кампании;
- utm_term — идентификатор ключевого слова;
- utm_content — идентификатор конткертного объявления;
- google_client_id — уникальный идентификатор пользователя.

Дополнительные данные в Получении списка заказов — блок customer_details - только для b2b проектов

В Получение списка заказов добавляем дополнительные данные о покупателе - группу, к которой он относится и тип цены, назначенной этой группе.

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

"address": 
{
    "type:" "doors",
    "geoObject": {
          "id": "f706237a-4078-11de-b509-001d92f78698",
          "name": "Яворов"
      },
     "street" : {
          "id"   : "16922828-e1c2-11e3-8c4a-0050568002cf", 
          "name" : "ул. А. Маковея, 62" 
      },
      "houseNumber"   : "22/12", 
      "flatNumber"    : "16Б"
}

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

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

{
    "deliveryOperatorType": "ukrposhta",
    "tnId": "d07d4f9a-444a-4da9-968f-349c50e028c0",
    "tnNumber": "0000003391590",
    "tnStatusName": "Не зарегистрирован в отделении",
    "tnTrackingUpdateDate": null,
    "estimatedDeliveryDate": "2022-02-15",
    "departure": {
        "sender": {
            "type": "INDIVIDUAL",
            "id": "a4018a6e-8e86-40c4-8637-3eb71669d8ae",
            "title": "Петров Иван Генадиевич",
            "phone": "380636511066"
        },
        "address": {
            "type": "warehouse",
            "geoObject": {
                "id": "10754",
                "name": "Львов"
            },
            "warehouse": {
                "id": "79000",
                "name": "79000 Львів, вул. Словацького, 1"
            }
        }
    },
    "destination": {
        "recipient": {
            "name": "Тамара",
            "surname": "Перепеличко",
            "patronymic": "Анатольевна",
            "phone": "380636511023"
        },
        "address": {
            "type": "doors",
            "geoObject": {
                "id": "10754",
                "name": "Львов"
            },
            "street": {
                "id": "490046",
                "name": "вул. Банаха"
            },
            "buildingNumber": "2",
            "flatNumber": "3"
        }
    },
    "payment": {
        "payer": "Recipient"
    },
    "redelivery": {
        "cost": "43998",
        "payer": "Recipient"
    }
}

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

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "offset": 0,
    "limit": 2,
    "additionalData": true
}

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

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "ids": [
        5, 6
    ],
    "additionalData": true
}

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

{
    "token": "c5bc0cd25647e701bc6427f3629b27b4",
    "status": [
        2
    ],
    "additionalData": true
}

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

0 Comments