QUINCE API. Накладні Нової Пошти

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

Передавання даних для майбутньої ТТН

Щоб місто, відділення або поштомат і післяплата підставлялися у форму ТТН, передайте блок NovaPoshta через /api/v2/order/add або /api/v2/order/update. Блок працює однаково в режимах strict: true і strict: false та потребує серверної версії QUINCEFIN з його підтримкою.

1. Разом із замовленням передайте CityRef, WarehouseRef і CODAmount. Суму післяплати розраховує інтеграція; для повністю оплаченого замовлення передайте 0.
2. Перевірте збережений блок NovaPoshta через /api/v2/order/list.
3. Менеджер створює продаж із замовлення, а потім ТТН із продажу у звичайній формі QUINCEFIN. Також можна створити ТТН безпосередньо із замовлення.
4. Для однозначно визначеного замовлення форма підставляє його адресу доставки й режим післяплати. Відділення та поштомат отримують відповідний тип доставки. Менеджер перевіряє отримувача, профіль відправника, параметри пакування й суму, після чого завершує оформлення та реєструє відправлення.

MoneyTransfer відповідає полю «Грошовий переказ», PaymentControl — «Контроль оплати». Для контролю оплати потрібні профіль відправника-організації та відповідний договір із NovaPay; форма перевіряє сумісність профілю. CODPayer визначає платника послуги грошового переказу, а платник доставки задається окремо у формі. Оголошена вартість відправлення не підміняється сумою післяплати.

Для часткового продажу або повторного відправлення система не підставляє повну додатну суму післяплати замовлення ще раз: показує попередження й залишає суму для ручного уточнення. Якщо замовлення визначене однозначно, адресу можна заповнити з нього. Менеджер вводить суму саме цього відправлення або вимикає післяплату; явно переданий нуль залишається нулем.

Якщо продаж об’єднує кілька замовлень і містить збережені дані NovaPoshta, форма попереджає про неоднозначність та не вибирає дані одного з них. Адресу й післяплату треба перевірити вручну. Перевірка повторних відправлень враховує збережені документи на момент відкриття форми; одночасно відкриті незбережені ТТН не резервують суму післяплати.

Дані замовлення мають пріоритет над адресою партнера. Якщо його відділення або поштомат більше не знаходиться в довіднику, форма повідомить про це та вимагатиме уточнити адресу. Якщо блок NovaPoshta взагалі не зберігали або очистили через null, діє попередній порядок заповнення форми.

Збереження NovaPoshta не створює чернетку ТТН і не реєструє відправлення у Новій Пошті. Оновлення замовлення також не перезаписує вже збережену накладну при її відкритті. Метод /api/v2/document/nova_poshta/list залишається методом читання оформлених у QUINCEFIN накладних.

Налаштування профілю й роботу менеджера з формою описано в інструкції з інтеграції з Новою Поштою.

Отримання списку накладних Нової Пошти

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

Повертає накладні Нової Пошти, доступні користувачу API-ключа. Метод призначений тільки для читання: через нього не можна створити, змінити, провести, скасувати або видалити накладну.

Для навігації використовується номер сторінки page; за замовчуванням повертається перша сторінка. Розмір сторінки береться з налаштувань API, зазвичай це 100 елементів; за потреби можна передати limit.

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

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

Якщо DateFrom і DateTo не передані та немає точного фільтра Id, NumberNP, ENId або ParentDocId, API повертає накладні за поточний день. Якщо передати тільки одну з дат, API поверне помилку DateFrom and DateTo are required.

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

Приклад пошуку за номером ТТН

{
  "filter": {
    "NumberNP": "20450000000001"
  },
  "page": 1
}

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

{
  "filter": {
    "DateFrom": "2026-03-01",
    "DateTo": "2026-03-31",
    "Status": [5]
  },
  "page": 1,
  "limit": 100
}

Приклад відповіді

{
  "success": true,
  "data": [
    {
      "Id": 782411,
      "Date": "2026-03-14T11:18:00",
      "Number": "НП-000145",
      "NumberNP": "20450000000001",
      "ENId": "8f2a4c45-7b56-11ee-a60f-48df37b921da",
      "Status": "Відправлення прямує до міста отримувача",
      "StatusCode": 5,
      "StatusAlias": "В дорозі",
      "StatusColor": "info",
      "RecipientName": "Іван Петренко",
      "RecipientPhone": "+380671112233",
      "Partner": {
        "Id": 53869,
        "Name": "Іван Петренко"
      },
      "Company": {
        "Id": 112,
        "Name": "Наше підприємство"
      },
      "Responsible": {
        "Id": 4701,
        "PersonName": "Менеджер"
      },
      "ParentDoc": {
        "Id": 494872,
        "Type": "OUTGOING_INVOICE",
        "Name": "Продаж",
        "Number": "РН-000145",
        "Date": "2026-03-14T11:20:00",
        "DisplayName": "Продаж №РН-000145 від 14.03.2026"
      },
      "Fixed": true,
      "Void": false,
      "Comment": "Післяплата"
    }
  ]
}

Коли використовувати цей метод

Використовуйте /api/v2/document/nova_poshta/list, якщо інтеграції потрібно:

1. Знайти накладну за номером Нової Пошти.
2. Отримати окремий список відправлень за період.
3. Показати поточний статус доставки.
4. Звірити, до якого документа продажу прив’язана ТТН.

Якщо потрібен список продажів разом із ТТН, використовуйте /api/v2/document/outgoing_invoice/list. У ньому накладні Нової Пошти повертаються масивом NovaPoshtaNotes у кожному документі продажу.