Асинхронні фіскальні операції#
Асинхронні методи запускають фіскальну операцію та повертають її ідентифікатор operationId. Виконання відбувається окремо: успішна відповідь на запит запуску означає отримання ідентифікатора операції, але ще не підтверджує успішну фіскалізацію.Порядок роботи#
1.
Надішліть запит до відповідного асинхронного методу.
2.
Збережіть data.operationId з відповіді.
3.
Перевіряйте стан через відповідний метод GET .../fiscalisation-operations/{operationId} для чеків, службових чеків або змін.
4.
Поки операція має статус PENDING або PROCESSING, продовжуйте перевірку. Рекомендований початковий інтервал — 1–2 секунди; для тривалого очікування його можна поступово збільшувати.
5.
Після COMPLETED отримайте результат із data.result. Склад результату залежить від типу операції та описаний у відповідному методі.
Приклад успішної відповіді запуску:{
"success": true,
"data": {
"operationId": "f44c9d98-7e46-43b1-a19c-b8636a89eed0"
},
"errors": null
}
Поле status у відповіді запуску не повертається. Актуальний стан потрібно отримувати окремим запитом перевірки операції.Стани операції#
| Статус | Значення | Подальша дія |
|---|
PENDING | Операцію створено, виконання ще не почалося. | Продовжуйте перевірку. |
PROCESSING | Операція виконується. | Продовжуйте перевірку. |
COMPLETED | Операцію завершено. | Отримайте data.result. |
FAILED | Спроба завершилася помилкою. | Перевірте причину помилки та фактичний стан чека або зміни перед повторенням. |
FAILED є станом операції в системі. За наявності збереженої помилки поточний API повертає її через HTTP 400, тому клієнт повинен обробляти також HTTP-помилки перевірки, а не лише значення data.status в успішній відповіді.Помилки#
Помилки можуть виникати як під час запуску, так і під час виконання операції. Помилка запуску стосується запиту або підготовки операції; помилка, отримана під час перевірки operationId, може стосуватися виконання вже створеної операції.Типова форма відповіді з помилкою:{
"success": false,
"data": null,
"errors": {
"id": "<код конкретної помилки>",
"message": "<опис причини>"
}
}
HTTP 400 під час перевірки — може означати невдале виконання операції. Аналізуйте errors.id і errors.message; код причини не обов’язково має значення FAILED.
HTTP 404 — операцію з переданим operationId не знайдено. Це не статус FAILED.
HTTP 403 — доступ до запиту заборонено.
Мережева помилка або HTTP 5xx — самі по собі не підтверджують завершення чи невиконання фіскальної операції. Повторіть перевірку того самого operationId.
Якщо очікування у вашому застосунку завершилося за таймаутом, збережіть operationId: операція може продовжувати виконуватися. Не створюйте нову операцію лише через тривале очікування.Повторне надсилання запиту#
Для методів, які підтримують clientCheckId, сформуйте та збережіть його до першого надсилання. Якщо відповідь запуску загубилася, повторіть той самий запит із тим самим ідентифікатором та незміненими параметрами. Без клієнтського ідентифікатора сервер генерує новий, тому стабільне повторення запиту клієнтом не забезпечується.Якщо для обчисленого ключа повторення вже існує операція PENDING, PROCESSING або COMPLETED, сервіс повертає її operationId без повторної постановки в чергу. Це може бути ідентифікатор уже завершеної операції. Отримайте її актуальний стан і результат через метод перевірки.Після FAILED повторний запит може створити нову спробу з новим operationId. Надалі перевіряйте новий ідентифікатор; попередній залишається ідентифікатором попередньої спроби. Перед повторенням перевірте причину помилки та фактичний стан чека або зміни: невдала спроба не гарантує відсутності вже виконаних фіскальних дій.Особливості окремих методів:Продаж і переказ: clientCheckId передається на верхньому рівні тіла запиту. Ключ також залежить від checkId і типу операції. Не змінюйте checkId при повторенні. Якщо checkId не передано, підготовка чека відбувається до перевірки ключа та може виконуватися повторно.
Відміна/повернення та службові чеки: ідентифікатор передається в additionalInfo.clientCheckId. Для відміни/повернення пробільні символи видаляються при формуванні ключа.
Відкриття зміни: clientCheckId передається на верхньому рівні тіла запиту.
Закриття зміни: повторення визначається касою та shiftId, а не clientCheckId.
Використовуйте окремий унікальний clientCheckId для кожної нової операції, зокрема між касами та типами операцій. Не використовуйте повторний ключ для редагування даних: змінений запит не оновлює вже наявну операцію. Конкретні поля та правила повторення наведені в описі кожного методу.Modified at 2026-10-23 08:23:00