swag-claim-management/spec/swagger.yaml

swagger: '2.0'
info:
  version: 0.1.0
  title: RBKmoney Claim Management API
  description: |

    ## Описание

    RBKmoney Claim Management API служит для управления заявками. Любые сторонние
    приложения, включая наши веб-сайты и другие UI-интерфейсы являются внешними
    приложениями-клиентами.

    RBKmoney API работает поверх HTTP-протокола. Мы используем REST архитектуру,
    схема описывается в соответствии со [Swagger](http://swagger.io/). Коды
    возврата описываются соответствующими HTTP-статусами. Платформа принимает и
    возвращает JSON-структуры в HTTP body.

    ## Запросы

    Любой вызов методов API обязан предваряться предоставлением уникального для
    участника в пределах платформы ID запроса. Данный ID передается в
    соответствующем заголовке HTTP-запроса:

    ```
     X-Request-ID: oX5MWM2AQy
    ```

    ## Тип содержимого и кодировка

    Любой запрос к API должен выполняться в кодировке UTF-8 и с указанием
    содержимого в формате JSON

    ```
      Content-Type: application/json; charset=utf-8
    ```

    ## Формат дат

    Платформа принимает значения date-time в стандарте ISO 8601 с обязательным
    указанием UTC-оффсета, например:

    ```
      2017-01-01T00:00:00Z
      2017-01-01T00:00:01+00:00
    ```

    ## Максимальное время обработки запроса

    К любому вызову методов API можно добавить параметр отсечки по времени,
    определяющий максимальное время ожидания завершения операции по запросу.
    Данная отсечка передается в соответствующем заголовке HTTP-запроса:

    ```
     X-Request-Deadline: 10s
    ```

    Значение отсечки может быть задано в формате ISO 8601 (см. [Формат дат](#section/Format-dat)), либо
    в относительных величинах, например:

    `150000ms`, `540s`, `3.5m`
    При этом возможные единицы измерения `ms`, `s`, `m`.
    В обоих случаях  не рекомендуется, чтобы задаваемое значение было
    меньше **3 секунд** и превышало **1 минуту**.
  termsOfService: 'http://rbk.money/'
  contact:
    name: RBKmoney support team
    email: support@rbk.money
    url: 'https://rbk.money'
host: api.rbk.money
basePath: /claim-management/v0
schemes:
  - https
consumes:
  - application/json; charset=utf-8
produces:
  - application/json; charset=utf-8
securityDefinitions:
  bearer:
    type: apiKey
    name: Authorization
    in: header
    description: >
      Для аутентификации вызовов мы используем [JWT](https://jwt.io).
      Cоответствующий ключ передается в заголовке.

      ```shell
       Authorization: Bearer {TOKENIZATION|PRIVATE_JWT}
      ```      
security:
  - bearer: []
responses:
  NotFound:
    description: Заданный ресурс не найден
    schema:
      $ref: '#/definitions/GeneralError'
  Unauthorized:
    description: Ошибка авторизации
  DefaultLogicError:
    description: Неверные данные
    schema:
      $ref: '#/definitions/DefaultLogicError'
  GeneralError:
    description: Неверные данные
    schema:
      $ref: '#/definitions/GeneralError'
parameters:
  requestID:
    name: X-Request-ID
    in: header
    description: Уникальный идентификатор запроса к системе
    required: true
    type: string
    maxLength: 32
    minLength: 1
  partyID:
    name: partyID
    in: query
    description: Идентификатор участника
    required: true
    type: string
  claimID:
    name: claimID
    in: path
    description: Идентификатор заявки
    required: true
    type: integer
    format: int64
  claimRevision:
    name: claimRevision
    in: query
    description: Версия заявки
    required: true
    type: integer
    format: int32
  limit:
    name: limit
    in: query
    description: Лимит выборки
    required: true
    type: integer
    format: int32
    minimum: 1
    maximum: 1000
  deadline:
    name: X-Request-Deadline
    in: header
    description: Максимальное время обработки запроса
    required: false
    type: string
    maxLength: 40
    minLength: 1
  continuationToken:
    name: continuationToken
    in: query
    required: false
    description: >
      Токен, сигнализирующий о том, что в ответе передана только часть данных.

      Для получения следующей части нужно повторно обратиться к сервису, указав
      тот-же набор условий и полученый токен.

      Если токена нет, получена последняя часть данных.      
    type: string
tags:
  - name: Claims
    x-displayName: Заявки
    description: >
      Некоторая область данных может быть изменена только после премодерации на
      стороне платформы. Например, создание и активация новых магазинов,
      изменение финансовых данных вашего участника и т.п. требуют ручной
      проверки сотрудниками RBKmoney. Попытка изменить такие данные приводит к
      автоматическому созданию заявки на изменение данных. До тех пор, пока
      заявка не одобрена, вы можете добавлять изменения. После одобрения они
      будут применены к набору данных. В случае отказа по заявке данные
      останутся в неизменном состоянии. Ближайшим аналогом заявок можно
      представить Pull Request в распределенных системах контроля версий.