QUINCE API. Роздріб: чеки та повернення

Методи повертають документи роздрібного продажу з товарними рядками для обліку та аналітики. Потрібна серверна версія QUINCEFIN із підтримкою цих методів. Саме оновлення документації не означає, що сервер вашого середовища вже оновлено.

Методи та авторизація

Метод	Документи
`POST /api/v2/document/receipt/list`	Чеки, `Type = RECEIPT`
`POST /api/v2/document/purchase_return/list`	Чеки повернення, `Type = PURCHASE_RETURN`

Обидва методи працюють лише на читання. Створення, редагування, проведення, скасування та фіскалізація через них не виконуються.

Використовуйте налаштування підключення QUINCE API та заголовок Content-Type: application/json. Для API-ключа заголовок авторизації має вигляд Authorization: ApiKey <ваш-ключ>. Компанія облікового запису та користувач визначаються авторизацією: передавати TenantId, UserId або змінювати тип документа в тілі запиту не потрібно.

Застосовуються доступність типу документа за тарифом, право перегляду та доступ до конкретних документів. Недоступні чеки не входять ні у відповідь, ні в кількість результатів. Окреме право редагування для читання не потрібне.

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

Поле	Тип	Поведінка
`filter.Id`	integer або string	Один документ. Без дат доступний незалежно від його дати.
`filter.DateFrom`	string	Початок періоду включно: `yyyy-mm-dd` або `yyyy-mm-dd HH:mm:ss`.
`filter.DateTo`	string	Кінець періоду включно у тому самому форматі; дата без часу включає весь день.
`filter.Company`	integer або string	Організація.
`filter.Pos`	integer або string	Точка продажу.
`filter.Fixed`	boolean	`true` — проведені, `false` — непроведені; без поля — обидва стани.
`filter.Archive`	boolean	`false` або відсутнє поле — неархівні; `true` — лише архівні.
`page`	integer	Номер сторінки від 1; типово 1.
`limit`	integer	Кількість документів на сторінці від 1 до 1000; типово 100.

Усі фільтри поєднуються через AND. Ідентифікатори додатні; великі bigint передавайте десятковим рядком, щоб JavaScript не округлював значення. page та limit передавайте числами, логічні поля — true або false.

Дати інтерпретуються в часовому поясі користувача API. Якщо немає ані Id, ані дат, повертаються чеки за поточний день цього користувача. Дати потрібно передавати парою; можна поєднати дату без часу з датою і часом. Точність часу — одна секунда, кінцева секунда включається повністю. Допустимі календарні дати — від 1753 до 9998 року. Невалідний або зворотний діапазон повертає помилку.

Для історичної аналітики передавайте період явно. Налаштування касового екрана «показувати лише сьогодні» не замінює період цього API; права доступу залишаються чинними.

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

{
  "filter": {
    "DateFrom": "2026-10-01",
    "DateTo": "2026-10-31",
    "Fixed": true,
    "Archive": false
  },
  "page": 1,
  "limit": 100
}

Надішліть запит до /api/v2/document/receipt/list. Для повернень використайте той самий фільтр із /api/v2/document/purchase_return/list.

Один чек із рядками

{ "filter": { "Id": "123456" } }

Окремий метод завантаження не потрібний: list із фільтром Id повертає один доступний документ із Rows. Для архівного документа додайте "Archive": true.

Відповідь

Нижче скорочений приклад із вигаданими даними; решта доступних полів описана в таблицях.

{
  "success": true,
  "data": [{
    "Id": 123456,
    "Type": "RECEIPT",
    "Number": 42,
    "Date": "2026-10-15T12:30:00",
    "Sum": 100.5,
    "SumCash": 40.5,
    "SumCard": 60,
    "Fixed": true,
    "Void": false,
    "Rows": [{
      "Id": 654321,
      "RowNo": 1,
      "Product": 1001,
      "ProductName": "Демонстраційний товар",
      "Qty": 2,
      "Price": 50.25,
      "Sum": 100.5,
      "PriceWithoutDiscount": 55,
      "PercentDiscount": 8.636
    }]
  }],
  "paging": { "page": 1, "size": 100, "totalItems": 1, "totalPages": 1 }
}

Поля документа

Поля	Значення
`Id`, `Type`, `Number`, `Date`, `DateModified`	Ідентифікатор, тип, номер, дата та час останньої зміни. Дати — у часовому поясі користувача.
`Sum`, `SumVat`, `SumWithoutVat`, `VatInclude`	Збережена сума документа, ПДВ, сума без ПДВ та ознака включення ПДВ.
`SumWithoutDiscount`	Збережена сума до знижки.
`SumCash`, `SumCard`	Збережені оплати готівкою та карткою. Вони не є сумами після вирахування комісії еквайрингу.
`Company`, `Pos`, `Store`, `Partner`	Організація, точка продажу, склад і партнер: об’єкти з `Id` та `Name`.
`Currency`	Валюта документа: `Id`, `Code`; незаповнені реквізити можуть бути `null`.
`CashAccount`, `Terminal`	Каса та термінал: `Id`, `Name`.
`Status`	Користувацький статус: `Id`, `Name`. Проведення визначається окремо полем `Fixed`.
`Fixed`, `Void`	Проведення та архівність.
`Fiscalized`, `ReceiptLink`	Збережена ознака фіскалізації та посилання на чек, якщо воно заповнене.
`Responsible`, `Comment`	ID відповідального та коментар.
`ParentDoc`	Доступний батьківський документ: `Id`, `Type`, `Number`. Для пов’язаного повернення це вихідний чек. Якщо зв’язку або права перегляду немає, реквізити порожні.
`Rows`	Масив товарних і сервісних рядків цього документа.

Поля рядка

Поля	Значення
`Id`, `RowNo`	ID та номер рядка.
`Product`, `ProductName`, `Article`, `Kind`, `Unit`	ID позиції, назва, артикул, тип позиції та ID одиниці виміру.
`Qty`, `Price`, `Sum`, `SumVat`	Збережені кількість, ціна, сума та ПДВ рядка.
`PriceWithoutDiscount`, `PercentDiscount`	Ціна до знижки та відсоток знижки.
`Store`	Склад рядка: `Id`, `Name`, якщо заповнений.

Незаповнені числові суми повертаються як 0. API віддає збережені значення, не перераховує проведення чи собівартість. Для чистих продажів враховуйте чеки повернення окремо: їхні суми та кількості не змінюють знак автоматично. Оплати та сума документа можуть відрізнятися, зокрема через бонусні розрахунки; не підміняйте Sum виразом SumCash + SumCard.

Пагінація та порожній результат

Документи впорядковані за Id за зростанням, рядки — за номером рядка та Id. Збільшуйте page до paging.totalPages, зберігаючи фільтри й limit. Кількість рахується лише за доступними документами. Якщо документи паралельно змінюються, повторна вибірка може мати іншу кількість: набір сторінок не є незмінним знімком.

Коли нічого не знайдено, відповідь містить success: true, data: [], totalItems: 0 і totalPages: 0. Сторінка за межами результатів також має порожній data, але зберігає загальну кількість знайдених документів. Недоступний або чужий ID не розкриває документ.

Помилки

`code`	Причина
`VALIDATION_ERROR`	Невалідний формат фільтра, дата, ID, логічне поле або пагінація.
`ACCESS_DENIED`	Немає права перегляду типу документа.
`FEATURE_UNAVAILABLE`	Тип документа недоступний за тарифом.
`UNKNOWN`	Інша серверна помилка; перевірте `error`.

Помилка має форму {"success": false, "error": "…", "code": "…"}. Перевіряйте поле success, а не лише HTTP-статус. Не додавайте відхилену або порожню відповідь до обороту як успішно прочитаний чек.

Фіскальні чеки

Фіскальні чеки отримуйте окремим методом POST /api/v2/document/fiscal_receipt/list. Кожен запис містить посилання на чек і SourceDocument — документ, з якого його видано. Фільтри, пагінація та повторний обмін описані в статті Журнал фіскальних чеків.