QUINCE API. Журнал фіскальних чеків

Для передавання інформації про видані чеки ПРРО у зовнішню систему використовуйте окремий метод POST /api/v2/document/fiscal_receipt/list. Він повертає список чеків Checkbox і Вчасно.Каса. У кожного чека є SourceDocument — документ QUINCEFIN, з якого його видано.

Запит лише читає збережені дані й не виконує фіскальних операцій у провайдера. Авторизація описана в налаштуваннях підключення API. Для роботи методу потрібна серверна версія QUINCEFIN із підтримкою журналу.

Запит

POST /api/v2/document/fiscal_receipt/list
Content-Type: application/json

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

Параметри

Усі параметри необов’язкові. page — ціле число від 1, типово 1; limit — від 1 до 1000, типово 100. Фільтри передавайте в об’єкті filter.

Фільтр	Опис
`DateFrom`, `DateTo`	Період дати документа-підстави, у часовому поясі користувача API. Передавайте обидві межі у форматі `YYYY-MM-DD` або `YYYY-MM-DD HH:mm:ss`. Кінцева дата включає весь день, кінцевий час — усю зазначену секунду.
`SourceDocumentId`	ID конкретного документа-підстави. Без періоду шукає його чек незалежно від дати документа, у межах дозволеного тарифом доступу.
`SourceDocumentType`	Один із типів документа з таблиці нижче.
`Company`	ID організації документа-підстави.
`Pos`	ID точки продажу документа-підстави.
`Provider`	Збережений код ПРРО, наприклад `checkbox` або `vchasno`.
`IsReturn`	`true` — лише чеки повернення; `false` — лише чеки продажу; без фільтра — обидва види.
`Archive`	`true` — чеки архівних документів; `false` — неархівних. Без фільтра повертаються обидва варіанти: архівування документа не скасовує виданий чек.

Без DateFrom/DateTo та SourceDocumentId метод вибирає поточний день у часовому поясі користувача API. Для обміну за період завжди задавайте дати явно. Великі ID передавайте десятковими рядками, щоб уникнути втрати точності в JavaScript.

`SourceDocumentType`	Документ-підстава
`OUTGOING_ORDER`	Замовлення покупця
`OUTGOING_INVOICE`	Реалізація
`OUTGOING_RETURN_INVOICE`	Повернення від покупця
`RECEIPT`	Роздрібний чек
`PURCHASE_RETURN`	Роздрібний чек повернення

Щоб отримати чек конкретного документа:

{ "filter": { "SourceDocumentId": "123400" } }

Якщо чек видано на замовленні, SourceDocumentId має містити ID цього замовлення. Пов’язана реалізація без власного чека не створює додаткового запису в журналі.

Відповідь

Приклад із вигаданими даними:

{
  "success": true,
  "data": [{
    "Id": "11111111-2222-3333-4444-555555555555",
    "Provider": "checkbox",
    "ReceiptId": "11111111-2222-3333-4444-555555555555",
    "ReceiptUrl": "https://api.checkbox.in.ua/api/v1/receipts/11111111-2222-3333-4444-555555555555/html",
    "IsReturn": false,
    "SourceDocument": {
      "Id": 123400,
      "Type": "OUTGOING_ORDER",
      "Number": 87,
      "Date": "2026-10-15T12:30:00",
      "Guid": "11111111-2222-3333-4444-555555555555",
      "Archive": false
    }
  }],
  "paging": { "page": 1, "size": 100, "totalItems": 1, "totalPages": 1 }
}

Поле	Опис
`Id`	Стабільний ключ запису журналу QUINCEFIN. У поточній моделі це GUID документа-підстави; використовуйте разом з ідентифікатором облікового запису для повторного імпорту.
`Provider`	Код ПРРО. Для неповних історичних даних можливе `null`.
`ReceiptId`	UUID чека Checkbox; для Вчасно.Каса — `null`. Це ідентифікатор провайдера, а не фіскальний номер.
`ReceiptUrl`	Посилання на HTML-чек Checkbox або збережене посилання Вчасно.Каса. Може бути `null`, якщо даних для посилання немає.
`IsReturn`	Ознака чека повернення.
`SourceDocument.Id`, `SourceDocument.Type`	ID та тип документа, на якому видано чек. За ними зіставляйте документ із записом у зовнішній системі.
`SourceDocument.Number`, `SourceDocument.Date`	Номер і дата документа QUINCEFIN. Дата — у часовому поясі користувача API; це не фіскальний номер і не час видачі чека.
`SourceDocument.Guid`	GUID документа-підстави.
`SourceDocument.Archive`	Чи архівований документ-підстава.
`paging`	Номер і розмір сторінки, загальна кількість доступних записів та сторінок після застосування фільтрів.

Записи впорядковані за зростанням SourceDocument.Id. Кожен фіскалізований документ з’являється один раз. Повернення має власний документ-підставу. Якщо записів немає, data дорівнює [], а totalItems і totalPages — 0. Сторінка за межами списку має порожній data, але зберігає загальні лічильники.

Повторний обмін

Перевірте success. Помилка запиту або відсутність методу в старій версії сервера не означає відсутності чеків.
Прочитайте всі сторінки за однакових фільтрів, збільшуючи page до paging.totalPages.
Для кожного запису збережіть Id, SourceDocument, провайдера, посилання на чек та ознаку повернення.
Оновлюйте наявний запис за парою «обліковий запис QUINCEFIN + Id», щоб повторне завантаження не створювало дубль.
Періодично повторюйте звірку потрібного облікового періоду та документів, для яких очікуєте чек. Між сторінками дані можуть змінитися; повторна звірка за стабільними ключами врахує такі зміни.

Фіскалізація старого документа не обов’язково змінює його DateModified. Метод фільтрує дату документа і не є стрічкою подій за часом фіскалізації. Порожній список не є командою видалити раніше імпортовані чеки.

Доступ і помилки

Потрібне право перегляду журналу фіскалізованих документів, відповідних типів документів і самих документів-підстав. Діють обмеження тарифу, зокрема доступного періоду. Недоступні документи не потрапляють ані в data, ані в лічильники пагінації.

Невірні дати, ID, фільтри чи пагінація повертають success: false із кодом VALIDATION_ERROR. Відмова в доступі до журналу повертає ACCESS_DENIED, недоступна за тарифом функціональність — FEATURE_UNAVAILABLE. Обробляйте будь-яку відповідь із success: false як помилку.

Межі даних

Журнал повертає збережену в QUINCEFIN інформацію й не опитує ПРРО. Окремий фіскальний номер, точний час видачі та поточний статус у провайдера до відповіді не входять. Доступність зовнішнього посилання залежить від провайдера.

Для читання самих документів використовуйте API замовлень, реалізацій, повернень і роздрібних документів.