prro-cloud Billing API

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


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


    Автентифікація: Bearer JWT. Токен створюють у кабінеті. Цей документ не описує вхід у кабінет.'
  version: 0.9.0
tags:
- name: Billing
paths:
  /v1/billing/usage:
    get:
      operationId: billingUsage
      summary: Передплачений баланс і підсумок тарифікації за період
      description: 'Суми — копійки десятковим рядком. Типовий період — поточний календарний місяць за UTC. Дата `to` не входить у період. Для періоду понад 366 днів сервіс повертає 422.


        Сервіс тарифікує чеки асинхронно. Тому підсумок може не містити чеків за останні кілька секунд.'
      tags:
      - Billing
      security:
      - bearerAuth: []
      parameters:
      - name: from
        in: query
        schema:
          type: string
          format: date
        description: Початок періоду, дата за UTC. Дата входить у період. Типово — перше число поточного місяця.
      - name: to
        in: query
        schema:
          type: string
          format: date
        description: Кінець періоду. Дата не входить у період. Типово — перше число наступного місяця. Для періоду понад 366 днів сервіс повертає 422.
      responses:
        '200':
          description: Баланс і підсумок тарифікації за період.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingUsage'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/Error'
  /v1/invoices:
    get:
      operationId: listInvoices
      summary: Рахунки клієнта, від найновішого періоду
      description: Один рахунок відповідає одному розрахунковому періоду, а не одному платежу.
      tags:
      - Billing
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 200
          default: 50
        description: 'Кількість рахунків у відповіді: 1–200, типово 50.'
      - name: offset
        in: query
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Кількість рахунків, які сервіс пропускає. Параметр використовують для посторінкового читання.
      responses:
        '200':
          description: Рахунки клієнта.
          content:
            application/json:
              schema:
                type: object
                required:
                - invoices
                properties:
                  invoices:
                    description: Рахунки, від найновішого періоду.
                    type: array
                    items:
                      $ref: '#/components/schemas/Invoice'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/Error'
components:
  schemas:
    Money:
      type: string
      pattern: ^-?\d+(\.\d{1,4})?$
      description: Копійки, десятковий рядок (numeric(14,4)). Ніколи не число з рухомою комою.
    BillingUsage:
      description: Баланс і підсумок тарифікації за період.
      type: object
      required:
      - balance
      - soft_limit
      - blocked
      - period
      - receipts
      - charged
      - tariff
      properties:
        balance:
          $ref: '#/components/schemas/Money'
        soft_limit:
          allOf:
          - $ref: '#/components/schemas/Money'
          description: Поріг балансу. Поки balance < soft_limit, сервіс відхиляє чеки.
        blocked:
          type: boolean
          description: Сервіс зараз відхиляє чеки через баланс або за рішенням оператора.
        period:
          description: Період підсумку.
          type: object
          required:
          - from
          - to
          properties:
            from:
              type: string
              format: date
              description: Дата входить у період.
            to:
              type: string
              format: date
              description: Дата не входить у період.
        receipts:
          type: integer
          format: int64
          description: Кількість тарифікованих чеків за період.
        charged:
          $ref: '#/components/schemas/Money'
        tariff:
          description: Тариф, за яким сервіс тарифікував чеки.
          type: object
          required:
          - plan_id
          - price_per_receipt
          properties:
            plan_id:
              type: string
              format: uuid
              description: Ідентифікатор тарифного плану.
            price_per_receipt:
              $ref: '#/components/schemas/Money'
    Error:
      description: 'Конверт помилки: машинний код, текст для людини і подробиці, якщо вони є.'
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          examples:
          - unauthorized
          - validation_failed
          description: Стабільний машинний код помилки. Програма клієнта обробляє помилку за цим кодом.
        message:
          type: string
          description: Текст для людини. Не використовуйте цей текст у логіці програми.
        details:
          description: 'Подробиці помилки, якщо вони є. Приклад: перелік полів, які не пройшли валідацію.'
    Invoice:
      description: Рахунок за один розрахунковий період.
      type: object
      required:
      - id
      - period_start
      - period_end
      - amount
      - currency
      - status
      - created_at
      properties:
        id:
          type: string
          format: uuid
          description: Ідентифікатор рахунка.
        period_start:
          type: string
          format: date
          description: Дата входить у період.
        period_end:
          type: string
          format: date
          description: Дата входить у період.
        amount:
          $ref: '#/components/schemas/Money'
        currency:
          type: string
          description: 'Валюта рахунка за ISO 4217: UAH.'
        status:
          type: string
          enum:
          - draft
          - issued
          - paid
          - overdue
          description: '- `draft` — чернетка

            - `issued` — рахунок виставлено

            - `paid` — рахунок оплачено

            - `overdue` — рахунок прострочено'
        created_at:
          type: string
          format: date-time
          description: Час створення рахунка.
  responses:
    Error:
      description: Конверт помилки.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Токена немає, токен недійсний, строк дії токена закінчився або токен відкликано.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Машинний JWT із довгим строком дії. Токен створюють у кабінеті. Необмежений токен діє на всі каси клієнта, поточні й майбутні.


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