.. _Integration_CryptoApi_CreatingSignature:

Формирование подписи
####################

| Запрос: ``POST /v2/sign``
| HTTP-заголовки:

.. code-block::

    Authorization: Bearer access_token
    Content-Type: application/json
    Accept: application/json

Тело запроса:

.. code-block:: JSON

    {
        "Thumbprint": "string",         // отпечаток сертификата
        "CertificateRawData": "base64", // данные сертификата в виде массива байт в Base64
        "ThrowOnErrors": true,          // признак того, что в случае ошибки нужно прервать выполнение запроса
        "Contents": [                   // коллекция данных на подписание
            "base64"
        ]
    }

Описание запроса
****************

Запрос позволяет сформировать ЭП для переданных данных с помощью заданного сертификата.

Сертификат для подписания либо задается отпечатком в поле ``Thumbprint``, либо в поле ``CertificateRawData`` передается массив байт сертификата в Base64.

Запрос позволяет сформировать несколько подписей за один раз. Данные на подписание передаются в коллекции ``Contents``.
Каждый элемент коллекции - это массив байт в Base64.

Поле ``ThrowOnErrors`` управляет поведением запроса в случае, если возникли ошибки при формировании одной из подписей.

Если поле установлено в ``true`` и хотя бы одна из подписей не была сформирована, то выполнение запроса прерывается 
и возвращается :ref:`HTTP-статус 400 (Bad Request) <Integration_Common_ApiHttpStatuses_BadRequest>` с сообщением об ошибке.

Если поле установлено в ``false``, то выполнение запроса не прерывается и Crypto API пытается сформировать подписи для оставшихся данных.

Ответ на запрос
***************

В случае успешного выполнения либо в случае значения ``false`` в поле ``ThrowOnErrors``, ответ на запрос содержит коллекцию результатов формирования подписей.

Порядок элементов в коллекции совпадает с порядком элементов в поле ``Contents`` запроса: первому элементу в ``Contents`` соответствует первый элемент в ответе.

Структура данных элемента коллекции представляет JSON вида:

.. code-block:: JSON

    {
        "Result": "base64",         // данные подписи в виде массива байт в Base64
        "ErrorMessage": "string"    // сообщение об ошибке при формировании подписи
    }

Данные подписи
==============

Если подпись была успешно сформирована, то в поле ``Result`` возвращаются данные подписи в виде массива байт в Base64.

Формат подписи зависит от настроек Продукта.
Если используется криптопровайдер на основе установленного на сервере `КриптоПро CSP <https://www.cryptopro.ru/products/csp>`_ и CSP использует настройки по умолчанию, то:

* если для формирования подписей используется :ref:`сервис CAdES <Setup_Integration_BasicSetup_Cryptography_CadesSettings>`, сформированная подпись будет улучшена до заданного типа;
* если для формирования подписей используется сервис по умолчанию, сформированная подпись будет в формате CAdES BES.

Если используется иной криптопровайдер, будет использован формат подписи, настроенный для выбранного криптопровайдера.
В любом случае подпись будет упакована в PKCS #7-контейнер.

Сообщение об ошибке
===================

Если подпись не была сформирована, то в поле ``ErrorMessage`` возвращается текст возникшей ошибки.