Конечная точка Operations

Управляет операциями, требующими подтверждения пользователем.

Получение списка операций

Параметр Значение
HTTP-метод GET
Путь /v1/operations?type=Type&opid=OpId
Аутентификация Аутентификация на ключе Kauth.
Параметры Type - тип операции, OpId - идентификатор операции, ClientId - идентификатор прикладной системы.
Возвращаемое значение Объект OperationsInfo, список операций для подтверждения.

Примечание Поля Type, OpId и ClientId в запросе могут быть не заданы, в этом случае сервис вернёт перечень всех операций, требующих подтверждения, для данного пользователя.

Параметр OpId имеет приоритет, если он задан, то будет возвращена операция с указанным в его значении идентификатором независимо от значения параметра Type или ClientId.

Запрос

GET /mydss/v1/operations?type=SecondaryAuthSignDocs HTTP/1.1
Host: teststand.cryptopro.ru

Ответ

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 17 May 2019 04:53:09 GMT

{
    "operations": [
        {
            "description": {
                "type": "SecondaryAuthSignDocs",
                "caption": "Подпись документов. Тип подписи: Пример для Сбербанка. Сертификат: Тестовый пользователь simdss."
            },
            "expiresAt": 1563171222,
            "documentCount": 1,
            "transactionId": "708a4546-5045-468e-89e9-6265f7363739",
            "parameters": null,
            "documents": [
                {
                    "id": "78544ff2-5a7b-4947-8025-6a3490d3253e",
                    "documentInfo": "test.txt",
                    "documentHash": "A988A71076FCC2809988073D69C7785E71C464491D426CAEFCC980823E485236",
                    "snippet": "<div><label>Название:</label><b>test.doc</b></div>",
                    "snippetHash": "693BE8DF00312EEE89CF0E5E608288B2C636DFF9DA965145226F8FE16DFB3689",
                    "fileSize": 2367,
                    "pageCount": 1
                }
            ]
        }
    ]
}

Получение сведений об операциях

Примечание

Метод доступен в версии 1.1 конечной точки /operations. Для версий DSS старше 2.0.3390 получение версий поддерживаемого сервисом API доступно через запрос OPTION на адрес https:////operations В ответе сервиса в заголовке api-supported-versions будет содержаться список поддерживаемых версий. Версии 2.0.3390 и более ранние на запрос OPTION на адрес https:////operations вернут ответ 404.

Параметр Значение
HTTP-метод GET
Путь /v1.1/operations/info?interval=Interval&opid=OpId
Аутентификация Аутентификация на ключе Kauth.
Параметры interval - интервал времени в секундах., OpId - идентификатор операции.
Возвращаемое значение Объект OperationsInfo, список операций для подтверждения.

Примечание

Поля Interval и OpId в запросе могут быть не заданы, в этом случае сервис вернёт перечень всех операций данного пользователя.

Параметр OpId имеет приоритет, если он задан, то будет возвращена операция с указанным в его значении идентификатором независимо от значения параметра Type.

Параметр Interval определяет интервал времени (в секундах) для поиска операций. Если параметр указан в запросе, то сервис вернёт все операции созданные после (Now - interval).

Ответ сервиса будет содержать список найденных операций пользователя. Если операции не были найдены, вернётся пустой список.

Каждый элемент списка содержит поле state, содержащий статус операции.

  • Completed - операция была завершена.
  • Expired - операция истекла.
  • Error - возникла ошибка при обработке операции.
  • Declined - операция отменена пользователем.
  • Cancelled - операция отменена Прикладной системой.

Так же возможны промежуточные статусы:

  • Challenged - для операции запрошено подтверждение
  • Created - операция создана, подтверждение ещё не было запрошено.
  • Running, Processing операция выполняется.

Статус Completed означает, что операция была подтверждена и обработана. Результат обработки каждого отдельного действия (документа) actions необходимо смотреть отдельно.

Запрос

GET /mydss/v1/operations/info HTTP/1.1
Host: hostname

Ответ

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "operations": [
        {
            "id": "ec5df8d5-9190-4f2d-a910-1e4a77083562",
            "type": "SignDocument",
            "description": "Описание операции (json)",
            "state": "Completed",
            "createdAt": 1603996634,
            "confirmedAt": 1603996684,
            "completedAt": 1603996685,
            "externalId": null,
            "actions": [
                {
                    "id": "9772a9b6-b621-4f05-91b6-919a0c4da3ac",
                    "documentId": "20097b0d-310d-452e-a9c4-653b13c6421f",
                    "originalDocumentId": null,
                    "status": "Approved",
                    "state": "Error",
                    "resultValue": null,
                    "error": "InternalError",
                    "errorDescription": "Описание ошибки..."
                },
                {
                    "id": "bf68d7f4-349b-45dc-91e0-2c0bfd2d745c",
                    "documentId": "22b41432-ca6a-46a8-a33c-1b7b9627ad6e",
                    "originalDocumentId": null,
                    "status": "Approved",
                    "state": "Executed",
                    "resultValue": "0f2942fb-05e2-41e3-883d-6db42ffaa2c0",
                    "error": null,
                    "errorDescription": null
                }
            ]
        }
    ]
}

Подтвердить/отклонить операцию

Отправка запроса на подтверждения выполнения операции.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/confirm
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект ApproveRequest, параметры подтверждения операции.
Возвращаемое значение Нет возвращаемого значения

Примечание

В поле confirmedDocuments структуры approvedOperation необходимо передать список подтверждённых документов. Если требуется подтвердить операцию, в которой не участвуют документы, то необходимо передать пустой список. В остальных случаях это поле не заполняется.

В поле declinedDocuments структуры approvedOperation необходимо передать список отклонённых документов. Если требуется отклонить операцию, в которой не участвуют документы, то необходимо передать пустой список. В остальных случаях это поле не заполняется.

Поля confirmedDocuments и declinedDocuments в структуре approvedOperation в запросе не могут быть оба пустыми или оба не заполнены (иметь значения null).

Запрос

POST /mydss/v1/operations/confirm HTTP/1.1
Host: teststand.cryptopro.ru
Content-Type: application/json
Content-Length: 327

{
    "approvedOperation": "{ \"id\": \"708a4546-5045-468e-89e9-6265f7363739\", \"timeStamp\": 12345, \"confirmedDocuments\": [ { \"id\": \"78544ff2-5a7b-4947-8025-6a3490d3253e\", \"documentHash\": \"A988A71076FCC2809988073D69C7785E71C464491D426CAEFCC980823E485236\", \"snippetHash\": \"56987632345678987654345678987654C636DFF9DA965145226F8FE16DFB3689\" }, { \"id\": \"5c37b048-bec1-47f9-b970-2639e1bcd472\", \"documentHash\": \"693BE8DF00312EEE89CF0E5E608288B2C636DFF9DA965145226F8FE16DFB3689\", \"snippetHash\": \"65298341094735617497501808ABCD79076F6D687D564CAEFCC980823E485236\" } ] }",
    "hmac": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
}

Ответ

HTTP/1.1 200 OK

Подпись документов

Отправка запроса на выполнение операции подписи на ключах хранимых в DSS.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/sign
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект ApprovedOperation, включающий идентификаторы подписываемых документов и параметры подписи, типа signTemplateId, certId и pinCode.
Возвращаемое значение Объект SignatureResult, результат подписи документов.

Запрос

POST /mydss/v1/operations/sign HTTP/1.1
Host: teststand.cryptopro.ru
Content-Type: application/json
Content-Length: 239

{
    "approvedOperation": {
        "confirmedDocuments": [
            {
                "id": "78544ff2-5a7b-4947-8025-6a3490d3253e",
                "documentHash": "A988A71076FCC2809988073D69C7785E71C464491D426CAEFCC980823E485236",
                "snippetHash": "693BE8DF00312EEE89CF0E5E608288B2C636DFF9DA965145226F8FE16DFB3689"
            }
        ],
        "parameters": {
            "signTemplateId": "1",
            "certId": "8350",
            "pinCode": ""
        }
    }
}

Ответ

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 17 May 2019 04:53:09 GMT

{
    "results": [
        {
            "refId": "5b581cee-7ce0-4da3-b144-1be44724155c",
            "originalRefId": "617f77c7-19c5-4353-a3c0-cf06e2da19da",
            "status": "Completed",
            "error": null,
            "errorDescription": null
        }
    ]
}

Подпись документов на клиентских ключах

Отправка запроса на выполнение операции подписи на ключах, хранимых в мобильном приложении.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/sign/ex
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект ApprovedOperation, включающий идентификаторы подписываемых документов и параметры подписи, типа signTemplateId, certId и pinCode.
Возвращаемое значение Объект Operation, операция для подтверждения.

Запрос

POST /mydss/v1/operations/sign/ex HTTP/1.1
Host: hostname
Content-Type: application/json
Content-Length: 239

{
    "ApprovedOperation": {
        "ConfirmedDocuments": [
            {
                "Id": "b64d7bf8-c82c-4e85-b91a-92f90a4ffb95"
            }
        ],
        "Parameters": {
            "signTemplateId": "1",
            "certId": "57232"
        }
    }
}

Ответ

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 17 May 2019 04:53:09 GMT

{
    "description": {
        "type": "SignDocument",
        "caption": "{\"values\": {\"dss\": \"%D0%9A%D1%80%D0%B8%D0%BF%D1%82%D0%BE%D0%9F%D1%80%D0%BE DSS\",\"date\": \"13.10.2021 17:37:48\",\"login\": \"xmv_self2\",\"certid\": \"57232\", \"sessionid\":\"zhmesyay\",\"optype\":\"%D0%9F%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C\" },\"keys\": {\"dss\": \"%D0%A1%D0%B5%D1%80%D0%B2%D0%B5%D1%80 %D0%AD%D0%9F\",\"date\": \"%D0%92%D1%80%D0%B5%D0%BC%D1%8F\",\"login\": \"%D0%9B%D0%BE%D0%B3%D0%B8%D0%BD %D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F\",\"certid\":\"%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80 %D1%81%D0%B5%D1%80%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%B0\",\"sessionid\":\"%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80 %D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0\",\"optype\":\"%D0%9E%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D1%8F\"}}"
    },
    "expiresAt": 1634136468,
    "documentCount": 1,
    "transactionId": "d349387e-ad2e-4966-964c-c517a3d8f4c3",
    "parameters": {
        "signatureType": "CAdES",
        "isDetached": "true"
    },
    "documents": [
        {
            "id": "b64d7bf8-c82c-4e85-b91a-92f90a4ffb95",
            "documentInfo": "signed_document",
            "documentHash": "1127C9C6F50AD4CA32740F03C7187EA1366187629060193FBA78E4B6CBF644C1",
            "snippet": "<html lang=\"ru\">\r\n  <head>\r\n    <meta charset=\"UTF-8\" />\r\n    <style>body{{font-family: -apple-system,BlinkMacSystemFont,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\",\"Segoe UI Symbol\"; padding: 16pt;}} @media (prefers-color-scheme: dark) {  body {    background: #484848; color:white; } }</style>\r\n  </head>\r\n  <body>\r\n    <p>%D0%98%D0%BC%D1%8F %D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0:</p>\r\n    <p>signed_document</p>\r\n  </body>\r\n</html>",
            "snippetHash": "66A0ACEED05DCB664EBF3174C625DC2E9AD94540F401C649C65ED6A3221588A7",
            "fileSize": 19232,
            "pageCount": 0,
            "isPrintableViewAvailable": false,
            "isSnippetViewAvailable": true,
            "isRawViewAvailable": false,
            "documentPreSignedHash": null,
            "xmlEncryptedKey": null,
            "documentPreDataId": null
        }
    ],
    "isClientSide": true,
    "isFullDocRequired": true,
    "certificateId": "57232"
}

Отправка запроса для подтверждения выполнения операции с клиентским ключом.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/confirm/ex
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект ApproveRequest, параметры подтверждения операции.
Возвращаемое значение Объект SignatureResult, результат подписи документов.

Запрос

POST /mydss/v1/operations/confirm/ex HTTP/1.1
Host: hostname
Content-Type: application/json
Content-Length: 327

{
    "ApprovedOperation": "{\"Id\":\"d349387e-ad2e-4966-964c-c517a3d8f4c3\",\"TimeStamp\":1634135869,\"Type\":\"SignDocument\",\"Caption\":\"{\\\"values\\\": {\\\"dss\\\": \\\"%D0%9A%D1%80%D0%B8%D0%BF%D1%82%D0%BE%D0%9F%D1%80%D0%BE DSS\\\",\\\"date\\\": \\\"13.10.2021 17:37:48\\\",\\\"login\\\": \\\"xmv_self2\\\",\\\"certid\\\": \\\"57232\\\", \\\"sessionid\\\":\\\"zhmesyay\\\",\\\"optype\\\":\\\"%D0%9F%D0%BE%D0%B4%D0%BF%D0%B8%D1%81%D1%8C\\\" },\\\"keys\\\": {\\\"dss\\\": \\\"%D0%A1%D0%B5%D1%80%D0%B2%D0%B5%D1%80 %D0%AD%D0%9F\\\",\\\"date\\\": \\\"%D0%92%D1%80%D0%B5%D0%BC%D1%8F\\\",\\\"login\\\": \\\"%D0%9B%D0%BE%D0%B3%D0%B8%D0%BD %D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F\\\",\\\"certid\\\":\\\"%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80 %D1%81%D0%B5%D1%80%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%B0\\\",\\\"sessionid\\\":\\\"%D0%98%D0%B4%D0%B5%D0%BD%D1%82%D0%B8%D1%84%D0%B8%D0%BA%D0%B0%D1%82%D0%BE%D1%80 %D0%B7%D0%B0%D0%BF%D1%80%D0%BE%D1%81%D0%B0\\\",\\\"optype\\\":\\\"%D0%9E%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D1%8F\\\"}}\",\"ConfirmedDocuments\":[{\"Id\":\"b64d7bf8-c82c-4e85-b91a-92f90a4ffb95\",\"Hash\":null,\"DocumentHash\":\"1127C9C6F50AD4CA32740F03C7187EA1366187629060193FBA78E4B6CBF644C1\",\"SnippetHash\":\"66A0ACEED05DCB664EBF3174C625DC2E9AD94540F401C649C65ED6A3221588A7\",\"SignedHash\":null,\"SignedDocId\":\"b78f55c1-6aa4-4879-98cd-92dffc1091a9\",\"DecryptedDocId\":null}],\"DeclinedDocuments\":[],\"Parameters\":null}",
    "Hmac": "cpGnGRxBCIp/IMMVzZ7z+FEFt8CVTSfO6LRMfeYf4ns="
}

**Ответ **

{
    "results": [
        {
            "refId": "da738a9f-df55-44d4-a773-7f4cb9dd3034",
            "originalRefId": "b64d7bf8-c82c-4e85-b91a-92f90a4ffb95",
            "status": "Completed",
            "error": null,
            "errorDescription": null,
            "originalContent": null
        }
    ]
}

Отправка запроса для подтверждения выполнения операции с клиентским ключом.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/dsk/commitment
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект DskSignCommitmentInput, параметры подтверждения владения ключом.
Возвращаемое значение Объект DskSignCommitmentOutput.

Пример запроса

POST https://hostname/Mdag/v1/operations/dsk/commitment
Authorization:  myDSS 22818299:RDvMrvWEW9EsnX4ruWTNqOfxgOrxvw6nPpm7m0FKdqg=:cWUIxu84H4YPaXrDUp8I6Ecw+w76+kDJTc+aS/NjTs0=

{
  "OpId": "b7f19ce4-c282-42ce-8e49-a1b8ba006a74",
  "Commitment": {
    "e805895e-66b9-4b33-919b-437e5e4204ac": "D02B2040FB59072F569F8F6910DF14A603874E660BE05429317139DB9FDBF392"
  }
}

Шаг протокола распределённой подписи.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/dsk/commitment2
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект DskSignCommitment2Input, параметры подтверждения владения ключом.
Возвращаемое значение Объект DskSignCommitment2Output.

Завершение протокола распределённой подписи.

Параметр Значение
HTTP-метод POST
Путь /v1/operations/dsk/ticket
Аутентификация Аутентификация на ключе Kauth.
Параметры Объект DskSignTicketInput, параметры подтверждения владения ключом.
Возвращаемое значение Объект DskSignTicketOutput.