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

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

Метод	Опис
`/api/v2/document/nova_poshta/list`	Отримання списку накладних Нової Пошти

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

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

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

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

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

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

Поле	Тип	Опис
`filter`	object	Фільтр накладних. Поля фільтра працюють з логікою `AND`.
`filter.Id`	integer	Ідентифікатор накладної Нової Пошти в QUINCEFIN.
`filter.DateFrom`	string	Дата, починаючи з якої повертати накладні. Формат: `yyyy-mm-dd` або `yyyy-mm-dd HH:mm:ss`.
`filter.DateTo`	string	Дата, до якої повертати накладні. Формат: `yyyy-mm-dd` або `yyyy-mm-dd HH:mm:ss`.
`filter.Company`	integer	Ідентифікатор організації.
`filter.Partner`	integer	Ідентифікатор партнера-отримувача.
`filter.ParentDocId`	integer	Ідентифікатор документа-підстави. Також підтримуються alias-поля `ParentDoc` і `ParentDocument`.
`filter.NumberNP`	string	Номер експрес-накладної Нової Пошти. Пробіли в номері можна не передавати.
`filter.ENId`	string	Ідентифікатор експрес-накладної у Новій Пошті, якщо він збережений у QUINCEFIN.
`filter.Status`	integer або array	Код статусу Нової Пошти або масив кодів. Alias: `StatusCode`.
`filter.Archive`	boolean	Якщо `true`, повертає скасовані/архівні накладні; якщо не передати, повертаються активні накладні.
`filter.MobileApp`	boolean	Якщо `true`, API використовує збільшений ліміт вибірки.
`page`	integer	Номер сторінки.
`limit`	integer	Розмір сторінки, якщо потрібно перевизначити стандартний ліміт API.

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

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

Поле	Опис
`Id`	Ідентифікатор накладної Нової Пошти в QUINCEFIN.
`Date`	Дата накладної в часовому поясі користувача API-ключа.
`Number`	Внутрішній номер документа накладної в QUINCEFIN.
`NumberNP`	Номер експрес-накладної Нової Пошти.
`ENId`	Ідентифікатор експрес-накладної у Новій Пошті, якщо він доступний.
`Status`	Текст поточного статусу Нової Пошти.
`StatusCode`	Код поточного статусу Нової Пошти.
`StatusAlias`	Коротка назва статусу для компактного відображення.
`StatusColor`	Службова назва кольору статусу в QUINCEFIN.
`RecipientName`	Ім’я або назва отримувача.
`RecipientPhone`	Телефон отримувача.
`Partner`	Партнер-отримувач.
`Company`	Організація.
`Responsible`	Відповідальний користувач.
`ParentDoc`	Документ-підстава: `Id`, `Type`, `Name`, `Number`, `Date`, `DisplayName`.
`Fixed`	Ознака публікації документа накладної.
`Void`	Ознака архівності або скасування документа накладної.
`Comment`	Коментар до накладної.

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

{
  "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, якщо інтеграції потрібно:

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

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