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

QUINCE API. Замовлення

Список методів


/order/list

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

/order/add

Створення нового замовлення

/order/update

Внесення змін до замовлення


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


Назва методу: /order/list


Повертає список замовлень. Для навігації використовується номер сторінки (page).
Розмір сторінки фіксований і дорівнює 100 елементам.


Параметри запиту:


filter Тип: object

Доступні поля для фільтрації (Фільтр завжди використовує логіку “AND“):

Id - ідентифікатор замовлення. Необов'язковий параметр

DateFrom - дата, починаючи з якої повертати замовлення. Обов'язковий параметр

DateTo - дата по яку повертати замовлення. Обов'язковий параметр

Company - ідентифікатор компанії, за якою отримуються замовлення. Необов'язковий параметр

page Тип: integer (необов'язковий)

Якщо в запиті не передати, за замовчуванням буде встановлена перша сторінка.


Результат запиту:


Якщо в запиті фільтр відсутній, то повертається список замовлень у порядку зростання Id.


Значення полів замовлень, що повертаються методом:


Id

Ідентифікатор замовлення

Date

Дата замовлення (string)

Number

Номер (string)

NumberOrderSite

Зовнішній номер (string)

Sum

Сума замовлення (decimal)

VatInclude

Суми включають ПДВ (boolean)

SumVat

Сума ПДВ (decimal)

SumWithoutVat

Сума без ПДВ (decimal)

Comment

Коментар (string)

DeliveryAddress

Адреса доставки (string)

DateScheduleShipment

Дата доставки (string)

Fixed

Ознака публікації документа

Partner

Об'єкт з полями "Id" та "Name"

Store

Об'єкт з полями "Id" та "Name"

Status

Об'єкт з полями "Id" та "Name"

Company

Об'єкт з полями "Id" та "Name"

Contract

Об'єкт з полями "Id" та "Name"

PriceType

Об'єкт з полями "Id" та "Name"

DiscountType

Об'єкт з полями "Id" та "Name"

Responsible

Об'єкт з полями "Id" та "PersonName"

Rows

Товарні позиції. Об'єкт з наступними полями:

Id - Ідентифікатор позиції

RowNo - Номер рядка

Product - Ідентифікатор товару

Price - Ціна

Qty - Кількість

Sum - Сума

SumVat - СумаПДВ

PriceWithoutDiscount - Ціна без знижки

PercentDiscount - Відсоток знижки

Kind - Вид. Приймає значення "P" або "S" (товар або послуга)


Приклад:


Запит:


{
"filter": {
"DateFrom": "2022-06-20",
"DateTo": "2022-07-28"
},
"page": 1
}


Результат:


{
"success": true,
"data": [
{
"Id": 8027,
"NumberOrderSite": "2",
"Date": "2022-07-01T00:00:00Z",
"Number": 1,
"DeliveryAddress": "Осіння 105, Дніпро, 15151",
"DateScheduleShipment": null,
"Sum": 3278.90,
"Fixed": false,
"Void": false,
"Partner": {
"Id": 53869,
"Name": "Buyer"
},
"Store": {
"Id": 346,
"Name": "Store_5"
},
"Status": {
"Id": 1173,
"Name": "Новий"
},
"Company": {
"Id": 298,
"Name": "Наше підприємство"
},
"Contract": {
"Id": 54066,
"Name": "Основний контракт (грн)"
},
"PriceType": {
"Id": 335,
"Name": "Ціна продажу"
},
"DiscountType": {},
"Responsible": {
"Id": 898,
"PersonName": "ivan"
},
"Rows": [
{
"Id": 15705,
"RowNo": 4,
"Product": 89274,
"Price": 324.940000,
"Qty": 1.000000,
"Sum": 324.94,
"PriceWithoutDiscount": 324.940000,
"PercentDiscount": 0.00,
"Kind": "P"
},
...
]
},
...
]
}


Створення або оновлення замовлення


Метод створення замовлення: /api/v2/order/add


Метод оновлення замовлення: /api/v2/order/update


Методи додають або оновлюють замовлення. Максимальна кількість замовлень в одному пакеті - 100.


Методи підтримують два режими:


1) Якщо в запиті вказати ознаку "strict" = true, то поля, які представляють собою посилання на довідники (наприклад, товар, партнер та ін), мають передавати ідентифікатори сутностей системи Quincefin. Значення "Store" та "Company" беруться з налаштувань за замовчуванням адміністратора.


Параметри запиту додавання:


array Тип: масив (Обов'язковий)

Кожне замовленння в масиві являє собою об'єкт з переліком полів. Доступні поля:

NumberOrderSite

Номер замовлення зовнішьої системи

Date

Дата замовлення. Фортмат: yyyy-mm-dd

Sum

Загальна сумма

Comment

Коментар

DeliveryAddress

Адреса доставки

DateScheduleShipment

Запланована дата доставки. Фортмат: yyyy-mm-dd

Partner

Ідентифікатор партнера

Contract

Ідентифікатор контракту

Status

Ідентифікатор статусу замовлення

PriceType

Ідентифікатор типу ціни

DiscountType

Ідентифікатор типу скидки

PaymentOption

Ідентифікатор типу варіанту оплати

ShippingOption

Ідентифікатор типу варіанту відвантаження

Responsible

Ідентифікатор користувача

Rows

Товарні позиції. Об'єкт з наступними полями:

Product - Ідентифікатор товару

Price - Ціна

Qty - Кількість

Sum - Сума

PriceWithoutDiscount - Ціна без знижки

PercentDiscount - Відсоток знижки



Результат запиту:


Метод повертає об'єкт з наступними полями:


success

true или false

data

Масив ідентифікаторів створених замовлень

error

Зміст помилки (вказується, якщо success = false)


Приклад запиту додавання ("strict" = true):


{
"strict": true,
"array": [
{

"Comment": "Comment",
"Date": "2022-07-20",
"Sum": 1000,
"Partner": 53869,
"Status": 1397,
"Contract": 54065,
"PriceType": 610,
"Responsible": 898,
"Rows": [
{
"Product": 89272,
"Price": 6.67,
"PriceWithoutDiscount": 6.67,
"Qty": 2,
"Sum": 1.2,
"PercentDiscount": 50,
"RowNo": 1
}
]
}
]
}


Результат:


{
    "success": true,
    "data": [
        {
            "Id": 12617
        }
    ]
}


Приклад запиту оновлення ("strict" = true)
Якщо в масиві Rows вказати Id товарної позиції, то рядок буде оновлений. Якщо не вказати Id, рядок буде доданий до замовлення.


{
    "strict": true,
    "array": [
        {
            "Id": 225,
            "Comment": "Comment_2",
            "Partner": 111,
            "Contract": 151,
            "Responsible": 100,
            "Rows": [
                {
                    "Id": 244,
                    "RowNo": 2
                }
            ]
        }
    ]
}


2) Якщо "strict" = false, то замість Id потрібно передавати поля (назва, артикул, тощо) за якими буде відбуватись пошук елементу довідника. В системі Quincefin знайдений за назвою елемент довідника буде прив'язаний до замовлення. В іншому випадку автоматично створений. Значення "Store" та "Company" беруться з налаштувань за замовчуванням адміністратора.


Особливості режиму:


  • Поле "NumberOrderSite" є обов'язковим. По ньому виконується пошук замовлення при оновленні документа, тому необхідно забезпечити унікальність значення цього поля.
  • При оновленні поля "Partner" необхідно передавати також "Contract". Та навпаки - при оновленні "Contract" необхідно передавати "Partner".


  • Поле "Name" об'єкта "Partner" використовується для пошуку існуючого партнера в довіднику партнерів. Якщо потрібно виконувати пошук за поштою або телефоном, в тілі запиту потрібно вказати ключ "search-partner-by" і одне зі значень {Name | Email | Phone}. Якщо ключ "search-partner-by" не вказаний, пошук буде виконуватись за назвою.
  • Оновлення товарних позицій не підтримується (для цього можна використовувати режим strict = true)
  • Відповідальним за замовлення автоматично призначається головний користувач - адміністратор.
  • Пошук товару в системі відбувається спочатку по артикулу, якщо присутній, потім за назвою.


Параметри запиту додавання:


array Тип: масив (Обов'язковий)

Кожне замовленння в масиві являє собою об'єкт з переліком полів. Доступні поля:

**NumberOrderSite**\*

Номер замовлення зовнішьої системи

**Sum**\*

Загальна сумма

**Date**\*

Дата замовлення. Фортмат: yyyy-mm-dd

Comment

Коментар

DeliveryAddress

Адреса доставки

DateScheduleShipment

Запланована дата доставки. Фортмат: yyyy-mm-dd

**Partner**\*

Об'єкт з наступними полями:

Name**\* - Назва партнера. **Пошук в системі за назвою.

Phone

Email

**Status**\*

Об'єкт з наступними полями:

Name**\* - Назва статусу. **Пошук в системі за назвою.

**Contract**\*

Об'єкт з наступними полями:

Name**\* - Назва контракту. **Пошук за назвою.

**Currency**\* - Код валюти

**PriceType**\*

Об'єкт з наступними полями:

Name**\* - Назва типу ціни. **Пошук за назвою.

**Currency**\* - Код валюти

DiscountType

Об'єкт з наступними полями:

Name**\* - Назва типу знижки. **Пошук за назвою.

Percent \* \- відсоток

**Rows**\*

Товарні позиції. Об'єкт з наступними полями:

**Product**\* \- об'єкт з наступними полями:

\- Name**\* - Назва товару. **Пошук за назвою.

\- Article \- Артикул товару. Найвищий приорітет пошуку.

\- **Unit**\* - Одиниця виміру

\- Kind**\* - Вид. Приймає значення "P" або "S**" (товар або послуга)

**Price**\* - Ціна

**Qty**\* - Кількість

**Sum**\* - Сума

**PriceWithoutDiscount**\* - Ціна без знижки

**PercentDiscount**\* - Відсоток знижки


\* \- обо'язкове поле


Результат запиту:


Метод повертає об'єкт з наступними полями:


success

true или false

data

Масив об'єктів, кожен з яких зберігає ідентифікатор створеного замовлення та номер замовлення зовнішьої системи, який передавався в запиті

error

Зміст помилки (вказується, якщо success = false)


Приклад запиту додавання ("strict" = false):


{
"strict": false,
"search-partner-by": "Email",
"array": [
{
"NumberOrderSite": "api_order_5",
"Comment": "comment_134",
"Date": "2022-07-20",
"DeliveryAddress": "м. Дніпро, вул. Осіння 100",
"DateScheduleShipment": "2022-07-25",
"Sum": 6.66,
"Partner": {
"Name": "Partner_1",
"Phone": "0677255253",
"Email": "vanjuteam@gmail.com"
},
"Contract": {
"Name": "Contract_12",
"Currency": "USD"
},
"Status": {
"Name": "Виготовлено"
},
"PriceType": {
"Name": "Цена продажи",
"Currency": "UAH"
},
"DiscountType": {
"Name": "Discount_1",
"Percent": 20.2
},
"Rows": [
{
"Product": {
"Name": "product_2",
"Article": "article_2",
"Unit": "шт",
"Kind": "P"
},
"Price": 6.67,
"PriceWithoutDiscount": 6.67,
"Qty": 2,
"Sum": 1.2,
"PercentDiscount": 50,
"RowNo": 1
},
...
]
},
...
]
}


Результат:


{
"success": true,
"data": [
{
"Id": 12641,
"NumberOrderSite": "api_order_5"
},
...
]
}


Приклад запиту оновлення ("strict" = false):


{
    "strict": false,
    "array": [
        {
            "NumberOrderSite": "api_order_5",
            "Comment": "Сomment_12345",
            "DeliveryAddress": "м. Дніпро, вул. Осіння 101",
            "DateScheduleShipment": "2022-07-28",
            "Status": {
                "Name": "Виготовлено"
            },
...
        }
    ]
}


Результат:


{
    "success": true,
    "data": [
        {
            "Id": 12641,
            "NumberOrderSite": "api_order_5"
        },
...
    ]
}

Оновлено: 03/07/2024