Продаж через касу

Огляд

Під час продажу маркованого товару (алкоголь, тютюнові вироби) в точці продажу акцизну марку потрібно перевірити перед додаванням у чек і заблокувати (погасити) одразу після фіскалізації. За це відповідає EDIN Акциз POS Service — API-шлюз для інтеграції касових систем (POS/РРО/ПРРО) з EDIN Акциз. На відміну від приймання, переміщення чи списання, цей процес не передбачає ручного сканування в EDIN Акциз Mobile — все відбувається через пряму інтеграцію каси з API.

Ключові можливості

• Перевірка марки в реальному часі (до 200 мс) у момент сканування товару в чек
• Пакетна перевірка всіх марок чека перед фіскалізацією
• Ручне введення readableCode (12 символів) для пошкоджених штрихкодів
• Автоматичне розгортання УГІ в окремі марки під час перевірки
• Асинхронне блокування марок після фіскалізації, ідемпотентне за receiptId

---

Схема інтеграції

Автентифікація: OAuth 2.0 Bearer token. Кожен запит обов’язково містить query-параметр ?tenant={tenantName}.

1. Касир сканує акцизну марку товару під час додавання в чек — POS викликає POST /validate (уточнюйте в команди розробки) з одним кодом (exciseCodes або readableCodes)
2. EDIN Акциз POS Service повертає overallValid і статус коду — POS додає товар у чек, якщо марка валідна
3. Перед фіскалізацією POS викликає POST /validate (уточнюйте в команди розробки) пакетно з усіма кодами чека
4. Каса фіскалізує чек через РРО/ПРРО
5. Одразу після фіскалізації POS викликає POST /block з receiptId, fiscalNumber, fiscalizationTimestamp та масивом exciseCodes
6. EDIN Акциз POS Service одразу повертає 202 Accepted — блокування марок виконується асинхронно у фоні

Діаграма процесу

sequenceDiagram
    actor Cashier as Касир
    participant POS as Каса (POS/РРО)
    participant EDINAktsyz as EDIN Акциз POS Service
    autonumber

    Cashier->>POS: Сканує акцизну марку товару
    POS->>EDINAktsyz: POST /validate (exciseCodes або readableCodes)
    EDINAktsyz-->>POS: overallValid + статус коду
    POS-->>Cashier: Товар додано в чек (якщо valid)

    Cashier->>POS: Завершує чек
    POS->>EDINAktsyz: POST /validate (пакет усіх кодів чека)
    EDINAktsyz-->>POS: overallValid (пакет)

    POS->>POS: Фіскалізує чек через РРО/ПРРО

    POS->>EDINAktsyz: POST /block (receiptId, fiscalNumber, exciseCodes)
    EDINAktsyz-->>POS: 202 Accepted
    EDINAktsyz-->>EDINAktsyz: Асинхронно блокує марки ("продано")

---

Найкращі практики

Валідація

1. Викликайте /validate одразу при скануванні марки в чек — не чекайте фіскалізації, щоб одразу відхилити невалідну марку
2. Виконуйте пакетну /validate перед фіскалізацією як фінальну перевірку всього чека
3. Використовуйте readableCodes лише як резервний спосіб при пошкодженому штрихкоді

Блокування

1. Викликайте /block одразу після успішної фіскалізації — не відкладайте виклик
2. Завжди передавайте унікальний receiptId — запит ідемпотентний, повторний виклик безпечний (at-least-once)
3. Якщо в чеку був код УГІ, передавайте в /block розгорнуті окремі марки, отримані з відповіді /validate, а не сам код УГІ