REP-58: add reporting (#5)

package.json

@@ -1,5 +1,5 @@
 {
-  "name": "RBKmoney-analyrics-api-spec",
+  "name": "RBKmoney-analytics-api-spec",
   "version": "0.0.1",
   "dependencies": {
     "bower": "^1.7.7",

spec/definitions/FileMeta.yaml

@@ -0,0 +1,32 @@
+type: object
+required:
+  - id
+  - filename
+properties:
+  id:
+    description: Идентификатор файла
+    type: string
+    maxLength: 40
+    minLength: 1
+  filename:
+    description: Имя файла
+    type: string
+    maxLength: 1000
+    minLength: 1
+  signatures:
+    type: object
+    description: Сигнатуры файла
+    required:
+      - md5
+      - sha256
+    properties:
+      md5:
+        description: MD5 содержимого файла
+        type: string
+        maxLength: 32
+        minLength: 32
+      sha256:
+        description: SHA256 содержимого файла
+        type: string
+        maxLength: 64
+        minLength: 64

spec/definitions/Report.yaml

@@ -0,0 +1,53 @@
+type: object
+required:
+  - id
+  - createdAt
+  - fromTime
+  - toTime
+  - status
+  - reportType
+  - partyID
+  - files
+properties:
+  id:
+    description: Идентификатор отчета
+    type: integer
+    format: int64
+  createdAt:
+    description: Дата и время создания
+    type: string
+    format: date-time
+  fromTime:
+    description: Дата и время начала периода
+    type: string
+    format: date-time
+  toTime:
+    description: Дата и время конца периода
+    type: string
+    format: date-time
+  status:
+    description: Статус формирования отчета
+    type: string
+    enum:
+      - pending
+      - created
+  reportType:
+    description: Тип отчета
+    type: string
+    enum:
+      - provisionOfService
+      - paymentRegistry
+  partyID:
+    description: Идентификатор участника
+    type: string
+    maxLength: 32
+    minLength: 32
+  shopID:
+    description: Идентификатор магазина
+    type: string
+    maxLength: 40
+    minLength: 1
+  files:
+    type: array
+    items:
+      $ref: '#/definitions/FileMeta'

spec/definitions/ReportLink.yaml

@@ -0,0 +1,7 @@
+type: object
+required:
+  - url
+properties:
+  url:
+    description: URL файла
+    type: string

spec/paths/reports.yaml

@@ -0,0 +1,92 @@
+post:
+  description: Сгенерировать отчет с указанным типом по магазину за указанный промежуток времени
+  tags:
+    - Reports
+  operationId: createReport
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/fromTime'
+    - $ref: '#/parameters/toTime'
+    - $ref: '#/parameters/reportType'
+    - $ref: '#/parameters/partyID'
+    - $ref: '#/parameters/shopID'
+  responses:
+    '201':
+      description: Отчет создан
+      schema:
+        $ref: '#/definitions/Report'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '400':
+      description: Ошибочные данные для генерации
+      schema:
+        type: object
+        required:
+          - code
+          - message
+        properties:
+          code:
+            description: |
+              [Код ошибки](#tag/Error-Codes)
+            type: string
+            enum:
+              - invalidShopID
+              - invalidRequest
+              - invalidDeadline
+          message:
+            description: Человекочитаемое описание ошибки
+            type: string
+            example: "Invalid shop id"
+
+get:
+  description: Получить список отчетов по данному магазину за период
+  tags:
+    - Reports
+  operationId: getReports
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/fromTime'
+    - $ref: '#/parameters/toTime'
+    - name: reportTypes
+      description: Типы отчетов
+      in: query
+      required: true
+      type: array
+      items:
+        type: string
+        enum:
+          - provisionOfService
+          - paymentRegistry
+    - $ref: '#/parameters/partyID'
+    - $ref: '#/parameters/shopID'
+  responses:
+    '200':
+      description: Найденные отчеты
+      schema:
+        type: array
+        items:
+          $ref: '#/definitions/Report'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '400':
+      description: Ошибочные данные для получения
+      schema:
+        type: object
+        required:
+          - code
+          - message
+        properties:
+          code:
+            description: |
+              [Код ошибки](#tag/Error-Codes)
+            type: string
+            enum:
+              - limitExceeded
+              - invalidRequest
+              - invalidDeadline
+          message:
+            description: Человекочитаемое описание ошибки
+            type: string
+            example: "Max limit: 1000"

spec/paths/reports@{reportID}.yaml

@@ -0,0 +1,22 @@
+get:
+  description: Получить отчет по данному идентификатору
+  tags:
+    - Reports
+  operationId: getReport
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/reportID'
+    - $ref: '#/parameters/partyID'
+    - $ref: '#/parameters/shopID'
+  responses:
+    '200':
+      description: Найденный отчет
+      schema:
+        $ref: '#/definitions/Report'
+    '404':
+      $ref: '#/responses/NotFound'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '400':
+      $ref: '#/responses/DefaultLogicError'

spec/paths/reports@{reportID}@files@{fileID}@download.yaml

@@ -0,0 +1,21 @@
+get:
+  description: Скачать файл
+  tags:
+    - Reports
+  operationId: downloadFile
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/deadline'
+    - $ref: '#/parameters/reportID'
+    - $ref: '#/parameters/fileID'
+  responses:
+    '200':
+      description: Download link
+      schema:
+        $ref: '#/definitions/ReportLink'
+    '404':
+      $ref: '#/responses/NotFound'
+    '401':
+      $ref: '#/responses/Unauthorized'
+    '400':
+      $ref: '#/responses/DefaultLogicError'

spec/swagger.yaml

@@ -256,6 +256,46 @@ parameters:
     type: string
     maxLength: 40
     minLength: 1
+  partyID:
+    name: partyID
+    in: query
+    description: Идентификатор участника
+    required: true
+    type: string
+    maxLength: 40
+    minLength: 1
+  shopID:
+    name: shopID
+    in: query
+    description: Идентификатор магазина
+    required: false
+    type: string
+    maxLength: 40
+    minLength: 1
+  reportType:
+    name: reportType
+    in: query
+    description: Тип отчета
+    required: true
+    type: string
+    enum:
+      - provisionOfService
+      - paymentRegistry
+  reportID:
+    name: reportID
+    in: path
+    description: Идентификатор отчета
+    required: true
+    type: integer
+    format: int64
+  fileID:
+    name: fileID
+    in: path
+    description: Идентификатор файла
+    required: true
+    type: string
+    maxLength: 40
+    minLength: 1
 tags:
   - name: Search
     x-displayName: Поиск
@@ -325,3 +365,12 @@ tags:
 
       Если вы получили ошибку, которой нет в данном описании, обратитесь в
       техническую поддержку.
+  - name: Reports
+    x-displayName: Отчеты
+    description: >
+      Один раз в отчетный период платформа автоматически подготавливает и
+      размещает документы в формате XLSX с разбиением по магазину активной
+      категории. Также, каждый документ будет подписан [квалифицированной
+      ЭЦП](http://minsvyaz.ru/ru/appeals/faq/31/). Данная подпись является
+      юридически значимой и позволяет полностью отказаться от бумажного
+      документооборота.