CashRegisterState

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/prro-cloud/json-schema/prro-cloud-cash-register-state-schema.json",
  "title": "CashRegisterState",
  "description": "Поточний стан каси: режим, зміна, залишок готівки, офлайн-сесія.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/prro-cloud-openapi.yaml#/components/schemas/CashRegisterState",
  "type": "object",
  "required": [
    "id",
    "fiscal_number",
    "local_number",
    "mode",
    "state",
    "offline_limits"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Ідентифікатор каси в цьому API. Це те саме значення, що cash_register_id у запиті на чек."
    },
    "fiscal_number": {
      "type": "string",
      "description": "Фіскальний номер каси, який присвоїла ДПС. У чеку це «ФН ПРРО»."
    },
    "local_number": {
      "type": "string",
      "description": "CASHDESKNUM: номер каси, який присвоїв клієнт."
    },
    "mode": {
      "type": "string",
      "enum": [
        "production",
        "test"
      ],
      "description": "- `production` — фіскальний режим\n- `test` — тестовий режим, усі документи тестові\n\nДокументи зміни мають режим, у якому зміну відкрито. Змінити режим\nможна, лише коли зміну закрито."
    },
    "state": {
      "type": "string",
      "enum": [
        "closed",
        "opened",
        "offline"
      ],
      "description": "- `closed` — зміну закрито\n- `opened` — зміну відкрито\n- `offline` — офлайн-сесія відкрита"
    },
    "offline_ready": {
      "type": "boolean",
      "description": "Чи має каса офлайн-ключі від ДПС. ДПС надсилає офлайн-ключі разом із квитанцією на відкриття зміни."
    },
    "shift_mode": {
      "$ref": "#/$defs/ShiftMode"
    },
    "shift_close_times": {
      "$ref": "#/$defs/ShiftCloseTimes"
    },
    "cash_balance": {
      "$ref": "#/$defs/CashBalance"
    },
    "current_shift": {
      "description": "Поточна зміна каси. Поля немає після закриття зміни.",
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Ідентифікатор зміни."
        },
        "number": {
          "type": "integer",
          "format": "int64",
          "description": "Наскрізний номер зміни в межах каси («Зміна №147»). Номер присвоює сервіс. ДПС не присвоює номерів змін."
        },
        "status": {
          "type": "string",
          "enum": [
            "opening",
            "opened",
            "closing",
            "closed"
          ],
          "description": "- `opening` — відкриття зміни виконується\n- `opened` — зміну відкрито\n- `closing` — закриття зміни виконується\n- `closed` — зміну закрито"
        },
        "testing": {
          "type": "boolean",
          "description": "Зміну відкрито в тестовому режимі каси. Усі документи зміни тестові."
        },
        "opened_at": {
          "type": "string",
          "format": "date-time",
          "description": "Час відкриття зміни."
        },
        "documents": {
          "type": "integer",
          "description": "Кількість документів зміни всіх типів, не лише чеків. Поля немає, якщо сервіс не зміг підрахувати документи."
        }
      }
    },
    "shift_totals": {
      "$ref": "#/$defs/ShiftTotals"
    },
    "offline_session": {
      "type": "object",
      "description": "Поле є лише тоді, коли офлайн-сесія відкрита.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "Ідентифікатор офлайн-сесії в сервісі."
        },
        "dps_session_id": {
          "type": "integer",
          "format": "int64",
          "description": "Номер офлайн-сесії, який присвоїла ДПС. Номер входить у фіскальний номер офлайн-документа."
        },
        "started_at": {
          "type": "string",
          "format": "date-time",
          "description": "Час відкриття офлайн-сесії. Від цього часу сервіс рахує межу 36 годин."
        },
        "documents": {
          "type": "integer",
          "format": "int64",
          "description": "Кількість документів, які сервіс створив у цій офлайн-сесії."
        },
        "last_significant_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Час останнього документа, який продовжує офлайн-сесію. За цим часом сервіс рахує використаний місячний час."
        },
        "submit_paused_at": {
          "type": "string",
          "format": "date-time",
          "description": "Час, коли сервіс призупинив надсилання офлайн-пакетів, бо ДПС відхилила пакет. Поле є лише тоді, коли надсилання призупинено."
        },
        "submit_fault": {
          "allOf": [
            {
              "$ref": "#/$defs/Fault"
            }
          ],
          "description": "Помилка, з якою ДПС відхилила офлайн-пакет. Поле є лише тоді, коли надсилання призупинено."
        }
      }
    },
    "offline_limits": {
      "type": "object",
      "description": "Законодавчі межі офлайн-режиму в секундах: 36 годин на одну офлайн-сесію і 168 годин на календарний місяць. Використаний час рахують від offline_session.started_at або від restored_at, якщо він пізніший, і за offline_month_used_seconds.",
      "required": [
        "session_seconds",
        "month_seconds",
        "enforced"
      ],
      "properties": {
        "session_seconds": {
          "type": "integer",
          "format": "int64",
          "description": "Межа однієї офлайн-сесії, 36 годин у секундах."
        },
        "month_seconds": {
          "type": "integer",
          "format": "int64",
          "description": "Межа на календарний місяць, 168 годин у секундах."
        },
        "enforced": {
          "type": "boolean",
          "description": "Межі діють. Значення false: межі знято за пунктом 13 розділу «Прикінцеві положення» Закону № 265. Сервіс рахує час в офлайн-режимі, але не відхиляє документи через межі."
        },
        "restored_at": {
          "type": "string",
          "format": "date-time",
          "description": "Час, коли межі повернули після зняття. Сервіс рахує межі від цього часу, якщо він пізніший за початок офлайн-сесії або місяця. Поля немає, якщо межі не знімали."
        }
      }
    },
    "offline_month_used_seconds": {
      "type": "integer",
      "format": "int64",
      "description": "Час в офлайн-режимі за поточний календарний місяць, у секундах. Сервіс рахує місяць за київським часом."
    },
    "attention": {
      "type": "object",
      "description": "Поле є лише тоді, коли каса має позначку «потребує уваги». Зняти позначку: DELETE .../attention. Якщо надсилання офлайн-пакетів призупинено, відновіть його через POST .../offline-session/retry.",
      "required": [
        "reason"
      ],
      "properties": {
        "reason": {
          "description": "- `recurring_remediation` — сервіс виправляє розбіжності з ДПС\n  знову і знову\n- `offline_submission_paused` — надсилання офлайн-пакетів\n  призупинено\n- `auto_close_failing` — автоматичне закриття зміни\n  завершується помилкою",
          "type": "string",
          "enum": [
            "recurring_remediation",
            "offline_submission_paused",
            "auto_close_failing"
          ]
        },
        "since": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Час, коли сервіс поставив позначку."
        }
      }
    }
  },
  "$defs": {
    "CashAmount": {
      "type": "string",
      "pattern": "^-?\\d+\\.\\d{2}$",
      "description": "Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація."
    },
    "CashBalance": {
      "type": "object",
      "description": "Залишок готівки в касі. Це не фіскальне значення. Залишок готівки\nдорівнює нулю, коли касу створено. Залишок готівки враховує лише\nдокументи, які пройшли через цей сервіс.\n\nЗалишок готівки змінюють:\n\n- готівкові оплати: продаж додає суму, повернення віднімає суму,\n  сторно скасовує зміну від скасованого чека\n- службове внесення і службова видача\n\nБезготівкові оплати не змінюють залишок готівки. Сервіс бере `sum`\nоплати, решту вже враховано. Залишок готівки належить касі, а не\nзміні. Z-звіт не скидає залишок готівки.\n\nВід'ємне значення означає, що в касі було більше готівки, ніж\nзареєстрував сервіс. Встановити залишок готівки: PUT\n/v1/cash-registers/{id}/cash-balance.",
      "required": [
        "amount"
      ],
      "properties": {
        "amount": {
          "$ref": "#/$defs/CashAmount"
        },
        "as_of": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "Час останньої зміни залишку готівки. null: змін ще не було. Тоді нуль означає «немає даних», а не «каса порожня»."
        }
      }
    },
    "Fault": {
      "type": "object",
      "description": "Структурований опис помилки завдання. Мову message визначає заголовок\nAccept-Language. Типова мова — українська.\n\nПростори імен коду:\n\n- `dps.*` — помилка ДПС\n- `fiscal.*` — валідація документа\n- `return.*` — перевірка повернення за початковим чеком\n- `storno.*` — перевірка сторно за чеком, який сторно скасовує\n- `signer.*` — помилка КЕП\n- `state.*` — стан каси",
      "required": [
        "code",
        "class"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Стабільний ідентифікатор помилки. Приклад: dps.check_local_number_invalid."
        },
        "class": {
          "type": "string",
          "enum": [
            "resync",
            "config",
            "precursor",
            "user_action",
            "transient",
            "request",
            "internal"
          ],
          "description": "Дія, яка може виправити помилку:\n\n- `resync` — звірити стан каси з ДПС\n- `config` — виправити налаштування каси\n- `precursor` — виконати пропущений попередній крок\n- `user_action` — потрібне рішення людини\n- `transient` — тимчасова недоступність, повторіть запит\n- `request` — виправити запит\n- `internal` — внутрішня помилка сервісу"
        },
        "params": {
          "description": "Значення для підстановки в message.",
          "type": "object",
          "additionalProperties": true
        },
        "message": {
          "type": "string",
          "description": "Текст для людини з каталогу помилок, перекладений мовою з Accept-Language."
        },
        "upstream_message": {
          "type": "string",
          "description": "Текст помилки від ДПС без змін."
        },
        "remediation": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "local_number_synced",
              "shift_adopted",
              "shift_abandoned",
              "zreport_recovered",
              "zreport_autofiled",
              "register_config_filled"
            ]
          },
          "description": "Автоматичні виправлення, які сервіс виконав під час завдання."
        }
      }
    },
    "ShiftCloseTimes": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$"
      },
      "description": "Час щоденного закриття зміни за київським часом. Масив порожній лише тоді, коли shift_mode — `manual`. Час прив'язано до годинника, а не до часу відкриття зміни.\n\nМасив містить щонайменше два значення. Проміжок між сусідніми значеннями — не більше 20 годин, також через північ. Для `round_the_clock` — два або більше значень у порядку зростання. Для `working_hours` — рівно два значення: початок і кінець дня, у цьому порядку. Приклад вікна через північ: \"08:00\", потім \"02:00\"."
    },
    "ShiftMode": {
      "type": "string",
      "enum": [
        "manual",
        "round_the_clock",
        "working_hours"
      ],
      "description": "Як сервіс керує змінами каси:\n\n- `manual` — клієнт відкриває і закриває зміни сам.\n- `round_the_clock` — сервіс закриває зміну в кожен час із\n  shift_close_times. Наступний чек відкриває нову зміну.\n- `working_hours` — денне вікно між двома значеннями\n  shift_close_times.\n\n`round_the_clock` і `working_hours` — автоматичні режими змін. В\nавтоматичному режимі змін перший чек відкриває зміну."
    },
    "ShiftTotals": {
      "type": "object",
      "description": "Підсумки відкритої зміни на поточний момент. З цих сум сервіс створить Z-звіт під час закриття зміни. realiz — продажі, return — повернення.\n\nСкасовані чеки не входять у підсумки. Сервіс віднімає скасований чек із продажів або повернень. Службові внесення і службові видачі входять окремо: у service_in і service_out.\n\nСум за податками тут немає. Суми за податками є в підсумках Z-звіту (ZReportTotals) після закриття зміни.",
      "required": [
        "realiz",
        "return",
        "service_in",
        "service_out"
      ],
      "properties": {
        "realiz": {
          "$ref": "#/$defs/ShiftTotalsSide"
        },
        "return": {
          "$ref": "#/$defs/ShiftTotalsSide"
        },
        "service_in": {
          "$ref": "#/$defs/CashAmount"
        },
        "service_out": {
          "$ref": "#/$defs/CashAmount"
        }
      }
    },
    "ShiftTotalsSide": {
      "type": "object",
      "description": "Продажі або повернення: кількість чеків, сума і суми за формами оплати.",
      "required": [
        "count",
        "sum"
      ],
      "properties": {
        "count": {
          "type": "integer",
          "description": "Кількість чеків."
        },
        "sum": {
          "$ref": "#/$defs/CashAmount"
        },
        "pay_forms": {
          "type": "array",
          "description": "Суми за формами оплати. code і name — код і назва форми оплати, як у Z-звіті (PAYFORMCD і PAYFORMNM). Поля немає, якщо чеків немає.",
          "items": {
            "type": "object",
            "required": [
              "code",
              "name",
              "sum"
            ],
            "properties": {
              "code": {
                "type": "integer",
                "description": "PAYFORMCD: фіскальний код форми оплати."
              },
              "name": {
                "type": "string",
                "description": "PAYFORMNM: назва форми оплати, яку сервіс друкує."
              },
              "sum": {
                "$ref": "#/$defs/CashAmount"
              }
            }
          }
        }
      }
    }
  }
}