Task

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/prro-cloud/json-schema/prro-cloud-task-schema.json",
  "title": "Task",
  "description": "Завдання фіскального конвеєра. Кожен запит до ДПС сервіс виконує як завдання.",
  "x-generated": "2026-10-31",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/prro-cloud-openapi.yaml#/components/schemas/Task",
  "type": "object",
  "required": [
    "task_id",
    "type",
    "status",
    "created_at"
  ],
  "properties": {
    "task_id": {
      "type": "string",
      "format": "uuid",
      "description": "Ідентифікатор завдання. Статус завдання: GET /v1/tasks/{id}."
    },
    "type": {
      "type": "string",
      "enum": [
        "receipt",
        "open_shift",
        "close_shift",
        "close_offline_session",
        "abandon_offline_session",
        "verify_key",
        "sync_register",
        "dps_objects"
      ],
      "description": "Операція завдання:\n\n- `receipt` — чек\n- `open_shift` — відкриття зміни\n- `close_shift` — закриття зміни\n- `close_offline_session` — закриття офлайн-сесії\n- `abandon_offline_session` — відмова від офлайн-сесії, яку\n  відхиляє ДПС\n- `verify_key` — перевірка ключа КЕП\n- `sync_register` — звіряння каси з ДПС\n- `dps_objects` — запит господарських одиниць власника ключа"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "processing",
        "succeeded",
        "failed"
      ],
      "description": "- `pending` — завдання в черзі\n- `processing` — завдання виконується\n- `succeeded` — завдання завершилося успішно, дані в result\n- `failed` — завдання завершилося помилкою, дані в fault"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Час створення завдання."
    },
    "finished_at": {
      "type": "string",
      "format": "date-time",
      "description": "Час завершення завдання. Поля немає, поки завдання виконується."
    },
    "error": {
      "type": "string",
      "description": "Текст помилки завдання. Структурований опис цієї помилки — у полі fault."
    },
    "fault": {
      "$ref": "#/$defs/Fault"
    },
    "result": {
      "$ref": "#/$defs/TaskResult"
    }
  },
  "$defs": {
    "AbandonedDocument": {
      "type": "object",
      "description": "Документ офлайн-сесії, від якої відмовилися. Покупець отримав цей документ. Фіскального номера документа в ДПС немає.",
      "required": [
        "document_id",
        "class",
        "local_number",
        "created_at"
      ],
      "properties": {
        "document_id": {
          "type": "string",
          "format": "uuid",
          "description": "Ідентифікатор документа в журналі сервісу."
        },
        "task_id": {
          "type": "string",
          "format": "uuid",
          "description": "Завдання, яке створило документ."
        },
        "class": {
          "type": "string",
          "enum": [
            "check",
            "zreport",
            "open_shift",
            "close_shift",
            "offline_begin",
            "offline_end"
          ],
          "description": "Тип документа."
        },
        "kind": {
          "type": "string",
          "enum": [
            "sale",
            "return",
            "storno",
            "service_in",
            "service_out"
          ],
          "description": "Тип чека. Поле є лише для class = check."
        },
        "local_number": {
          "type": "integer",
          "format": "int64",
          "description": "Локальний номер документа."
        },
        "fiscal_number": {
          "type": "string",
          "description": "Офлайн-фіскальний номер, надрукований у документі."
        },
        "total": {
          "type": "string",
          "description": "Сума документа в гривнях. Поле є лише для чеків."
        },
        "pay_form": {
          "type": "string",
          "enum": [
            "cash",
            "cashless",
            "mixed"
          ],
          "description": "Форма оплати. Поле є лише для чеків."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Час створення документа."
        }
      }
    },
    "CashAmount": {
      "type": "string",
      "pattern": "^-?\\d+\\.\\d{2}$",
      "description": "Гривні з копійками, десятковий рядок. Формат той самий, що в сумах чека. Тип Money рахує копійки, його використовує лише тарифікація."
    },
    "DPSRegistrar": {
      "type": "object",
      "description": "Каса, зареєстрована в ДПС за господарською одиницею.",
      "required": [
        "fiscal_number",
        "local_number"
      ],
      "properties": {
        "fiscal_number": {
          "type": "string",
          "description": "Фіскальний номер каси, який присвоїла ДПС."
        },
        "local_number": {
          "type": "string",
          "description": "Локальний номер каси, який присвоїв власник."
        },
        "name": {
          "type": "string",
          "description": "Назва каси з реєстраційних даних ДПС."
        },
        "closed": {
          "type": "boolean",
          "description": "Касу скасовано в ДПС."
        }
      }
    },
    "DPSTaxObject": {
      "type": "object",
      "description": "Господарська одиниця власника ключа (dps_objects).",
      "required": [
        "name",
        "tin",
        "org_name",
        "registrars"
      ],
      "properties": {
        "name": {
          "type": "string",
          "description": "Назва господарської одиниці."
        },
        "address": {
          "type": "string",
          "description": "Адреса господарської одиниці."
        },
        "tin": {
          "type": "string",
          "description": "Податковий номер власника: ЄДРПОУ або РНОКПП."
        },
        "ipn": {
          "type": "string",
          "description": "Індивідуальний податковий номер платника ПДВ."
        },
        "org_name": {
          "type": "string",
          "description": "Назва суб'єкта господарювання."
        },
        "registrars": {
          "description": "Каси, зареєстровані в ДПС за цією господарською одиницею.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DPSRegistrar"
          }
        }
      }
    },
    "DocResult": {
      "description": "Документ, який створило завдання: номери в сервісі і в ДПС, посилання для покупця.",
      "type": "object",
      "required": [
        "document_id",
        "local_number",
        "fiscal_number",
        "register_fiscal_number"
      ],
      "properties": {
        "document_id": {
          "type": "string",
          "format": "uuid",
          "description": "Ідентифікатор документа в журналі сервісу."
        },
        "local_number": {
          "type": "integer",
          "description": "Наскрізний номер документа в межах каси (ORDERNUM)."
        },
        "fiscal_number": {
          "type": "string",
          "description": "Фіскальний номер документа, який присвоїла ДПС."
        },
        "register_fiscal_number": {
          "type": "string",
          "description": "Фіскальний номер каси, у якій сервіс створив документ. У чеку це «ФН ПРРО» (CASHREGISTERNUM). Це номер каси, а не документа. На відміну від fiscal_number, цей номер однаковий в онлайн-режимі і в офлайн-сесії. Поле є завжди."
        },
        "offline": {
          "type": "boolean",
          "description": "Сервіс підписав документ в офлайн-сесії. Сервіс обчислив фіскальний номер локально (<sid>.<n>.<crc>). ДПС отримає документ лише разом із пакетом офлайн-сесії."
        },
        "receipt_url": {
          "type": "string",
          "format": "uri",
          "description": "Копія чека для покупця на короткому домені сервісу\n(https://r.prro.cloud/<код>). Посилання надсилають покупцю або\nперетворюють на QR-код. Сторінка відкривається без авторизації:\nдоступ дає код у посиланні.\n\nФормат задає параметр запиту ?format=:\n\n- `html` (типовий) — сторінка чека\n- `png` — зображення чека шириною 576 px (стрічка 80 мм для\n  термопринтера) з QR-кодом\n- `qr` — PNG із QR-кодом адреси цієї сторінки\n\nПоле є лише в чеках. Посилання працює одразу, також в\nофлайн-сесії. Сторінка — копія чека, а не підтвердження\nфіскалізації. Підтвердження фіскалізації: fiscal_number і tax_url."
        },
        "tax_url": {
          "type": "string",
          "format": "uri",
          "description": "Цей документ в Електронному кабінеті платника податків ДПС. Це незалежне підтвердження фіскалізації. Поля немає, доки ДПС не отримала документ. До надсилання пакета офлайн-сесії офлайн-чек має лише фіскальний номер, який сервіс обчислив локально."
        },
        "original": {
          "$ref": "#/$defs/ReturnOriginal"
        },
        "totals": {
          "$ref": "#/$defs/ZReportTotals"
        }
      }
    },
    "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": "Автоматичні виправлення, які сервіс виконав під час завдання."
        }
      }
    },
    "KeyPasswordCheckResult": {
      "type": "object",
      "description": "Результат швидкої перевірки пароля контейнера. Сервіс лише розшифровує контейнер і не надсилає запитів у мережу.\n\nЗавдання завершується успішно і при ok = false, тому що перевірка дала результат. Якщо сталася внутрішня помилка, результату немає, і сервіс повторює завдання.",
      "required": [
        "signing_key_id",
        "ok"
      ],
      "properties": {
        "signing_key_id": {
          "type": "string",
          "format": "uuid",
          "description": "Ключ, пароль якого перевіряли."
        },
        "ok": {
          "type": "boolean",
          "description": "Пароль правильний: сервіс розшифрував контейнер."
        },
        "verify_code": {
          "type": "string",
          "description": "Код причини. Поле є завжди при ok = false. Приклад: wrong_password."
        },
        "verify_error": {
          "type": "string",
          "description": "Текст помилки бібліотеки підпису без змін."
        }
      }
    },
    "KeyVerificationResult": {
      "description": "Результат повної перевірки ключа КЕП: чи можна підписувати ключем документи каси і хто власник ключа.",
      "type": "object",
      "required": [
        "signing_key_id",
        "status",
        "prro_capable"
      ],
      "properties": {
        "signing_key_id": {
          "type": "string",
          "format": "uuid",
          "description": "Ключ, який перевіряли. Якщо deleted = true, ключа в сервісі вже немає."
        },
        "status": {
          "type": "string",
          "enum": [
            "active",
            "invalid"
          ],
          "description": "- `active` — ключ можна використовувати\n- `invalid` — сервіс відхилив ключ, причина в verify_code"
        },
        "verify_code": {
          "type": "string",
          "enum": [
            "wrong_password",
            "cert_not_found",
            "cert_expired",
            "not_prro",
            "verify_failed",
            "ca_unreachable"
          ],
          "description": "Причина відхилення. Ключ із причиною not_prro можна активувати через POST /cabinet/signing-keys/{id}/activate."
        },
        "verify_error": {
          "type": "string",
          "description": "Текст помилки перевірки без змін."
        },
        "key_type": {
          "type": "string",
          "enum": [
            "individual",
            "legal"
          ],
          "description": "Тип власника ключа за даними сертифіката."
        },
        "prro_capable": {
          "type": "boolean",
          "description": "Сертифікат дозволяє підписувати документи каси."
        },
        "cert_subject": {
          "type": "string",
          "description": "Поле subject сертифіката, як його записав АЦСК."
        },
        "org_name": {
          "type": "string",
          "description": "Назва суб'єкта господарювання або ім'я фізичної особи з сертифіката."
        },
        "edrpou": {
          "type": "string",
          "description": "ЄДРПОУ юридичної особи з сертифіката, лише цифри."
        },
        "drfo": {
          "type": "string",
          "description": "РНОКПП (ДРФО) фізичної особи з сертифіката, лише цифри."
        },
        "deleted": {
          "type": "boolean",
          "description": "Сервіс видалив ключ. Сервіс видаляє ключ за будь-якої причини відхилення, крім not_prro."
        }
      }
    },
    "OfflineAbandonResult": {
      "type": "object",
      "description": "Результат відмови від офлайн-сесії (abandon_offline_session).",
      "required": [
        "session_id",
        "dps_session_id",
        "held_documents",
        "abandoned",
        "closed"
      ],
      "properties": {
        "session_id": {
          "type": "string",
          "format": "uuid",
          "description": "Офлайн-сесія, від якої відмовилися."
        },
        "dps_session_id": {
          "type": "integer",
          "format": "int64",
          "description": "Номер офлайн-сесії, який присвоїла ДПС."
        },
        "held_documents": {
          "type": "integer",
          "format": "int64",
          "description": "Кількість документів сесії, які ДПС отримала. Ці документи залишаються зареєстрованими."
        },
        "abandoned": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/AbandonedDocument"
          },
          "description": "Документи сесії, яких ДПС не отримала."
        },
        "closure_session_id": {
          "type": "string",
          "format": "uuid",
          "description": "Офлайн-сесія, якою сервіс закриває в ДПС сесію, від якої відмовилися. Поля немає, якщо ДПС не отримала жодного документа сесії або ДПС уже закрила сесію сама."
        },
        "closed": {
          "type": "boolean",
          "description": "true: сесію закрито в ДПС, каса знову в онлайн-режимі. false: сервіс ще надсилає документ закриття сесії. Доти нові документи каси чекають у черзі."
        }
      }
    },
    "ReconcileReport": {
      "type": "object",
      "description": "Результат звіряння каси з ДПС (sync_register): дані ДПС і виправлення, які сервіс виконав у своїх даних.",
      "required": [
        "fiscal_number",
        "dps_shift_opened",
        "dps_next_local_number"
      ],
      "properties": {
        "fiscal_number": {
          "type": "string",
          "description": "Фіскальний номер каси, яку звіряли."
        },
        "dps_shift_opened": {
          "type": "boolean",
          "description": "Чи відкрита зміна каси за даними ДПС."
        },
        "dps_next_local_number": {
          "type": "integer",
          "format": "int64",
          "description": "Локальний номер, який ДПС очікує в наступному документі."
        },
        "dps_testing": {
          "type": "boolean",
          "description": "Чи тестова каса за даними ДПС."
        },
        "counter_old": {
          "type": "integer",
          "format": "int64",
          "description": "Лічильник локальних номерів сервісу до звіряння."
        },
        "counter_new": {
          "type": "integer",
          "format": "int64",
          "description": "Лічильник локальних номерів сервісу після звіряння."
        },
        "shift_adopted": {
          "type": "boolean",
          "description": "Сервіс прийняв як свою зміну, відкриту в ДПС."
        },
        "shift_abandoned": {
          "type": "boolean",
          "description": "Сервіс закрив у своїх даних зміну, якої в ДПС немає."
        },
        "offline_credentials_refreshed": {
          "type": "boolean",
          "description": "Сервіс оновив офлайн-ключі каси з даних ДПС."
        },
        "cash": {
          "type": "object",
          "description": "Рух готівки за поточну зміну: за даними сервісу (ours) і за даними ДПС (dps). Поле є лише тоді, коли зміна відкрита в ДПС.\n\nПоле довідкове. Сервіс не виправляє розбіжність.",
          "required": [
            "ours",
            "dps",
            "match"
          ],
          "properties": {
            "ours": {
              "$ref": "#/$defs/CashAmount"
            },
            "dps": {
              "$ref": "#/$defs/CashAmount"
            },
            "match": {
              "type": "boolean",
              "description": "Чи збігаються дані сервісу і дані ДПС."
            }
          }
        },
        "totals": {
          "type": "object",
          "description": "Підсумки поточної зміни за даними сервісу і за даними ДПС. Поле є лише тоді, коли зміна відкрита і в ДПС, і в сервісі.\n\nЯкщо підсумки не збігаються, сервіс надсилає Z-звіт зміни з підсумками ДПС. ДПС не приймає інших підсумків.",
          "required": [
            "ours",
            "match",
            "z_report_source"
          ],
          "properties": {
            "ours": {
              "$ref": "#/$defs/ShiftTotalsBrief"
            },
            "dps": {
              "$ref": "#/$defs/ShiftTotalsBrief",
              "description": "Поля немає, якщо ДПС не повернула підсумків."
            },
            "match": {
              "type": "boolean",
              "description": "Чи збігаються підсумки сервісу і підсумки ДПС."
            },
            "z_report_source": {
              "type": "string",
              "enum": [
                "local",
                "dps"
              ],
              "description": "Джерело підсумків для Z-звіту зміни."
            },
            "forced": {
              "type": "boolean",
              "description": "Це звіряння перевело Z-звіт зміни на підсумки ДПС."
            },
            "held": {
              "type": "string",
              "enum": [
                "dps_totals_unavailable",
                "shift_closing",
                "offline_backlog"
              ],
              "description": "Причина, з якої сервіс не звірив підсумки або не виправив\nрозбіжність:\n\n- `dps_totals_unavailable` — ДПС не повернула підсумків. У\n  цьому випадку match = false і поля dps немає.\n- `shift_closing` — сервіс уже надіслав Z-звіт зміни.\n- `offline_backlog` — сервіс ще не надіслав офлайн-документи\n  до ДПС."
            }
          }
        },
        "attention_cleared": {
          "type": "boolean",
          "description": "Сервіс зняв позначку auto_close_failing. Автоматичне закриття зміни знову працює."
        },
        "skipped": {
          "type": "string",
          "enum": [
            "offline_session"
          ],
          "description": "Причина, з якої сервіс не виконав звіряння. offline_session: сервіс не звіряє касу, коли офлайн-сесія відкрита."
        }
      }
    },
    "ReturnOriginal": {
      "description": "Початковий чек повернення. Поле є лише в чеку повернення.",
      "type": "object",
      "required": [
        "fiscal_number",
        "verified"
      ],
      "properties": {
        "fiscal_number": {
          "type": "string",
          "description": "Фіскальний номер початкового чека."
        },
        "document_id": {
          "type": "string",
          "format": "uuid",
          "description": "Початковий чек у журналі сервісу. Поля немає, якщо verified = false."
        },
        "verified": {
          "type": "boolean",
          "description": "true: сервіс створив початковий чек і перевірив повернення за залишком цього чека. false: початкового чека в сервісі немає, його створила інша каса. Сервіс прийняв повернення без перевірки."
        }
      }
    },
    "ShiftTotalsBrief": {
      "type": "object",
      "description": "Суми й кількості чеків зміни, за якими ДПС перевіряє Z-звіт.",
      "required": [
        "sales",
        "sales_count",
        "returns",
        "returns_count",
        "service_input",
        "service_output"
      ],
      "properties": {
        "sales": {
          "$ref": "#/$defs/CashAmount"
        },
        "sales_count": {
          "type": "integer",
          "description": "Кількість чеків продажу."
        },
        "returns": {
          "$ref": "#/$defs/CashAmount"
        },
        "returns_count": {
          "type": "integer",
          "description": "Кількість чеків повернення."
        },
        "service_input": {
          "$ref": "#/$defs/CashAmount"
        },
        "service_output": {
          "$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"
              }
            }
          }
        }
      }
    },
    "TaskResult": {
      "type": "object",
      "description": "Фіскальні поля (prro_id, shift_id, testing та інші) є в результаті завдань на чек, зміну та офлайн-сесію. Завдання verify_key повертає лише key_verification.",
      "properties": {
        "prro_id": {
          "type": "string",
          "format": "uuid",
          "description": "Каса, на якій сервіс виконав завдання."
        },
        "shift_id": {
          "type": "string",
          "format": "uuid",
          "description": "Зміна, у якій сервіс створив документи завдання."
        },
        "shift_number": {
          "type": "integer",
          "format": "int64",
          "description": "Наскрізний номер зміни в межах каси. Номер присвоює сервіс. ДПС не присвоює номерів змін, у квитанції ДПС цього поля немає."
        },
        "testing": {
          "type": "boolean",
          "description": "Документи завдання тестові: каса в тестовому режимі."
        },
        "receipt": {
          "$ref": "#/$defs/DocResult",
          "description": "Чек, який створило завдання receipt."
        },
        "shift_open": {
          "$ref": "#/$defs/DocResult",
          "description": "Документ відкриття зміни."
        },
        "zreport": {
          "$ref": "#/$defs/DocResult",
          "description": "Z-звіт, яким сервіс закрив зміну."
        },
        "shift_close": {
          "$ref": "#/$defs/DocResult",
          "description": "Документ закриття зміни."
        },
        "offline_end": {
          "$ref": "#/$defs/DocResult",
          "description": "Документ закриття офлайн-сесії."
        },
        "offline_abandon": {
          "$ref": "#/$defs/OfflineAbandonResult"
        },
        "key_verification": {
          "$ref": "#/$defs/KeyVerificationResult",
          "description": "Результат перевірки ключа КЕП. Це поле повертає завдання verify_key."
        },
        "key_password_check": {
          "$ref": "#/$defs/KeyPasswordCheckResult"
        },
        "reconcile": {
          "$ref": "#/$defs/ReconcileReport"
        },
        "dps_objects": {
          "description": "Господарські одиниці власника ключа. Це поле повертає завдання dps_objects.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/DPSTaxObject"
          }
        }
      }
   

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/prro-cloud/json-schema/prro-cloud-task-schema.json