prro-cloud System API

openapi: 3.2.0
info:
  title: prro-service System API
  description: 'REST API сервісу фіскалізації. Шляхи вказано від базової адреси.


    Каса — програмний реєстратор розрахункових операцій (ПРРО). Документ — будь-який документ, який сервіс надсилає до ДПС: чек, Z-звіт, документ зміни, документ офлайн-сесії. Чек — документ типу sale, return, storno, service_in або service_out.


    Автентифікація: Bearer JWT. Токен створюють у кабінеті. Цей документ не описує вхід у кабінет.'
  version: 0.9.0
tags:
- name: System
paths:
  /v1/version:
    get:
      operationId: getVersion
      summary: Версія збірки сервісу
      tags:
      - System
      responses:
        '200':
          description: Версія збірки.
          content:
            application/json:
              schema:
                type: object
                required:
                - version
                properties:
                  version:
                    description: 'Тег збірки: dev для локальної збірки, номер версії для релізу.'
                    type: string
                    examples:
                    - dev
                    - v0.3.0
  /v1/whoami:
    get:
      operationId: whoami
      summary: Клієнт і дозволи токена
      tags:
      - System
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Клієнт, дозволи (scopes) і каси токена.
          content:
            application/json:
              schema:
                type: object
                required:
                - client_id
                - scopes
                - jti
                - all_cash_registers
                properties:
                  client_id:
                    type: string
                    format: uuid
                    description: Клієнт, від імені якого діє токен.
                  scopes:
                    description: Дозволи токена.
                    type: array
                    items:
                      type: string
                  all_cash_registers:
                    type: boolean
                    description: 'true: токен необмежений, він діє на всі каси клієнта, поточні й майбутні. false: токен обмежений, він діє лише на каси з cash_registers.'
                  cash_registers:
                    type: array
                    description: Перелік uuid кас, на які діє обмежений токен. Поля немає, якщо all_cash_registers = true.
                    items:
                      type: string
                      format: uuid
                  jti:
                    type: string
                    format: uuid
                    description: Ідентифікатор токена. За цим ідентифікатором токен відкликають у кабінеті.
                  expires_at:
                    type: string
                    format: date-time
                    description: Час, коли строк дії токена закінчується. Поля немає, якщо токен безстроковий.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/system/dps:
    get:
      operationId: systemDPSStatus
      summary: Поточний режим роботи з ДПС (онлайн/офлайн)
      description: Режим, у якому сервіс працює з ДПС зараз. Маршрут доступний для будь-якого машинного токена.
      tags:
      - System
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Режим роботи з ДПС і телеметрія, яка пояснює цей режим.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DPSPulse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    DPSPulse:
      type: object
      description: Режим роботи з ДПС і телеметрія, яка пояснює цей режим. Сервіс працює з ДПС за значенням effective.
      required:
      - effective
      - verdict
      - since
      - latency_ms
      - samples
      - failures
      - tunables
      properties:
        effective:
          type: string
          enum:
          - online
          - offline
          description: Поточний режим роботи сервісу з ДПС.
        verdict:
          type: string
          enum:
          - online
          - degraded
          - offline
          description: Результат детектора. Значення degraded означає «повільно», offline — «недоступно».
        since:
          type: string
          format: date-time
          description: Час, з якого діє поточне значення effective.
        latency_ms:
          type: integer
          format: int64
          description: Затримка успішних запитів у вікні детектора, у мілісекундах. Значення 0 означає, що у вікні немає успішних запитів.
        samples:
          type: integer
          description: Кількість запитів у вікні детектора.
        failures:
          type: integer
          description: Кількість невдалих запитів у вікні детектора.
        last_ok_at:
          type: string
          format: date-time
          description: Час останньої успішної відповіді ДПС.
        last_probe_at:
          type: string
          format: date-time
          description: Час останньої перевірки доступності ДПС.
        tunables:
          type: object
          description: 'Пороги для значень вище: ширина вікна детектора, поріг degraded і інтервал перевірок.'
          required:
          - window_seconds
          - degraded_latency_ms
          - probe_interval_seconds
          properties:
            window_seconds:
              type: integer
              format: int64
              description: Ширина вікна детектора, у секундах.
            degraded_latency_ms:
              type: integer
              format: int64
              description: Затримка, від якої відповідь вважається повільною, у мілісекундах.
            probe_interval_seconds:
              type: integer
              format: int64
              description: Інтервал перевірок, у секундах.
    Error:
      description: 'Конверт помилки: машинний код, текст для людини і подробиці, якщо вони є.'
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          examples:
          - unauthorized
          - validation_failed
          description: Стабільний машинний код помилки. Програма клієнта обробляє помилку за цим кодом.
        message:
          type: string
          description: Текст для людини. Не використовуйте цей текст у логіці програми.
        details:
          description: 'Подробиці помилки, якщо вони є. Приклад: перелік полів, які не пройшли валідацію.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Машинний JWT із довгим строком дії. Токен створюють у кабінеті. Необмежений токен діє на всі каси клієнта, поточні й майбутні.


        Обмежений токен діє лише на каси зі свого переліку. Для інших кас операції з касою повертають 404, і сервіс не повідомляє, чи існує каса. Ресурси рівня клієнта (тарифікація, вебхуки) повертають 403.'