Руководство по интеграции для тестирования удаленной подписи документов с помощью eSigner CSC API

Это руководство проведет вас через подписание хэша документа и файла PDF с помощью SSL.com. Электронная подпись облачная служба подписи и API Cloud Signature Consortium (CSC). Все примеры запросов API будут показаны с Почтальон, и мы рекомендуем установить Настольное приложение Postman на вашем компьютере, если вы хотите поработать с примерами. Также включены примеры команд cURL запросов API.

Создать тестовый заказ

1. Во-первых, вам нужно создать порядок подписи документов в песочнице. Начните с входа в свою учетную запись Sandbox и перейдите в Аккаунт меню.
   
2. Нажмите Средства для разработчиков.
   
3. Выберите Подпись документа eSigner, А затем нажмите Создать тестовый заказ .
   
4. Появится диалоговое окно. Щелкните значок OK .
   
5. Найдите свой тестовый заказ и щелкните значок подробнее ссылку.
   
6. Нажмите редактировать регистрант чтобы начать ввод информации о заявителе и получателе для вашего тестового заказа. Обратите внимание: поскольку эта информация не будет использоваться для выдачи действительного сертификата подписи документа, при желании вы можете ввести вымышленную информацию.
   
7. Добавьте информацию о заявителе для сертификата тестирования, затем нажмите кнопку Следующий >> .
   
8. Введите информацию о получателе, затем щелкните значок Следующий >> .
   
9. Нажмите Пропускать кнопку, чтобы пропустить загрузку проверочных документов для тестового сертификата.
   
10. Теперь ваш тестовый заказ должен иметь статус ожидание проверки. Свяжитесь со службой поддержки SSL.com по адресу Support@SSL.com чтобы ваш тестовый сертификат был подтвержден.
    

Зарегистрируйтесь в eSigner и настройте двухфакторную аутентификацию

1. После того, как ваш тестовый заказ будет проверен сотрудниками службы поддержки SSL.com, вы можете зарегистрировать его в eSigner. Перейдите к Заказы в своей учетной записи песочницы SSL.com и найдите свой тестовый заказ.
   
2. Нажмите на заказ подробнее ссылку.
   
3. Создайте и подтвердите 4-значный PIN-код, затем нажмите создать ПИН .
   
   Если вам нужно сбросить PIN-код eSigner, прочтите это как.
   
4. Появится QR-код.
   
   В следующий раз, когда вы перезагрузите страницу, QR-код не будет виден. Если вам нужно просмотреть или сбросить QR-код eSigner, прочтите это как.
   
5. Отсканируйте код в приложение для двухфакторной аутентификации на своем мобильном устройстве, например Google Authenticator или Authy. Приложение предоставит вам одноразовые пароли (OTP) для использования при подписании. Каждый OTP действителен в течение 2 секунд.
   

Установите Почтальон и импортировать коллекцию API CSC

1. Загрузите и разархивируйте Коллекция CSC API Postman (См. https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation для последних конечных точек API или загрузок коллекций).
   
2. Загрузите и установите Почтальон REST-клиент.
   
3. Запустите Postman, затем создайте новую учетную запись Postman или войдите в существующую.
   
4. Нажмите Импортировать .
   
5. Нажмите Загрузить файлы кнопку, перейдите к распакованному файлу коллекции API (CSC-API.postman_collection.json) и откройте его.
   
6. Нажмите Импортировать .
   
7. Нажмите Коллекции в Postman и разверните коллекцию API CSC, чтобы просмотреть пять запросов POST, с которыми вы будете работать:
   • Информация о CSC
   • Список учетных данных CSC
   • Информация об учетных данных CSC
   • Учетные данные Авторизовать
   • Подписать хеш

   

Получить токен доступа

1. Следующим шагом будет получение токена доступа с SSL.com. Прежде чем запросить токен доступа, вам понадобится идентификатор клиента (также известный как ID приложения, Пожалуйста, обратитесь к это как инструкции по созданию этих учетных данных).
2. Выберите Авторизация вкладка, выберите ОАут 2.0 из Тип меню и нажмите кнопку Получить новый токен доступа .
   
3. Введите следующую информацию в форму:
   • Название токена: SandBox CSC (или любое другое легко запоминающееся имя, которое вы предпочитаете)
   • Тип гранта: Код авторизации
   • URL обратного вызова: [оставьте поле пустым]
   • Авторизуйтесь с помощью браузера: проверил
   • URL авторизации: https://oauth-sandbox.ssl.com/oauth2/authorize
   • URL-адрес токена доступа: https://oauth-sandbox.ssl.com/oauth2/token
   • ID клиента: [Ваш идентификатор клиента]
   • Секрет клиента: [Секрет вашего клиента]
   • Объем: обслуживание
   • Район: [оставьте поле пустым]
   • Проверка подлинности клиента: Отправить как заголовок Basic Auth

   Когда вы закончите, щелкните Запросить токен .
   

4. В вашем браузере появится форма входа. Введите свое имя пользователя и пароль SSL.com, затем нажмите Логин участника .
   
5. Ваш новый токен доступа должен появиться в Postman. Выделите текст токена доступа и скопируйте его в буфер обмена, затем закройте Управление токенами доступа диалоговое окно. Вставьте свой токен доступа в текстовый редактор, чтобы вы могли легко получить к нему доступ. Срок действия каждого токена доступа истекает через час.
   
   Вы также можете сохранить свой токен для повторного использования в Почтальон запросов, но мы обнаружили, что наиболее надежно копировать и вставлять токен непосредственно в каждый запрос.
   

Подписать хеш

Теперь, когда у вас есть токен доступа, вы можете начать делать запросы API и создавать подписи. В этом разделе вы найдете пять доступных запросов в Коллекция Postman CSC, в результате чего на основе хэша документа создается цифровая подпись.

Получить информацию о CSC (необязательно)

1. Вы можете использовать Информация о CSC запрос на получение информации об облачном сервисе подписи SSL.com. Обратите внимание, что, в отличие от других в коллекции, этот запрос не требует вашего токена доступа. Чтобы отправить запрос, выберите Информация о CSC из API CSC коллекция, затем щелкните Отправить .
   
2. Информация об облачной службе подписи появится в объекте JSON в Postman's Режимы секции мощности поле.
   

Команда cURL

curl --location --request POST "https://cs-try.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}"

Список учетных данных CSC

1. Ассоциация Список учетных данных CSC request получит учетные данные, которые вы будете использовать в последующих запросах API. Выбрать Список учетных данных CSC И нажмите Авторизация меню.
   
2. Выберите Жетон на предъявителя из Тип меню, вставьте свой токен доступа в Токены поле, затем нажмите Отправить .
   
3. Объект JSON со списком идентификаторов учетных данных, связанных с пользователем, появится в Режимы секции мощности поле. Ваш список, вероятно, будет содержать одно значение. Скопируйте и вставьте свой идентификатор учетных данных в текстовый редактор для использования в последующих запросах.
   

Команда cURL

Замените MY-ACCESS-TOKEN с вашим фактическим токеном доступа:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Авторизация: носитель МОЙ-ДОСТУП-ТОКЕН "\ --data-raw" {} "

Если вы используете сертификат eseal (сертификат подписи документа, содержащий только информацию об организации; включен в вашу бесплатную учетную запись esigner.com), включите «clientData»: «DS_ESEAL» (примечание: eseal не требует OTP-аутентификации). Другие варианты для «clientData» - «EVCS» для подписи кода EV и «DS» (по умолчанию) для подписи документов IV или IV + OV:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Авторизация: носитель МОЙ-ДОСТУП-ТОКЕН "\ --data-raw" {\ "clientData \": \ "DS_ESEAL \"} "

Информация об учетных данных CSC (необязательно)

1. Ассоциация Информация об учетных данных CSC request вернет сертификаты и другую информацию, связанную с идентификатором учетных данных, и не требуется для подписи. Чтобы использовать этот запрос, выберите Информация об учетных данных CSC из коллекции и щелкните Авторизация меню.
   
2. Выберите Жетон на предъявителя из Тип меню, затем вставьте свой токен доступа в Токены поле.
   
3. Выберите Тело вкладка, затем вставьте свой идентификатор учетных данных в качестве значения для credentialID.
   
4. Нажмите Отправить .
   
5. Объект JSON с цепочкой сертификатов подписи и другой информацией появится в Режимы секции мощности поле.
   

Команда cURL

Замените MY-ACCESS-TOKEN и MY-CREDENTIAL-ID с вашей актуальной информацией:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "Авторизация: носитель MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "сертификаты \": \ "цепочка \", \ "certInfo \": true, \ "authInfo \": true} "

Учетные данные Авторизовать

1. Ассоциация Учетные данные Авторизовать request получит авторизацию для подписи хэша. Начните с выбора Учетные данные Авторизовать из коллекции и щелкнув Авторизация меню.
   
2. Выберите Жетон на предъявителя из Тип меню, затем вставьте свой токен доступа в Токены поле.
   
3. Выберите Тело таб. Вставьте свой идентификатор учетных данных как credentialID значение и хэш документа, который вы хотите подписать как hash значение. Получите и введите OTP из вашего приложения аутентификации и введите его в качестве значения для OTP, А затем нажмите Отправить .
   
4. Объект JSON с вашими данными активации подписи (SAD) появится в Режимы секции мощности поле. Скопируйте и вставьте это значение в текстовый редактор для использования в запросе подписи хэша.
   

Команда cURL

Замените MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHкачества MY-OTP с вашей актуальной информацией:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application / json" \ --header "Авторизация: носитель MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "numSignatures \": 1, \ "hash \": [\ "MY-HASH \ "], \" OTP \ ": \" MY-OTP \ "}"

Подписать хеш

1. Теперь мы готовы подписать хэш документа. Выбрать Подписать хеш из коллекции, затем выберите Авторизация меню.
   
2. Выберите Жетон на предъявителя из Тип меню, затем вставьте свой токен доступа в Токены поле.
   
3. Выберите Тело таб. Вставьте свой идентификатор учетных данных как credentialID значение, ваши данные активации подписи как SAD значение и хэш документа, который вы хотите подписать как hash значение, затем щелкните Отправить .
   
4. Объект JSON с вашей подписью появится в Режимы секции мощности поле.
   

Команда cURL

Замените MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADкачества MY-HASH с вашей актуальной информацией:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "Авторизация: носитель MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "SAD \": \ "MY-SAD \", \ "hash \": [\ "MY-HASH \"], \ "signAlgo \": \ "1.2.840.113549.1.1.11 \"} "

Подписать PDF

Помимо подписи хэшей документов, вы также можете загрузить и подписать файл PDF. Начните с загрузки и импорта Коллекция Postman API для подписи документов (См. https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation для последних конечных точек api и загрузок коллекций), следуя тому же этапы установки вы следовали выше для коллекции API CSC.

• Загрузить PDF-документ
• Подписать PDF-документ

Вы можете повторно использовать полученные вами учетные данные с Список учетных данных CSC запрос. Возможно, вам также понадобится получить новый маркер доступа.

Загрузить PDF-документ

1. Выберите Загрузить PDF-документ запрос и щелкните Авторизация меню.
   
2. Выберите Жетон на предъявителя из Тип меню, затем вставьте свой токен доступа в Токены поле.
   
3. Выберите Заголовки вкладка и вставьте свой идентификатор учетных данных в Значение колонка.
   
4. Выберите Тело вкладку и нажмите × рядом с hello.pdf чтобы удалить это имя-заполнитель.
   
5. Нажмите Выберите файл кнопку, затем перейдите к файлу, который хотите загрузить.
   
6. Нажмите Отправить .
   
7. Выберите и скопируйте id значение в ответе для использования в следующем запросе.
   

команда cURL

Замените MY-CREDENTIAL-ID, MY-ACCESS-TOKENкачества /PATH/TO/FILE.pdf с вашей актуальной информацией:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Авторизация: Bearer МОЙ-ДОСТУП-ТОКЕН "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

Примечание. Видимые подписи см. в следующих заголовках HTTP-запросов (/v1/pdf/upload):

Подписать PDF-документ

1. Теперь вы можете подписать PDF-файл. Выберите Загрузить PDF-документ запрос и щелкните Авторизация меню.
     
2. Выберите Жетон на предъявителя из Тип меню, затем вставьте свой токен доступа в Токены поле.
   
3. Выберите вкладку "Тело" и вставьте id значение из предыдущего шага.
   
4. Введите OTP из своего приложения аутентификации и нажмите Отправить .
   
5. Данные PDF появятся ниже в Режимы секции мощности поле. выберите Сохранить в файл из Сохранить ответ меню, затем дайте файлу имя.
   
6. Откройте файл в Acrobat, чтобы убедиться, что файл подписан. (Обратите внимание, что на снимке экрана ниже корень RSA Development SSL.com был вручную доверен в Acrobat.)
   

Команда cURL

Замените MY-CREDENTIAL-ID, MY-FILE-IDкачества MY-OTP с вашей актуальной информацией:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Content-Type : application / json "\ --header" Авторизация: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \", \ "otp \": \ "МОЙ-ОТП \"} "

 Начало работы с производством

Чтобы начать работу, вам нужно удалить «-try» из поддомена. Например, чтобы начать работу с ds-try.ssl.com, удалите «-try», чтобы субдомен стал ds.ssl.com.