| Фіскалізовано
|
FISCALIZED
|
Чек успішно фіскалізовано. Каса
щоб контролювати фіскалізацію, помилки, повернення і незакриті зміни. | Зупинити інтеграцію, повідомити адміністратора. Тип
|
|
4. SEO-опис
receipt.error_message = str(exc)
25. MVP
|
| Чеків створено
|
Загальна кількість чеків за період. Код
|
| Ручне відкриття
|
користувач системи або адміністратор відкриває зміну. )
|
-
|
Втрата чека
|
API недоступне під час продажу. },
- email;
- SMS;
- Viber;
- інший канал, якщо підтримується сервісом. |}
12.1. Загальна схема
Технічний стек: Python 3.11+, FastAPI, PostgreSQL, SQLAlchemy, Alembic, httpx, Pydantic, Celery/RQ/APScheduler, Redis, Docker. Тип
щоб не втратити продаж. |-
|
FiscalApiError
|
API повернув помилку. Поле
Python-сервіс повинен приймати інформаційні дані продажу та створювати фіскальний чек. Колір
"idempotency_key": command.idempotency_key,
18. API Python-сервісу
except TemporaryFiscalError as exc:
Сервіс повинен забезпечити:
return existing
existing = receipt_repository.get_by_idempotency_key(
POST /api/v1/fiscal/integrations/{integration_id}/check-connection
|
-
|
AC-16
|
Реалізується в межах цього ТЗ. Очікуваний результат
24.5. Dashboard
receipt.status = "FISCALIZATION_ERROR"
Якщо API або конфігурація «Вчасно.Каса» підтримують електронну відправку чека, Python-сервіс повинен передавати email або телефон покупця. Логічний endpoint:
платформа повинна підтримувати отримання проміжного X-звіту без закриття зміни. SEO-опис
"customer": {
18.5. Отримання чека
receipt.error_message = str(exc)
! receipt.fiscal_url = response.fiscal_url
{| class="wikitable"
! Значення
! |-
| Повернення
| Високий
| Важлива фінансова операційна дія. |-
| Зміна налаштувань
| користувач системи, старі та нові параметри. |-
| Перевірка перед чеком
| Якщо зміна вже відкрита, повторно не відкривати. Де застосовується для
=== 8.6. Закриття зміни ===
VCHASNO_KASA_INTEGRATION_MODE=cloud_api
[[Категорія:Фіскалізація]]
! Критерій
=== 8.3. Приклад запиту на чек ===
"fiscal_url": response.fiscal_url,
== 15. Дедублікація ==
Сценарії:
POST /api/v1/fiscal/shifts/{shift_id}/close
! # Чи потрібна технічна підтримка часткових повернень? |-
| Загальна БД чеків
| Усі чеки зберігаються в єдиній БД Python-сервісу. я хочу передати інформацію про оплату в Python-сервіс,
{| class="wikitable"
! Тип
Логічний endpoint:
8.2. Створення чека продажу
ERP / CRM / Website / POS
! |}
Для підвищення надійності фіскалізація повинна виконуватись через чергу. |-
| sku
| varchar
| Артикул. я хочу бачити dashboard по касах і чеках,
=== 16.1. Логіка черги ===
POST /api/v1/fiscal/shifts/open
! SEO-опис
{| class="wikitable"
! receipt = receipt_repository.get_by_id(db, receipt_id)
* повноцінний POS-інтерфейс касира;
* власна реалізація ПРРО без «Вчасно.Каса»;
* самостійна реєстрація ПРРО в ДПС через Python-сервіс;
* власний компонент КЕП;
* інтеграційні функції ERP з усіма еквайрингами;
* складний UI для касира;
* заміна кабінету «Вчасно.Каса». |-
| new_status
| varchar
| Новий статус. |-
| integration_mode
| varchar
| cloud_api, device_manager, hybrid. |-
| Хмарне API «Вчасно.Каса»
| Пряма інтеграційні функції ERP з кабінетом та фіскалізацією чеків. # Чи потрібен dashboard у UI, чи тільки API? Поле
== 6. Основні сутності ==
|-
| id
| uuid
| Внутрішній ID чека. |-
| AC-17
| виступає як незакриті зміни. |-
| external_cash_register_id
| varchar
| ID каси у «Вчасно.Каса». # Чи потрібна технічна підтримка декількох юридичних осіб? |-
| AC-13
| користувач системи закриває зміну. |-
| api_token_encrypted
| text
| Зашифрований токен. |-
| external_payment_id
| varchar
| ID оплати. | Healthcheck і fallback-сценарій. |-
| style="background:#ef9a9a;" | Червоний
| #ef9a9a
| Помилка або критична ситуація. |-
| fiscal_number
| varchar
| Фіскальний номер. Тип
|-
| «Вчасно.Каса»
| ПРРО-сервіс для фіскалізації чеків. | Python-сервіс створює чек зі статусом PENDING. №
|
style="background:#c8e6c9;" | Норма
|
| Очікують
|
Чеки в черзі. Сценарій
{
8.7. X-звіт
class VchasnoKasaSettings(BaseSettings):
v
Логічний endpoint Python-сервісу:
cash_register_id=receipt.cash_register_id,
VCHASNO_KASA_API_TOKEN=********
18.8. Відкриття зміни
entity_type="receipt",
"tax_group": "NO_VAT",
21.1. Основні KPI
щоб коректно відобразити повернення коштів покупцю. | Вони підсвічуються червоним. | платформа відкриває зміну, якщо auto_open_shift = true. # Чи потрібно автоматизовано відкривати зміну?== 1. Мета ==
- Python API для прийому продажів;
- клієнт ERP інтеграції з «Вчасно.Каса»;
- технічна підтримка фіскалізації чеків;
- технічна підтримка повернень;
- відкриття та закриття змін;
- збереження чеків;
- збереження статусів;
- журнал помилок;
- retry-механізм;
- dashboard / API для контролю;
- інтеграційні функції ERP з внутрішньою системою. №
| id
|
uuid
|
ID інтеграції. SEO-опис
5. Варіанти інтеграції
|
-
|
TimeoutError
|
-
|
name
|
varchar
|
-
|
status
|
varchar
|
class="wikitable"
<syntaxhighlight lang="python">
!
"fiscal_operation_type": "sale",
Варіант 2. 5.2. Device Manager
}
платформа повинна не допускати дублювання чеків. ! |-
|
Завантаження PDF
|
Низький
|
}
"name": "Іван Петренко",
Для реалізації задачі необхідно отримати:
)
</syntaxhighlight>
|
retry_count: int = 3
Варіант 3. 5.3. Гібридна схема
18.9. Закриття зміни
| -
|
CashRegisterError
|
-
|
cash_register_id
|
string
|
-
|
Validation Layer
|
Перевіряє товари, суми, оплати, податки, касу, касира. Поле
verify_ssl: bool = True
"email": "customer@example.com",
|
Статус / номер / посилання на чек
23. Логування та аудит
Мінімальні інформаційні дані:
|
|
Idempotency key і дедублікація. |}
це Python-клас або пакет, який інкапсулює роботу з API «Вчасно виступає ключовою рисою Vchasno Kasa Client.Каса» або Device Manager. |-
|
Невірна податкова група
|
Draft, Cancelled, Closed. # Які платіжні провайдери використовуються? Як зменшити
if existing:
Приклад hash:
default_cashier_id: str | None = None
POST /api/v1/fiscal/receipts
16.2. Пріоритети задач
|
=== Етап 1. Базова структура сервісу ===
платформа повинна підтримувати синхронізацію статусу чека з «Вчасно.Каса». | style="background:#ef9a9a;" | Критично
|
| Повернення
|
-
|
ShiftError
|
Помилка відкриття або закриття зміни.== 10. Статуси зміни ==
db.commit()
timeout_seconds: int = 30
|
-
|
idempotency_key
|
varchar
|
}
8.8. Отримання статусу чека
- Який сценарій інтеграції застосовується для: хмарне API, Device Manager або гібрид? Стан
27. Ризики
4. Передумови
|
-
|
send_receipt_to_customer
|
boolean
|
Ні
|
-
|
AC-5
|
}
def check_connection(self) -> "ConnectionStatus":
- створення інтеграції;
- перевірка підключення;
- створення чека продажу;
- створення чека повернення;
- валідація чеків;
- дедублікація;
- черга фіскалізації;
- відкриття зміни;
- закриття зміни;
- отримання статусу чека;
- збереження fiscal_number;
- журнал подій;
- retry-механізм;
- dashboard API;
- базові unit-тести;
- mock API для інтеграційних тестів. Від цього залежить технічна архітектура, мережеві конфігурація, обробка офлайн-ситуацій і друк чеків. |-
| external_shift_id
|
varchar
|
-
|
base_url
|
varchar
|
URL API. Поле
|
SEO-опис
|
№
},
14. Валідація чека
payload={"receipt_id": str(receipt.id)},
|
| external_order_id
|
string
|
ID замовлення у зовнішній системі. SEO-опис
try:
|
}
],
VCHASNO_KASA_ORGANIZATION_ID=org-001
{
|
|
-
|
Status Sync Worker
|
-
|
opened_at
|
timestamp
|
Дата відкриття. Тип
if receipt.status == "FISCALIZED":
</syntaxhighlight>
=== 20.2. Retry-логіка ===
! |-
| external_order_id
| varchar
| ID замовлення. | Refund, сторно, коригування. # Чи потрібно зберігати PDF чека локально? |-
| provider
| varchar
| LiqPay, WayForPay, Mono, terminal тощо. Валідація, дедублікація, черга
== Див. 30. так само ==
pass
|
| 3.[[Категорія:Технічні завдання]]
* створити FastAPI-проєкт;
* налаштувати PostgreSQL;
* створити моделі інтеграції, кас, змін, чеків;
* налаштувати Alembic;
* реалізувати healthcheck. |-
| customer
| object
| інформаційні дані покупця. | базовий зовнішній сервіс інтеграції. |-
| current_shift_id
| uuid
| Поточна зміна. Показник
</pre>
! | Другий чек не створюється. |-
| Vchasno Kasa Client
| Python-клієнт для API «Вчасно.Каса» або Device Manager. | style="background:#fff9c4;" | Жовтий
|-
| Відправляється
| SENDING
| Виконується API-запит. "currency": "UAH"
{
def close_shift(self, shift_id: str) -> "ZReportResponse":
!== 8. Функціональні вимоги ==
! |-
| AC-8
| API повертає тимчасову помилку. | Підходить для інтеграцій з локальними системами, POS, принтерами. Сценарій
=== 19.2. Worker фіскалізації ===
=== 12.2. Основні компоненти Python-сервісу ===
entity_id=receipt.id,
|-
| AC-15
| Керівник відкриває dashboard. |-
| raw_response
| jsonb
| Відповідь API. |-
| ERP / CRM / сайт / POS
| Джерело продажів, повернень, оплат і даних покупця. Поле
"total_amount": command.total_amount,
! |-
| Shift
| Касова зміна. |-
| Незакрита зміна
| Касир або платформа не закрили зміну. |-
| event_type
| varchar
| Тип події. | Повернути існуючий чек. | інтеграційні функції ERP зберігається в системі. | Чек отримує статус FISCALIZED. | style="background:#e3f2fd;" | Інформаційний
|-
| Фіскалізовано
| Кількість успішних чеків. |-
| integration_mode
| enum
| Так
| cloud_api, device_manager, hybrid. Worker викликає API «Вчасно.Каса». |-
| receipt_hash
| Hash товарів, сум, оплат і замовлення. |}
receipt.status = "NEEDS_RETRY"
"name": "Товар 1",
* timeout;
* тимчасової недоступності API;
* HTTP 429;
* HTTP 500;
* HTTP 502;
* HTTP 503;
* HTTP 504;
* мережевих помилок;
* тимчасової помилки Device Manager. |-
| original_fiscal_number
| string
| Фіскальний номер первинного чека. # Які податкові групи товарів використовуються? |-
| Помилки токена
| Токен змінено або відкликано. |-
| provider
| varchar
| vchasno_kasa. Тип
{| class="wikitable"
! |-
| receipt_type
| varchar
| sale або refund. SEO-опис
! ! |-
| AC-10
| Сума повернення більша за суму продажу. Очікуваний результат
__TOC__
! pass
event_type="RECEIPT_QUEUED",
=== 17.2. cash_registers ===
db.commit()
POST /api/v1/fiscal/shifts/{shift_id}/x-report
"quantity": 2,
платформа повинна логувати:
<syntaxhighlight lang="python">
Retry не застосовується для:
! Колір
== 17. Модель даних ==
=== Етап 5. Повернення ===
платформа повинна дозволяти створити конфігурація підключення до «Вчасно.Каса». | Записати помилку, дозволити повтор. API приймає запит на створення чека. |}
! Ризик
<pre>
Retry застосовується для:
== 11. Єдина логіка кольорів ==
api_token: str
</pre>
cashier_id=receipt.cashier_id,
ERP / CRM / Website / POS
* наявність external_order_id;
* відсутність уже фіскалізованого чека по цьому external_order_id;
* наявність каси;
* наявність касира;
* наявність відкритої зміни або можливість її відкрити;
* наявність хоча б однієї позиції;
* коректність кількості;
* коректність ціни;
* коректність суми рядка;
* відповідність total_amount сумі товарів і оплат;
* коректність типу оплати;
* коректність податкових груп;
* коректність email або телефону покупця, якщо чек потрібно відправити. | Помилки фіскалізації, незакрита зміна. Параметр
data={
pass
"unit": "послуга"
},
! |-
| DuplicateReceiptError
| Чек уже створено. |}
<div style="border-left: 6px solid #1565c0; background: #e3f2fd; padding: 12px 16px; margin: 16px 0;">
! Сутність
"amount": 70.00,
{| class="wikitable"
|-
| Чернетка
| DRAFT
| Чек створено у Python-сервісі, але ще не відправлено. | У БД зберігається fiscal_number. |-
| конкурентні переваги
| Немає локального застосунку, простіша інфраструктура. |-
| Закриття зміни
| Z-звіт, час, результат. SEO-опис
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
pass
<div style="border-left: 6px solid #c62828; background: #ffebee; padding: 12px 16px; margin: 16px 0;">
|-
| API Layer
| REST API для прийому продажів, повернень, команд зміни. |-
| Обмеження
| Потрібен стабільний інтернет і доступ до зовнішнього API. Конкретний сценарій потрібно зафіксувати в налаштуваннях інтеграції. |-
| base_url
| string
| Так
| Базова адреса API або Device Manager. |-
| is_active
| boolean
| Так
| Ознака активності інтеграції. |-
| Dashboard API
| інформаційні дані для керівника: чеки, зміни, помилки, обороти. |-
| AC-7
| Повторний запит має той самий idempotency_key. |-
| integration_id
| uuid
| ID інтеграції. |-
| auto_open_shift
| boolean
| Так
| автоматизовано відкривати зміну перед першим чеком. |-
| Receipt
| Фіскальний чек продажу. | Черга, статуси API. Статус
{{SEO
|title=Технічне завдання: Інтеграція Вчасно.Каса для Python
|description=Технічне завдання на реалізацію Python-сервісу для інтеграції з Вчасно.Каса: фіскалізація чеків, відкриття і закриття змін, повернення, X/Z-звіти, статуси, помилки, API-клієнт, черги та журналювання.
|keywords=Python, Вчасно.Каса, ПРРО, API, фіскалізація чеків, каса, програмний РРО, FastAPI, інтеграція, технічне завдання, K2 ERP
}}
entity_id=receipt.id,
"cash_register_id": "cash-register-001",
|-
| integration_name
| string
| Так
| Назва інтеграції.=== 24.3. Повернення ===
{| class="wikitable"
! SEO-опис
3. Значення
== 3. Джерела інтеграції ==
{| class="wikitable"
{| class="wikitable"
{| class="wikitable"
6. |-
| created_at
| timestamp
| Дата створення. №
<div style="border-left: 6px solid #6a1b9a; background: #f3e5f5; padding: 12px 16px; margin: 16px 0;">
"cashier_id": "cashier-001",
{| class="wikitable"
GET /api/v1/fiscal/dashboard?date_from=2026-05-01&date_to=2026-05-07
|-
| id
| uuid
| ID події. |}
== 28. Відкриті питання ==
! |-
| is_active
| boolean
| Чи застосовується для. Компонент
receipt.status = "SENDING"
|-
| original_receipt_id
| uuid
| Внутрішній ID первинного чека. ERP / CRM / сайт отримує статус. Поле
== 16. Черга фіскалізації ==
{| class="wikitable"
<pre>
! Критерій
POST /api/v1/fiscal/receipts/{receipt_id}/sync-status
=== 18.10. X-звіт ===
=== 18.7. Повторна фіскалізація ===
def get_receipt_pdf(self, receipt_id: str) -> bytes:
pass
</div>
=== Етап 3. Vchasno Kasa Client ===
"sku": "SKU-001",
! |-
| is_active
| boolean
| Активність. |}
"currency": command.currency,
=== 17.1. fiscal_integrations ===
! | style="background:#bbdefb;" | Блакитний
|-
| Відкрита
| OPEN
| Можна фіскалізувати чеки. |-
| Відправка в API
| endpoint, час, request_id. щоб розуміти, чи можна фіскалізувати чеки. |-
| Python-сервіс
| Інтеграційний шар між ERP / сайтом / CRM / POS та «Вчасно.Каса». | Первинний чек отримує ознаку повного або часткового повернення. |-
| raw_request
| jsonb
| Запит до API.<pre>
Перед фіскалізацією платформа повинна перевірити:
* перевірити відкриту зміну;
* перевірити незавершені чеки;
* сформувати Z-звіт;
* зберегти результат;
* змінити статус зміни на Closed;
* записати подію в журнал. |-
| price
| numeric
| Ціна. |-
| Device Manager недоступний
| Локальний застосунок не відповідає. оновлення версій ERP / CRM / POS
"receipt_type": "sale",
! |-
| cash_register_id
| uuid
| Каса. Створюється запис receipt зі статусом PENDING. SEO-опис
POST /api/v1/fiscal/receipts/{receipt_id}/sync-status
default_cash_register_id: str | None = None
Вчасно.Каса
payload={
! SEO-опис
POST /api/v1/fiscal/refund-receipts
|-
| Створення чека
| external_order_id, сума, каса, касир. |-
| external_order_id
| базовий ключ від зовнішньої системи. |-
| cash_register_id
| uuid
| Каса. |-
| X Report
| Проміжний звіт без закриття зміни.== 2. Область сценарії використання ==
* додати rate limiting;
* додати alerting;
* додати retry policy;
* додати dead letter queue;
* додати моніторинг;
* додати резервне копіювання. автоматичної фіскалізації чеків забезпечується через '''Головна ідея:''' розробити Python-сервіс.Каса»; так само реалізовано контролю касових змін, повернень, статусів, помилок і друку або відправки електронних чеків покупцям. |-
| Refund Receipt
| Чек повернення. Обов'язковість
! |-
| Payment
| Оплата в чеку: готівка, картка, онлайн-еквайринг тощо.== 21. Dashboard керівника ==
* реалізувати dashboard API;
* реалізувати журнал подій;
* реалізувати фільтри;
* реалізувати експорт, якщо потрібно. Параметр
=== 17.6. fiscal_payments ===
=== 24.4. Зміни ===
[[Категорія:Вчасно.Каса]]
=== 7.3. Контроль зміни ===
=== Етап 4. Чеки ===
=== 17.7. fiscal_events ===
<syntaxhighlight lang="python">
<pre>
"amount": 500.00,
<pre>
'''Управлінський результат:''' керівник повинен бачити, скільки чеків сформовано, скільки фіскалізовано, скільки помилок, які каси відкриті, які зміни не закриті, скільки повернень і які операції потребують уваги. |-
| currency
| string
| Валюта. |}
],
POST /api/v1/fiscal/shifts/open
{| class="wikitable"
=== Етап 2. конфігурація інтеграції ===
integration_mode: str = "cloud_api"
|-
| Підходить для
| POS-систем, локальних облікових систем, магазинів із чековими принтерами. Cloud API або Device Manager
! Критерій
Як керівник,
=== 18.3. Створення чека продажу ===
POST /api/v1/fiscal/shifts/{shift_id}/close
! |-
| Повторна обробка
| хто запустив, коли, результат. |-
| cashier_id
| varchar
| Касир. return receipt
* помилок валідації;
* неправильного токена;
* дублювання чека;
* некоректних сум;
* неправильних податкових груп;
* повернення понад доступну суму. |-
| Помилка фіскалізації
| код помилки, повідомлення, raw-відповідь. |}
[[Категорія:ПРРО]]
</pre>
VCHASNO_KASA_BASE_URL=https://api.example.vchasno-kasa
'''Критично критично:''' чек повернення повинен бути пов'язаний із первинним чеком. Що зберігати
платформа повинна підтримувати створення чека повернення. |-
| integration_id
| uuid
| ID інтеграції. Замовлення
Як адміністратор,
== 19. Приклад Python-логіки ==
{| class="wikitable"
v
{| class="wikitable"
=== 19.1. Створення чека ===
=== 21.2. Приклад dashboard ===
! |-
| items
| array
| Позиції чека. |-
| api_token
| secret
| Так
| Токен інтеграції. |-
| created_at
| timestamp
| Дата події.<div style="border-left: 6px solid #f57c00; background: #fff3e0; padding: 12px 16px; margin: 16px 0;">
|-
| Cash Register
| Каса / ПРРО, через яку фіскалізуються чеки. | style="background:#fff9c4;" | Увага
|-
| Помилки
| Чеки з помилкою. Колір
"quantity": 1,
! | платформа попереджає перед закриттям зміни. Пріоритет
POST /api/v1/fiscal/receipts
! |}
pass
Ключі дедублікації:
! |-
| Deduplication Service
| Захищає від повторної фіскалізації одного продажу. |-
| amount
| numeric
| Сума. | Валідація перед фіскалізацією. # Чи потрібна технічна підтримка локального друку чеків? |}
Python Fiscal Service
<pre>
audit_logger.log(
|
| id
|
uuid
|
-
|
updated_at
|
timestamp
|
Виконати retry. |-
|
AC-1
|
Адміністратор створює інтеграцію. # Які типи оплат підтримуються? Дія
12. технічна архітектура рішення для бізнесу
18.2. Перевірка підключення
POST /api/v1/fiscal/refund-receipts
|
Сума
v
)
|
-
|
fiscal_number
|
varchar
|
Фіскальний номер ПРРО, якщо доступний. Ключ
- повноцінний POS UI;
- власний ПРРО;
- інтеграційні функції ERP з усіма еквайрингами;
- складна аналітичні інструменти;
- автоматична реєстрація ПРРО в ДПС;
- технічна підтримка всіх нестандартних податкових сценаріїв;
- повна офлайн-робота без Device Manager. POST /api/v1/fiscal/integrations
except Exception as exc:
}
=== 18.1. Створення інтеграції ===
! | Не відправляти чек, повернути список помилок. |-
| Основні операції
| Фіскалізація чеків, друк, робота з POS-пристроями, X/Z-звіти. |-
| receipt_id
| uuid
| ID чека. | Він бачить кількість чеків, помилок, повернень і незакритих змін. |-
| AuthError
| Невірний API token або відсутній доступ. |-
| error_message
| text
| Остання помилка. ! |-
| Receipt Service
| Створення чеків продажу. SEO-опис
<pre>
</syntaxhighlight>
=== 24.2. Чеки ===
</div>
=== 8.4. Чек повернення ===
! Як касир або адміністратор,
== 29. Джерела ==
=== 18.4. Створення чека повернення ===
До MVP не входить:
"provider": "liqpay",
"external_order_id": command.external_order_id,
)
Критично критично: до початку розробки потрібно визначити сценарій інтеграції: хмарне API або Device Manager. |-
|
Fiscal Queue
|
-
|
Блакитний
|
#bbdefb
|
операційна дія виконується або в роботі. Поле
|
-
|
AC-3
|
Токен неправильний. Поле
def create_fiscal_receipt(command: "CreateReceiptCommand", db: "Session") -> "FiscalReceipt":
|
| Не відкрита
|
CLOSED
|
style="background:#ef9a9a;" | Червоний
|
Варіант 1. 5.1. Хмарне API
v
До MVP входить:
Вчасно.Каса
|-
| style="background:#c8e6c9;" | Зелений
| #c8e6c9
| Успішно: чек фіскалізовано, зміна відкрита або закрита коректно. |-
| Відкриття зміни
| каса, касир, час. |-
| error_message
| text
| Остання помилка. |}
Python-сервіс підтримує обидва способи інтеграції. v
|
"sku": "DELIVERY",
- реалізувати створення інтеграції;
- реалізувати зберігання токена;
- реалізувати check-connection;
- реалізувати права доступу.=== Етап 7. Dashboard та аудит ===
18.6. Синхронізація статусу чека
Як оператор або ERP,
17.3. fiscal_shifts
9. Статуси чеків
return
"price": 70.00,
Python-сервіс взаємодіє з Device Manager, який виконує інтеграційні функції локально або в середовищі клієнта. |-
|
external_payment_id
|
varchar
|
-
|
fiscal_url
|
varchar
|
Посилання на чек, якщо доступне. Фіскалізація через ПРРО
щоб він автоматизовано створив фіскальний чек у «Вчасно.Каса». Дія системи
entity_type="receipt",
функції ERP застосовується для для:
|
# Чи потрібна інтеграційні функції ERP з K2 ERP?=== 7.5. Контроль керівника ===
"payments": [
def create_receipt(self, payload: "ReceiptPayload") -> "ReceiptResponse":
receipt.fiscal_number = response.fiscal_number
| style="background:#c8e6c9;" | Зелений
|
| Помилка
|
ERROR
|
-
|
default_tax_group
|
string
|
Ні
|
Податкова група за замовчуванням. Код
7.2. Повернення
|
| id
|
uuid
|
-
|
external_refund_id
|
string
|
ID повернення у зовнішній системі. Тип
pass
Заборонено: зберігати API token, ключі, паролі касирів або інші секрети у коді, Git-репозиторії, відкритих логах або frontend-змінних. |-
|
Обмеження
|
-
|
total_amount
|
numeric
|
-
|
AC-6
|
-
|
idempotency_key
|
style="background:#ffcc80;" | Помаранчевий
|
| Скасовано
|
CANCELLED
|
Операцію скасовано. Фіскальний результат
До області задачі входить:
Логічний endpoint:
|
|
Retry, незавершені операції. # Чи потрібна технічна підтримка декількох торгових точок? SEO-опис
Vchasno Kasa Adapter
Python-сервіс напряму викликає хмарне API «Вчасно.Каса». | style="background:#f3e5f5;" | Фіолетовий
|}
=== 13.2. Основні методи ===
! |-
| name
| varchar
| Назва товару або послуги. |-
| Закриття зміни
| Критичний
| Не можна залишати зміну незакритою. |-
| qr_code
| text
| QR або інформаційні дані QR, якщо доступні. | як приклад K2 ERP або інша платформа. |}
receipt.qr_code = response.qr_code
def create_refund_receipt(self, payload: "RefundReceiptPayload") -> "ReceiptResponse":
{
1. | Check-connection і сповіщення адміністратора. |-
| z_report_number
| varchar
| Номер Z-звіту.<pre>
|-
| AC-12
| Перед першим чеком зміна закрита. "external_payment_id": command.external_payment_id,
|
Коментар
class VchasnoKasaClient:
|
-
|
ДПС
|
style="background:#ffcc80;" | Потрібна дія
|
Мінімальні інформаційні дані:
"external_order_id": "ORDER-2026-000123",
18.11. Dashboard
я хочу повторити фіскалізацію після технічної помилки,
|
-
|
AC-14
|
style="background:#c8e6c9;" | Зелений
|
| Закривається
|
CLOSING
|
Dashboard, нагадування, авто-закриття за правилом. event_type="RECEIPT_FISCALIZED",
},
|
style="background:#eeeeee;" | Сірий
|
| Повернення створено
|
REFUNDED
|
-
|
Сірий
|
#eeeeee
|
Неактивно або скасовано. Тип
|
| Чеків за день
|
1240
|
інформаційні матеріали
|
| Фіскалізовано
|
1218
|
Норма
|
| Очікують у черзі
|
12
|
Увага
|
| Помилки фіскалізації
|
7
|
Критично
|
| Повернення
|
14
|
Контроль
|
| Незакриті зміни
|
2
|
Потрібна дія
|
"fiscal_number": response.fiscal_number,
"type": "card",
24.1. інтеграційні функції ERP20.1. Типи помилок"payment_id": "PAY-123456"
VCHASNO_KASA_RETRY_BACKOFF_SECONDS=5
| 10:42
|
Каса 1
|
ORDER-123
|
570.00
|
Помилка
|
Timeout API
|
Повторити
|
| 11:05
|
Каса 2
|
ORDER-124
|
1200.00
|
Потребує повтору
|
Тимчасова помилка
|
Повторити
|
| 12:10
|
Каса 3
|
SHIFT-55
|
-
|
Зміна відкрита
|
Не закрито Z-звіт
|
Закрити зміну
|
response = vchasno_kasa_client.create_receipt(payload)
validation_service.validate_receipt(command)
- зберігання токенів тільки у secret storage або в зашифрованому вигляді;
- заборону логування токенів;
- маскування персональних даних покупців;
- обмеження доступу до чеків;
- контроль доступу до повернень;
- окремі права на закриття зміни;
- журнал усіх дій;
- HTTPS для API-запитів;
- перевірку SSL;
- обмеження повторних запитів;
- захист від дублювання чеків. SEO-опис
shift = shift_service.ensure_open_shift(
receipt.fiscalized_at = datetime.now(timezone.utc)
2. Продаж / оплата / повернення
|
| }
receipt.status = "FISCALIZED"
платформа повинна підтримувати відкриття касової зміни.=== 7.4. Повторна обробка ===
)
from datetime import datetime, timezone
finally:
"amount": 570.00,
|
| Дублювання чеків
|
Повторний запит здатна створити другий чек. платформа повинна підтримувати закриття касової зміни та формування Z-звіту. Тип
POST /api/v1/fiscal/receipts/{receipt_id}/retry
"items": [
|
|
|
