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

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

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

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

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

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

Якщо DateFrom і DateTo не передані та немає фільтра Id або DateModifiedFrom, API повертає документи за поточний день. Якщо передати тільки одну з дат DateFrom/DateTo без DateModifiedFrom, API поверне помилку DateFrom and DateTo are required. Поле Status має бути масивом.

Основні поля відповіді

Поля рядків Rows

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

{
  "filter": {
    "DateFrom": "2026-03-01",
    "DateTo": "2026-03-11",
    "Status": [111, 192]
  },
  "page": 1
}

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

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

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

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

API підтримує два режими:

Department, Segment і Project є винятком із загального правила для strict: false: в обох режимах їх визначають тільки за Id. Блок NovaPoshta також має однаковий формат в обох режимах: він приймає Ref Нової Пошти, а не Id довідників QUINCEFIN.

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

Для дат у створенні та оновленні використовуйте формат yyyy-mm-dd або yyyy-mm-dd HH:mm:ss. Якщо передати тільки дату без часу, API додає поточний час сервера.

Параметри для strict: true

Для /api/v2/order/add у strict: true обов’язкові Date, Responsible, Partner, Store, Status, Contract і непорожній масив Rows. Для /api/v2/order/update обов’язковий Id замовлення, а Rows можна не передавати. Якщо під час оновлення у Rows передати Id рядка, рядок буде оновлений. Якщо Id не передати, рядок буде доданий до замовлення.

Параметри рядків для strict: true

Якщо передати PriceWithoutDiscount, треба також передати PercentDiscount, і навпаки. Якщо ці поля не передані, PriceWithoutDiscount дорівнює Price, а PercentDiscount дорівнює 0.

Параметри для strict: false

Для /api/v2/order/add у strict: false обов’язкові NumberOrderSite, Date, Partner.Name, Store.Name, Status.Name, Contract.Name, Contract.Currency і непорожній масив Rows. Для /api/v2/order/update обов’язковий NumberOrderSite, а інші поля можна передавати частково. Якщо під час оновлення передати Partner, треба також передати Contract, і навпаки.

Пошук товару виконується спочатку за Article, якщо він переданий, потім за Name. InformationSource, PaymentOption і ShippingOption у strict: false передаються як об’єкти з полем Name; значення мають існувати у відповідних довідниках.

Доставка Новою Поштою

Передавайте NovaPoshta на рівні кожного замовлення в array через /api/v2/order/add або /api/v2/order/update. Дані зберігаються за конкретним замовленням і використовуються, коли менеджер створює ТТН із нього або пов’язаного продажу. Адреса партнера та вже збережені ТТН при цьому не змінюються.

Для використання блоку потрібна серверна версія QUINCEFIN з його підтримкою. Помилка Unknown order field: NovaPoshta означає, що сервер ще не підтримує цей контракт і потребує оновлення.

Інтеграція сама розраховує CODAmount: сума замовлення мінус передоплата, але не менше нуля. Наприклад, для замовлення на 1500 грн із передоплатою 250 грн передайте 1250, а для повністю оплаченого — 0. QUINCEFIN використовує передану суму: цей блок не створює платіжних документів, не перераховує взаєморозрахунки та не змінює оголошену вартість відправлення.

NovaPoshta замінюється цілком. Коли передаєте об’єкт, завжди включайте CityRef, WarehouseRef і CODAmount, навіть якщо змінюєте лише суму. Пропущені CODMode і CODPayer отримають значення за замовчуванням; пропущені назви стануть null. Пробіли на початку й у кінці назв прибираються, порожні назви зберігаються як null.

Ref міста й точки доставки перевіряються за синхронізованими довідниками QUINCEFIN. Відділення або поштомат має належати вказаному місту, а його населений пункт — бути в довіднику. Назви не замінюють Ref і не обходять перевірку. Якщо правильна точка ще відсутня, оновіть довідники Нової Пошти в QUINCEFIN та повторіть запит. Для форми ТТН система визначає SettlementRef і дані відділення за переданими Ref.

Невідомі вкладені поля, неповний об’єкт, некоректні UUID, від’ємна або надто точна сума, непідтримувані режим чи платник та невідповідність міста й відділення повертають success: false з описом помилки. Дані доставки й замовлення зберігаються в одній транзакції.

Під час order/update замовлення має існувати в поточному акаунті, бути активним і неопублікованим (Fixed: false). У strict: true використовуйте його Id і передавайте кожен Id лише один раз у пакеті оновлення. У strict: false значення NumberOrderSite має однозначно визначати замовлення; повторення такого номера в запиті з даними доставки або кілька збережених замовлень із цим номером спричиняють помилку. Для уточнення конкретного замовлення використовуйте strict: true з його Id.

order/list повертає NovaPoshta з полями з наведеної таблиці або null, якщо власні дані доставки не збережені. Ref повертаються малими літерами, сума 0 зберігається як нуль. Після add або update можна перевірити результат через order/list із filter.Id.

Приклад оновлення адреси й післяплати

UUID у прикладах умовні. Перед виконанням замініть їх на реальні Ref із синхронізованих довідників Нової Пошти, а Id — на Id свого замовлення.

{
  "strict": true,
  "array": [
    {
      "Id": 12345,
      "NovaPoshta": {
        "CityRef": "11111111-1111-4111-8111-111111111111",
        "WarehouseRef": "22222222-2222-4222-8222-222222222222",
        "CityName": "Київ",
        "WarehouseName": "Відділення №1",
        "CODAmount": 1250,
        "CODMode": "MoneyTransfer",
        "CODPayer": "Recipient"
      }
    }
  ]
}

Такий самий блок можна додати до замовлення в order/add разом зі звичайними обов’язковими полями та рядками.

Приклад повністю оплаченого замовлення у strict: false

Післяплату вимикає явний нуль; адреса залишається заданою:

{
  "strict": false,
  "array": [
    {
      "NumberOrderSite": "SHOP-10045",
      "NovaPoshta": {
        "CityRef": "11111111-1111-4111-8111-111111111111",
        "WarehouseRef": "22222222-2222-4222-8222-222222222222",
        "CODAmount": 0
      }
    }
  ]
}

Щоб очистити власні дані доставки, передайте в order/update:

{
  "strict": true,
  "array": [
    {
      "Id": 12345,
      "NovaPoshta": null
    }
  ]
}

Подальші дії менеджера й обмеження для часткових або повторних відправлень описані на сторінці накладних Нової Пошти.

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

Department, Segment і Project передаються на рівні замовлення, а не в Rows. В обох режимах використовуйте додатний числовий Id або об’єкт з полем Id; об’єкт тільки з Name та поля DepartmentId, SegmentId, ProjectId не підтримуються. Id має належати активному елементу довідника поточного акаунта, а сегмент — бути доступним користувачу API. Id підрозділів можна отримати через /api/v2/department/list; для сегментів і проєктів використовуйте /api/v2/segment/list і /api/v2/project/list.

При створенні замовлення, якщо одне з трьох полів не передати, API підставляє чинне й доступне значення з налаштувань користувача API за замовчуванням. Явний null залишає поле порожнім. При оновленні відсутнє поле зберігає попереднє значення, Id замінює його, а явний null очищає. Ці правила однакові для strict: true і strict: false.

Невідоме поле на рівні замовлення або некоректний Id аналітики повертає success: false з описом помилки. order/update не змінює опубліковане замовлення (Fixed: true) і повертає помилку. Оновлення API не заповнює аналітику в замовленнях, створених раніше.

Основні вкладені поля для strict: false

Формат відповіді

Приклад часткового оновлення аналітики

Для strict: true замовлення визначається за внутрішнім Id. Відсутній Segment залишиться без змін, а Project: null очистить проєкт:

{
  "strict": true,
  "array": [
    {
      "Id": 12345,
      "Department": { "Id": 12 },
      "Project": null
    }
  ]
}

Для strict: false замість Id використовується NumberOrderSite:

{
  "strict": false,
  "array": [
    {
      "NumberOrderSite": "api_order_5",
      "Department": 12,
      "Segment": { "Id": 34 },
      "Project": 56
    }
  ]
}

Приклад створення у strict: true

{
  "strict": true,
  "array": [
    {
      "Date": "2026-03-11",
      "Sum": 1000,
      "Partner": 53869,
      "Responsible": 101,
      "Status": 1397,
      "Contract": 54065,
      "Store": 201,
      "PriceType": 610,
      "Company": 112,
      "Department": 12,
      "Segment": 34,
      "Project": 56,
      "Rows": [
        {
          "Product": 89272,
          "Price": 500,
          "Qty": 2,
          "Sum": 1000,
          "RowNo": 1
        }
      ]
    }
  ]
}

Приклад створення у strict: false

{
  "strict": false,
  "search-partner-by": "Email",
  "array": [
    {
      "NumberOrderSite": "api_order_5",
      "Date": "2026-03-11",
      "Sum": 1000,
      "Partner": {
        "Name": "Partner 1",
        "Email": "partner@example.com"
      },
      "Contract": {
        "Name": "Основний контракт",
        "Currency": "UAH"
      },
      "Status": {
        "Name": "Новий"
      },
      "Store": {
        "Name": "Основний склад"
      },
      "PriceType": {
        "Name": "Ціна продажу",
        "Currency": "UAH"
      },
      "Department": { "Id": 12 },
      "Segment": 34,
      "Project": { "Id": 56 },
      "Rows": [
        {
          "Product": {
            "Name": "Товар 1",
            "Article": "SKU-1",
            "Unit": "шт",
            "Kind": "P"
          },
          "Price": 500,
          "Qty": 2,
          "Sum": 1000,
          "PriceWithoutDiscount": 500,
          "PercentDiscount": 0,
          "RowNo": 1
        }
      ]
    }
  ]
}