Introduce invoice templates (#79)

* introduce invoice templates
* refactor authorization description
* clarify auth description for Invoices operations

spec/definitions/AccessToken.yaml

@@ -0,0 +1,7 @@
+type: object
+required:
+  - payload
+properties:
+  payload:
+    description: Содержимое токена для доступа к ресурсу.
+    type: string

spec/definitions/CostAmountRange.yaml

@@ -0,0 +1,15 @@
+type: object
+required:
+  - upperBound
+  - lowerBound
+properties:
+  upperBound:
+    description: Верхняя (включительная) граница стоимости товаров или услуг.
+    type: integer
+    format: int64
+    minimum: 1
+  lowerBound:
+    description: Нижняя (включительная) граница стоимости товаров или услуг.
+    type: integer
+    format: int64
+    minimum: 1

spec/definitions/Invoice.yaml

@@ -50,3 +50,6 @@ allOf:
         description: Описание предлагаемых товаров или услуг
         type: string
         maxLength: 1000
+      invoiceTemplateID:
+        description: Идентификатор шаблона (для инвойсов, созданных по шаблону).
+        type: string

spec/definitions/InvoiceAccessToken.yaml

@@ -1,8 +0,0 @@
-type: object
-required:
-  - payload
-properties:
-  payload:
-    description: |
-      Содержимое токена для доступа
-    type: string

spec/definitions/InvoiceAndToken.yaml

@@ -0,0 +1,9 @@
+type: object
+required:
+  - invoice
+  - invoiceAccessToken
+properties:
+  invoice:
+    $ref: '#/definitions/Invoice'
+  invoiceAccessToken:
+    $ref: '#/definitions/AccessToken'

spec/definitions/InvoiceParams.yaml

@@ -1,11 +1,11 @@
 type: object
 required:
   - shopID
-  - product
-  - dueDate
   - amount
   - currency
   - metadata
+  - dueDate
+  - product
 properties:
   shopID:
     description: Идентификатор магазина

spec/definitions/InvoiceParamsWithTemplate.yaml

@@ -0,0 +1,18 @@
+type: object
+properties:
+  amount:
+    description: |
+      Стоимость предлагаемых товаров или услуг, в минорных денежных единицах,
+      например в копейках в случае указания российских рублей в качестве валюты.
+    type: integer
+    format: int64
+    minimum: 1
+  currency:
+    description: |
+      Валюта, символьный код согласно
+      [ISO 4217](http://www.iso.org/iso/home/standards/currency_codes.htm).
+    type: string
+    pattern: '^[A-Z]{3}$'
+  metadata:
+    description: 'Метаданные, которые необходимо связать с инвойсом'
+    type: object

spec/definitions/InvoiceSearchResult.yaml

@@ -28,11 +28,8 @@ allOf:
         format: date-time
       amount:
         description: >
-          Стоимость предлагаемых товаров или услуг, в минорных денежных
+          Стоимость предлагаемых товаров или услуг, в минорных денежных единицах,
-          единицах,
+          например в копейках в случае указания российских рублей в качестве валюты.
-
-          например в копейках в случае указания российских рублей в качестве
-          валюты.
         type: integer
         format: int64
         minimum: 1

spec/definitions/InvoiceTemplate.yaml

@@ -0,0 +1,32 @@
+type: object
+required:
+  - id
+  - shopID
+  - product
+  - lifetime
+  - cost
+properties:
+  id:
+    description: Идентификатор шаблона инвойса
+    type: string
+  shopID:
+    description: Идентификатор магазина
+    type: string
+    maxLength: 40
+  product:
+    description: Наименование предлагаемых товаров или услуг
+    type: string
+    maxLength: 100
+  description:
+    description: Описание предлагаемых товаров или услуг
+    type: string
+    maxLength: 1000
+  lifetime:
+    $ref: '#/definitions/LifetimeInterval'
+  cost:
+    $ref: '#/definitions/InvoiceTemplateCost'
+  metadata:
+    description: >
+      Метаданные, которые будут связаны с инвойсом, созданным по шаблону, в
+      случае, если иные метаданные не указаны в запросе на создание инвойса.
+    type: object

spec/definitions/InvoiceTemplateAndToken.yaml

@@ -0,0 +1,9 @@
+type: object
+required:
+  - invoiceTemplate
+  - invoiceTemplateAccessToken
+properties:
+  invoiceTemplate:
+    $ref: '#/definitions/InvoiceTemplate'
+  invoiceTemplateAccessToken:
+    $ref: '#/definitions/AccessToken'

spec/definitions/InvoiceTemplateCost.yaml

@@ -0,0 +1,10 @@
+type: object
+discriminator: invoiceTemplateCostType
+description: |
+  Ограничения на стоимость товаров и услуг для инвойсов, генерируемых по
+  шаблону.
+required:
+  - invoiceTemplateCostType
+properties:
+  invoiceTemplateCostType:
+    type: string

spec/definitions/InvoiceTemplateCostFixed.yaml

@@ -0,0 +1,21 @@
+type: object
+allOf:
+  - $ref: '#/definitions/InvoiceTemplateCost'
+  - type: object
+    required:
+      - currency
+      - amount
+    properties:
+      currency:
+        description: |
+          Валюта, символьный код согласно
+          [ISO 4217](http://www.iso.org/iso/home/standards/currency_codes.htm).
+        type: string
+        pattern: '^[A-Z]{3}$'
+      amount:
+        description: |
+          Стоимость предлагаемых товаров или услуг, в минорных денежных единицах,
+          например в копейках в случае указания российских рублей в качестве валюты.
+        type: integer
+        format: int64
+        minimum: 1

spec/definitions/InvoiceTemplateCostRange.yaml

@@ -0,0 +1,16 @@
+type: object
+allOf:
+  - $ref: '#/definitions/InvoiceTemplateCost'
+  - type: object
+    required:
+      - currency
+      - range
+    properties:
+      currency:
+        description: |
+          Валюта, символьный код согласно
+          [ISO 4217](http://www.iso.org/iso/home/standards/currency_codes.htm).
+        type: string
+        pattern: '^[A-Z]{3}$'
+      range:
+        $ref: '#/definitions/CostAmountRange'

spec/definitions/InvoiceTemplateCostUnlim.yaml

@@ -0,0 +1,3 @@
+type: object
+allOf:
+  - $ref: '#/definitions/InvoiceTemplateCost'

spec/definitions/InvoiceTemplateCreateParams.yaml

@@ -0,0 +1,28 @@
+type: object
+required:
+  - shopID
+  - product
+  - lifetime
+  - cost
+properties:
+  shopID:
+    description: Идентификатор магазина
+    type: string
+    maxLength: 40
+  product:
+    description: Наименование предлагаемых товаров или услуг
+    type: string
+    maxLength: 100
+  description:
+    description: Описание предлагаемых товаров или услуг
+    type: string
+    maxLength: 1000
+  lifetime:
+    $ref: '#/definitions/LifetimeInterval'
+  cost:
+    $ref: '#/definitions/InvoiceTemplateCost'
+  metadata:
+    description: >
+      Метаданные, которые будут связаны с инвойсом, созданным по шаблону, в
+      случае, если иные метаданные не указаны в запросе на создание инвойса.
+    type: object

spec/definitions/InvoiceTemplateUpdateParams.yaml

@@ -0,0 +1,19 @@
+type: object
+properties:
+  product:
+    description: Наименование предлагаемых товаров или услуг
+    type: string
+    maxLength: 100
+  description:
+    description: Описание предлагаемых товаров или услуг
+    type: string
+    maxLength: 1000
+  lifetime:
+    $ref: '#/definitions/LifetimeInterval'
+  cost:
+    $ref: '#/definitions/InvoiceTemplateCost'
+  metadata:
+    description: >
+      Метаданные, которые будут связаны с инвойсом, созданным по шаблону, в
+      случае, если иные метаданные не указаны в запросе на создание инвойса.
+    type: object

spec/definitions/LifetimeInterval.yaml

@@ -0,0 +1,19 @@
+type: object
+description: Время жизни инвойса с момента его создания.
+required:
+  - days
+  - months
+  - years
+properties:
+  days:
+    type: integer
+    format: int32
+    minimum: 0
+  months:
+    type: integer
+    format: int32
+    minimum: 0
+  years:
+    type: integer
+    format: int32
+    minimum: 0

spec/paths/analytics@shops@{shopID}@invoices.yaml

@@ -95,7 +95,7 @@ get:
           result:
             type: array
             items:
-              $ref: '#/definitions/InvoiceSearchResult'
+              $ref: '#/definitions/Invoice'
     '400':
       $ref: '#/responses/BadRequest'
     '404':

spec/paths/processing@invoice-templates.yaml

@@ -0,0 +1,20 @@
+post:
+  description: Создать новый шаблон инвойса.
+  tags:
+    - InvoiceTemplates
+  operationId: createInvoiceTemplate
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - name: invoiceTemplateCreateParams
+      description: Параметры шаблона инвойса.
+      in: body
+      required: true
+      schema:
+        $ref: '#/definitions/InvoiceTemplateCreateParams'
+  responses:
+    '201':
+      description: Шаблон инвойса создан.
+      schema:
+        $ref: '#/definitions/InvoiceTemplateAndToken'
+    '400':
+      $ref: '#/responses/BadRequest'

spec/paths/processing@invoice-templates@{invoiceTemplateID}.yaml

@@ -0,0 +1,55 @@
+get:
+  description: Получить шаблон инвойса по его идентификатору.
+  tags:
+    - InvoiceTemplates
+  operationId: getInvoiceTemplateByID
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceTemplateID'
+  responses:
+    '200':
+      description: Шаблон инвойса
+      schema:
+        $ref: '#/definitions/InvoiceTemplate'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'
+put:
+  description: Модифицировать шаблон инвойса.
+  tags:
+    - InvoiceTemplates
+  operationId: updateInvoiceTemplate
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceTemplateID'
+    - name: invoiceTemplateUpdateParams
+      description: Параметры модифицируемого инвойса.
+      in: body
+      required: true
+      schema:
+        $ref: '#/definitions/InvoiceTemplateUpdateParams'
+  responses:
+    '200':
+      description: Шаблон инвойса модифицирован.
+      schema:
+        $ref: '#/definitions/InvoiceTemplate'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'
+delete:
+  description: Удалить шаблон инвойса.
+  tags:
+    - InvoiceTemplates
+  operationId: deleteInvoiceTemplate
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceTemplateID'
+  responses:
+    '204':
+      description: Шаблон инвойса удален.
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'

spec/paths/processing@invoice-templates@{invoiceTemplateID}@invoices.yaml

@@ -0,0 +1,23 @@
+post:
+  description: Создать новый инвойс по шаблону.
+  tags:
+    - InvoiceTemplates
+  operationId: createInvoiceWithTemplate
+  parameters:
+    - $ref: '#/parameters/requestID'
+    - $ref: '#/parameters/invoiceTemplateID'
+    - name: invoiceParamsWithTemplate
+      description: Параметры создаваемого инвойса
+      in: body
+      required: true
+      schema:
+          $ref: '#/definitions/InvoiceParamsWithTemplate'
+  responses:
+    '201':
+      description: Инвойс создан
+      schema:
+        $ref: '#/definitions/InvoiceAndToken'
+    '400':
+      $ref: '#/responses/BadRequest'
+    '404':
+      $ref: '#/responses/NotFound'

spec/paths/processing@invoices.yaml

@@ -15,6 +15,6 @@ post:
     '201':
       description: Инвойс создан
       schema:
-        $ref: '#/definitions/Invoice'
+        $ref: '#/definitions/InvoiceAndToken'
     '400':
       $ref: '#/responses/BadRequest'

spec/paths/processing@invoices@{invoiceID}@access_tokens.yaml

@@ -1,17 +1,6 @@
 post:
   operationId: createInvoiceAccessToken
-  description: |
+  description: Создать новый токен для доступа к указанному инвойсу.
-    Создать новый токен для доступа к указанному инвойсу.
-
-    С помощью этого токена можно авторизовать ограниченное количество операций,
-    необходимых для проведения платежей по указанному инвойсу, в частности:
-
-      * токенизация платёжных инструментов,
-      * создание платежей по этому и только этому инвойсу,
-      * получение состояния и событий этого инвойса.
-
-    Срок действия токена составляет 1 час от момента создания, после истечения
-    которого использовать его для авторизации операций будет более невозможно.
   tags:
     - Invoices
   parameters:
@@ -19,8 +8,8 @@ post:
     - $ref: '#/parameters/invoiceID'
   responses:
     '201':
-      description: Токен для доступа создан
+      description: Токен для доступа к инвойсу создан.
       schema:
-        $ref: '#/definitions/InvoiceAccessToken'
+        $ref: '#/definitions/AccessToken'
     '404':
       $ref: '#/responses/NotFound'

spec/swagger.yaml

@@ -67,20 +67,23 @@ securityDefinitions:
     name: Authorization
     in: header
     description: >
-      Для аутентификации вызовов мы используем [JWT](https://jwt.io). Ваш
+      Для аутентификации вызовов мы используем [JWT](https://jwt.io).
-      приватный ключ и ключ для токенизации вы можете получить в личном
+      Cоответствующий ключ передается в заголовке.
-      кабинете. Для аутентификации запросов соответствующий ключ передается в
-      заголовке.
 
       ```shell
        Authorization: Bearer {TOKENIZATION|PRIVATE_JWT}
       ```
 
-      Ключи не разделяются на тестовые и боевые, ваш приватный ключ открывает
+      Посмотреть ваш API-ключ вы можете в
+      [личном кабинете](https://dashboard.rbk.money/api/key).
+
+
+      Ключи не разделяются на тестовые и боевые, ваш API ключ открывает
       доступ ко всем функциям платформы. Для тестовых транзакций используйте ID
       тестовых магазинов.
 
-      Помните, что вы никому не должны передавать ваш приватный ключ!
+
+      Помните, что вы никому не должны передавать ваш API ключ!
 security:
   - bearer: []
 responses:
@@ -128,6 +131,13 @@ parameters:
     required: true
     type: string
     maxLength: 40
+  invoiceTemplateID:
+    name: invoiceTemplateID
+    in: path
+    description: Идентификатор шаблона инвойса
+    required: true
+    type: string
+    maxLength: 40
   paymentID:
     name: paymentID
     in: path
@@ -321,6 +331,66 @@ tags:
       отгрузке товара или предоставлении услуги плательщику, можно запросить у
       платформы все события, произошедшие в рамках указанного ID инвойса, либо
       самое последнее из них.
+
+      ## Authorization
+
+      Операции:
+
+      * создания инвойса,
+
+      * отмены ивнвойса,
+
+      * погашения инвойса,
+
+      * получения *нового* токена доступа к инвойсу (уже после создания инвойса)
+
+
+      авторизуются вашим API-ключем.
+
+      ### Токен доступа к инвойсу
+
+      Токен доступа к инвойсу авторизует ограниченное количество операций,
+      необходимых для проведения [платежей](#tag/Payments) по указанному
+      инвойсу, в частности:
+
+      * [токенизация](#tag/Tokens) платёжных инструментов,
+
+      * создание платежей по этому и только этому инвойсу,
+
+      * получение состояния и событий этого инвойса.
+
+
+      Срок действия токена составляет 1 час от момента создания, после истечения
+      которого использовать его для авторизации операций будет более невозможно.
+  - name: InvoiceTemplates
+    x-displayName: Шаблоны инвойсов
+    description: >
+      Шаблоны инвойсов позволяют упростить выставление инвойсов. Шаблон инвойса
+      привязан к конкретному магазину и содержит спецификацию, по которой можно
+      создавать инвойсы, указывая только конкретнyю стоимость товаров и услуг
+      и/или метаданные инвойса.
+      В случае, если шаблон содержит фиксированную стоимость, её также можно
+      опустить при создании инвойса. Если при создании инвойса по шаблону
+      не указать метаданные инвойса, они будут взяты из значения в шаблоне (если
+      шаблон содержит метаданные).
+
+
+      Cоздание, модификация и удаление шаблона инвойса не требуют верификации
+      на стороне платформы и заявок на эти изменения.
+
+      ## Authorization
+
+      Создание, модификация и удаление шаблона инвойса авторизуются вашим
+      API-ключем.
+
+      ### Токен доступа к шаблону инвойса
+
+      Токен доступа к шаблону инвойса создается в результате операции
+      создания шаблона. Он авторизует:
+
+      * получение шаблона инвойса по его идентификатору,
+
+      * создание инвойса по данному шаблону.
   - name: Accounts
     x-displayName: Счета
     description: >
@@ -357,11 +427,16 @@ tags:
 
       Платформа обеспечивает идемпотентность списания денег с платежного
       средства, предоставляя уникальный идентификатор платежной сессии. Данный
-      идентификатор предоставляется в процессе создания токена платежного
+      идентификатор предоставляется в процессе создания [токена платежного
-      средства и гарантирует идемпотентность запросов на списание средств,
+      средства](#tag/Tokens) и гарантирует идемпотентность запросов на списание
-      обеспечивая защиту от ошибочных повторных списаний.
+      средств, обеспечивая защиту от ошибочных повторных списаний.
+
+      ## Authorization
+
+      Запросы API платежей авторизуются либо токеном доступа к инвойсу,
+      по которому создан платеж, либо вашим API-ключем.
   - name: Tokens
-    x-displayName: Токены
+    x-displayName: Платежные токены
     description: >
       Платформа предоставляет вам возможность самостоятельно инициировать
       списание денег с платежных карт плательщиков и берет на себя процессы
@@ -377,13 +452,10 @@ tags:
       платежной карты, который в дальнейшем вы можете использовать для запуска
       платежей.
 
-      ## Платежная сессия
 
-      Платформа обеспечивает идемпотентность списания денег с платежного
+      В процессе создания токена предоставляется
-      средства, предоставляя уникальный идентификатор платежной сессии. Данный
+      [платежная сессия](#tag/Payments), обеспечивающая идемпотентность
-      идентификатор предоставляется в процессе создания токена платежного
+      списания денег с платежного средства.
-      средства и гарантирует идемпотентность запросов на списание средств,
-      обеспечивая защиту от ошибочных повторных списаний.
   - name: Categories
     x-displayName: Категории магазинов
     description: >
@@ -440,8 +512,8 @@ tags:
     x-displayName: Поиск
     description: >
       Для получения списка всех инвойсов/платежей указанного магазина необходимо
-      вызвать соответствующий метод платформы. Также имеется возможность
+      вызвать соответствующий метод платформы. Имеется возможность отфильтровать
-      отфильтровать выборку по определенным статусам инвойсов/платежей.
+      выборку по определенным статусам.
   - name: Analytics
     x-displayName: Аналитика
     description: >