Това ръководство ще ви покаже как да регистрирате поръчка за сертификат за подписване на документи с SSL.com eSigner обслужват и използват API за облачен подпис на консорциума (CSC) за цифрово подписване на хеш на документ и PDF файл. Можете да използвате това ръководство и с двете къдрица or пощаджия. Препоръчваме на потребителите на Postman да инсталират настолни приложения, за работа с примерите. Примерите в това ръководство са приложими за производствени и тестови среди на SSL.com eSigner и eSealing. Разликите в командите между производствения и тестовия режим са обяснени в следващите раздели.
За да следвате тези инструкции, ще ви трябва:
- Валидирана поръчка за подписване на документ. Моля Прочети това как да за пълни инструкции за поръчка и валидиране.
- A Клиентски идентификационен номер (известен също като Идент. № на приложението. Моля, обърнете се към това как да за инструкции за генериране на тези идентификационни данни).
Поръчайте вашия SSL.com сертификат за подписване на документ
Как да поръчате сертификат в производствена среда
Моля, вижте тази статия с ръководство за инструкции как да поръчате удостоверение за подпис на производствен документ: Процес на поръчка за сертификати за подписване на кодове и документи
Как да поръчате тестов сертификат в Sandbox на SSL.com
SSL.com предлага специална Sandbox среда, отразяваща нашия жив SSL.com портал и SWS API, за безрисково експериментално пространство. Тази „лабораторна“ настройка позволява на потребителите да изследват и тестват услугите на SSL.com, без да се притесняват от причиняване на прекъсвания или реални разходи.
Статията, Използване на SSL.com Sandbox за тестване и интеграция, ще ви помогне да навигирате в процеса на създаване на акаунт в Sandbox, иницииране на тестова поръчка и интегриране на Sandbox с API на SWS.
След като създадете тестовия си сертификат, моля, свържете се с екипа за поддръжка на SSL.com, за да бъде валидиран. Можете да направите това, като щракнете върху бутона за онлайн чат в долния десен ъгъл на SSL.com уебсайт или изпращане на имейл до support@ssl.com.
Запишете се в eSigner и настройте двуфакторно удостоверяване
Преди да можете да започнете да използвате CSC API, ще трябва да се регистрирате в услугата за подписване в облак eSigner на SSL.com. Валидираните поръчки могат да бъдат регистрирани в eSigner, като следвате инструкциите по-долу:
- . Придвижете се до Поръчки в своя акаунт в SSL.com и намерете вашата поръчка.
- Щракнете върху поръчките детайли връзка.
- Създайте и потвърдете 4-цифрен ПИН, след което щракнете върху създайте ПИН бутон.
Ако трябва да нулирате своя eSigner ПИН, моля, прочетете това как да.
- Ще се появи QR код.
Следващият път, когато презаредите страницата, QR кодът няма да се вижда. Ако трябва да прегледате или нулирате своя QR код на eSigner, моля, прочетете това как да.
- Сканирайте кода в 2-факторно приложение за удостоверяване на вашето мобилно устройство, като например Google Authenticator or Authy. Приложението ще ви предостави еднократни пароли (OTP), които да използвате при подписване. Всеки OTP е валиден за 30 секунди.
По избор: Преобразувайте вашия сертификат за подписване на OV документ в сертификат за повторно запечатване
Забележка: Този раздел е само за потребители, които искат да направят повторно запечатване. За да автоматизират подписването на документи и да не бъдат подканвани от еднократни пароли (OTP), потребителите сами преобразуват своя сертификат за подписване на документ за проверка на организацията (OV) в сертификат за повторно запечатване на техните акаунти в SSL.com. Обърнете внимание, че сертификатът за подписване на документ за индивидуална проверка (IV) не може да бъде конвертиран за повторно запечатване. Инструкциите за повторно запечатване са дадени подробно по-долу:
- Кликнете Поръчки в горното меню на вашия акаунт в SSL.com.
- Намерете вашия сертификат и щракнете върху Свали / подробности връзка.
- Щракнете върху ПРЕМАХНЕТЕ 2FA бутон.
Инсталирайте колекциите на Postman и Import API
Инструкциите в този раздел са само за потребители на пощальон. Ако използвате cURL с CSC API, можете да преминете към следващия раздел.
- Изтеглете и разархивирайте Колекция CSC API Postman намлява API за подписване на документи Колекция пощальон (Вж. https://www.postman.com/sslcom за онлайн колекции API на SSL.com).
- Изтеглете и инсталирайте Пощальон REST клиент.
- Стартирайте Postman, след това създайте нов акаунт в Postman или влезте в съществуващ.
- Щракнете върху внос бутон.
- Щракнете върху Качване на файлове , отидете до разархивираните файлове за събиране на API (
csc-api-prod.postman_collection.jsonнамляваdocument-signing-api-prod.postman_collection.json) и ги отворете.
- Щракнете върху внос бутон.
- Заявките за API, с които ще работите, вече са налични в колекции в лявата част на прозореца на пощальона.
Изтеглете токена за достъп
Следващата стъпка е да извлечете токен за достъп от SSL.com. Ще ви трябват вашите Клиентски идентификационен номер налични, както и потребителското име и паролата за вашия SSL.com акаунт. Токените за достъп са валидни един час след издаването им.
Използвайте разделите за кликване по-долу, за да изберете инструкции за пощальон или curL:
- Изберете заявка за API от колекцията на CSC API.
- Изберете Упълномощаване И изберете OAuth 2.0 от Тип меню.
- Въведете следната информация във формуляра:
- Префикс на заглавката:
Bearer - Име на токена:
SSLCOM CSC(или друго лесно за запомняне име, което предпочитате) - Тип безвъзмездна помощ:
Authorization Code - URL адрес за обратно извикване:
https://upload.esigner.com - Оторизирайте с помощта на браузър: непроверен
- URL за удостоверяване:
https://login.ssl.com/oauth2/authorizeза производствена среда;https://oauth-sandbox.ssl.com/oauth2/authorizeза Sandbox среда. - URL за достъп до маркера:
https://login.ssl.com/oauth2/tokenза производствена среда;https://oauth-sandbox.ssl.com/oauth2/tokenза Sandbox среда. - Идент. № на клиента: [Вашият клиентски идентификатор]
- Клиентска тайна: [Вашата клиентска тайна]
- Обхват:
service - членка: [остави празно]
- Клиентско удостоверяване:
Send as Basic Auth header
Когато приключите, щракнете върху Вземете нов маркер за достъп бутон.
- Префикс на заглавката:
- Ще се появи формуляр за вход. Въведете вашето потребителско име и парола за SSL.com, след което щракнете върху Вход бутон.
- Новият ви маркер за достъп трябва да се появи в Postman. Изберете текста на маркера за достъп и го копирайте в клипборда, след което затворете Управление на маркерите за достъп диалогов прозорец. Поставете маркера си за достъп в текстов редактор, където можете лесно да го осъществите. Всеки маркер за достъп ще изтече след един час.
Можете също така да запазите маркера си за повторна употреба в исканията на Postman, но установихме, че е най-надеждно да копирате и поставите маркера директно във всяка заявка.
- Използвайте следната команда, за да поискате маркер за достъп. Заменете стойностите, показани в ALL-CAPS, с вашите действителни стойности:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "ВАШИЯ -CLIENT-ID", "client_secret" : "ВАШАТА-CLIENT-SECRET", "grant_type" : "парола", "username" : "ВАШЕТО-ПОТРЕБИТЕЛСКО ИМЕ", "password" : "ВАШАТА-PASSWORD" }' - Трябва да получите JSON обект, съдържащ маркер за достъп и маркер за опресняване. Копирайте стойността на маркера за достъп, за да го поставите във вашите заявки за API. Няма да ви е необходим маркер за опресняване за тези примери.
Подпишете хеш
След като вече имате токен за достъп, можете да започнете да правите заявки за API и да създавате подписи. Този раздел ще ви преведе през петте налични заявки в колекцията на Postman CSC, в резултат на което ще се създаде цифров подпис от хеш на документ.
- Необходима е PDF библиотека за манипулиране на PDF за въвеждане на хеш и по-късно вграждане на PKCS#7 в PDF документа. (напр. ApachePDFBox в Java).
- Крипто библиотека за създаване на PKCS#7 от необработени подписи, получени от API на eSigner (напр. BouncyCastle в Java).
Вземете информация за CSC (по избор)
- Можете да използвате Информация за CSC заявка за получаване на информация за услугата за подписване в облак на SSL.com. Имайте предвид, че за разлика от останалите в колекцията, тази заявка не изисква вашия маркер за достъп. За да изпратите заявката, изберете Информация за CSC от API на CSC колекция, след това щракнете върху Изпрати бутон.
- Информацията за услугата за подпис в облака ще се появи в обект JSON в Postman's Отговор поле.
- Използвайте следната команда, за да получите информация за CSC API услугата на SSL.com. Ако сте в пясъчна среда, използвайте
https://cs-try.ssl.com/csc/v0/infoвместо.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Тип съдържание: application / json" \ --data-raw "{}" - Ще получите JSON обект с подробности за услугата:
Списък с идентификационни данни на CSC
- Списък с идентификационни данни на CSC заявка ще извлече идентификационни данни, които ще използвате в по-късните заявки за API.
- Изберете Списък с идентификационни данни на CSC и кликнете върху Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, поставете маркера за достъп в Жетон след това щракнете върху Изпрати бутон.
- JSON обект със списък с идентификационни данни за идентификационни данни, свързани с потребителя, ще се появи в Отговор поле. Списъкът ви вероятно ще съдържа една стойност. Копирайте и поставете идентификационния си идентификационен номер в текстов редактор за използване при по-късни заявки.
- Въведете следната команда. (Заменете MY-ACCESS-TOKEN с действителния си маркер за достъп). Ако сте в пясъчна среда, използвайте
https://cs-try.ssl.com/csc/v0/credentials/listвместо:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Разрешение: Приносител MY- ДОСТЪП-МЕРКА "\ - необработени данни" {} "Ако използвате сертификат eseal (сертификат за подписване на документи само с информация за организацията; включен във вашия безплатен акаунт в esigner.com), включете „clientData“: „DS_ESEAL“ (забележка: eseals не изисква OTP удостоверяване). Други опции за „clientData“ са „EVCS“ за подписване на EV код и „DS“ (по подразбиране) за IV или IV+OV подписване на документи:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Упълномощаване: Носител MY- ДОСТЪП-ТОКЕН" \ --data-raw '{"clientData": "DS_ESEAL"}' - Трябва да получите JSON обект със списък с идентификационни данни за идентификационни данни, свързани с потребителя. Списъкът ви вероятно ще съдържа една стойност. Копирайте и поставете идентификационния си идентификационен номер в текстов редактор за използване при по-късни заявки.
Информация за идентификационните данни на CSC (по избор)
- CSC идентификационни данни Информация заявката ще върне сертификати и друга информация, свързана с идентификационен номер на идентификационните данни, и не е необходима за подписване.
- За да използвате тази заявка, изберете CSC идентификационни данни Информация от колекцията и щракнете върху Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, след това поставете маркера за достъп в Жетон поле.
- Изберете Body раздела, след това поставете идентификационния си номер като стойност за
credentialID.
- Щракнете върху Изпрати бутон.
- JSON обект с вашата верига за подписване на сертификати и друга информация ще се появи в Отговор поле.
- Въведете следната команда. Ако сте в средата на пясъчника, използвайте
https://cs-try.ssl.com/csc/v0/credentials/infoСменетеMY-ACCESS-TOKENнамляваMY-CREDENTIAL-IDс вашата действителна информация:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Упълномощаване: Носител MY- ДОСТЪП-ТОКЕН" \ --data-raw '{ "credentialID": "МОЯТ-КРЕДЕНЦИАЛ-ИД", "сертификати": "верига", "certInfo": истина, "authInfo": истина }' - Трябва да получите JSON обект с вашата верига за подписване на сертификати и друга информация:
Удостоверения за пълномощия
- Удостоверения за пълномощия заявката ще извлече разрешение за подписване на хеш.
- Започнете, като изберете Удостоверения за пълномощия от колекцията и щракване върху Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, след това поставете маркера за достъп в Жетон поле.
- Изберете Body раздел. Поставете идентификационния си номер като
credentialIDстойност и хеш на документа, който искате да подпишете катоhashстойност. Изтеглете и въведете OTP от приложението си за удостоверяване и го въведете като стойност заOTP, след което кликнете върху Изпрати бутон. Забележка: OTP не се изисква за запечатване на сертификати.
- JSON обект с вашите данни за активиране на подпис (SAD) ще се появи в Отговор поле. Копирайте и поставете тази стойност в текстов редактор за използване в заявката за подписване на хеш.
- Използвайте следната команда. Сменете
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID, иMY-HASHс вашата действителна информация. Вземете еднократна парола от вашето приложение 2FA и използването е като стойност заMY-OTP. Забележка: OTP не се изисква за запечатване на сертификати.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Упълномощаване: Носител MY- ДОСТЪП-ТОКЕН" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}' - Трябва да получите JSON обект с вашите данни за активиране на подпис (SAD). Копирайте и поставете тази стойност в текстов редактор за използване в заявката за подписване на хеш.
Подпишете хеш
Сега сте готови да подпишете хеша на документа.
- Изберете Подпишете хеш от колекцията, след което изберете Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, след това поставете маркера за достъп в Жетон поле.
- Изберете Body раздел. Поставете идентификационния си номер като
credentialIDстойност, вашите данни за активиране на подпис катоSADстойност и хеш на документа, който искате да подпишете катоhashстойност, след което щракнете върху Изпрати бутон.
- JSON обект с вашия подпис ще се появи в Отговор поле.
- Въведете следната команда. Сменете
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SAD, иMY-HASHс вашата действителна информация:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Упълномощаване: Носител MY- ДОСТЪП-ТОКЕН" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Трябва да получите JSON обект, съдържащ вашия подпис.
Подпишете PDF
В допълнение към подписването на хешове на документи, можете също да качите и подпишете PDF файл.
Когато подписвате PDF, ще работите с две POST заявки:
- Качете PDF документ
- Подпишете PDF документ
Можете да използвате повторно идентификационните данни, които сте получили по-горе, с Списък с идентификационни данни на CSC заявка. Вероятно ще трябва да изтеглите нов знак за достъп.
Качете PDF документ
- Изберете Качете PDF документ заявка и щракнете върху Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, след това поставете маркера за достъп в Жетон поле.
- Изберете Заглавия и поставете идентификационния си идентификационен номер в Стойност колона.
- Изберете Body и кликнете върху × до
hello.pdfза да премахнете това име на файл с резервни части.
- Щракнете върху Избери файл , след което отидете до файла, който искате да качите.
- Щракнете върху Изпрати бутон.
- Изберете и копирайте
idстойност в отговора за използване в следващата заявка.
- Използвайте следната команда. Сменете
MY-CREDENTIAL-ID,MY-ACCESS-TOKEN, и/PATH/TO/FILE.pdfс вашата действителна информация:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Разрешение: Приносител MY- ACCESS-TOKEN "\ --header" Тип съдържание: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Ще получите JSON обект със стойност за
id. Копирайте тази стойност, за да я използвате в следващата заявка.
Забележка: За видими подписи, моля, вижте следните заглавки на HTTP заявка (/v1/pdf/upload):
|
Credential-Id |
Уникален идентификационен номер, присвоен на ключа – Задължително |
|
Подписване-причина |
Добавете причина за подписване, за да добавите във външния вид на подписа, а също и в речника на подписите – по избор, напр. одобрявам този документ |
|
Подписване-местоположение |
Добавете място за подписване в речника за подписи – по избор, напр. Хюстън, Тексас |
|
Информация за контакт |
Добавете информация за контакт в речника за подписи – по избор, напр. телефонен номер |
|
Подпис-Поле-Позиция |
Позиция на полето за подпис, където се показва визуалният подпис. Форматът е „x,y, ширина, височина“ - По избор |
|
Номер на страницата |
Номер на страницата, където да се начертае подпис – по избор |
|
Подпис на ръка |
Base64 кодирано PNG изображение на подпис на ръка – по избор |
Подпишете PDF документ
Сега можете да подпишете PDF файла.
- Изберете Качете PDF документ заявка и щракнете върху Упълномощаване раздела.
- Изберете Жетон на приносител от Тип меню, след това поставете маркера за достъп в Жетон поле.
- Изберете раздела Body, поставете в
idстойност от предишната стъпка и OTP от вашето приложение за удостоверяване, след което щракнете върху Изпрати бутон.
- PDF данните ще се покажат по-долу в Отговор поле. Избирам Запазване във файл от Запазване на отговора меню, след това дайте име на файла.
- Отворете файла в Acrobat, за да потвърдите, че файлът е подписан.
- Въведете следната команда. Сменете
MY-CREDENTIAL-ID,MY-FILE-ID, иOUTPUT-FILENAMEс вашата действителна информация. Вземете еднократна парола (OTP) от приложението си 2FA и го въведете катоMY-OTP. Забележка: OTP не се изисква за запечатване на сертификати:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Упълномощаване: Приносител MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -изход OUTPUT-FILENAME - cURL ще изтегли подписания файл и ще го запише в името на файла, което сте посочили:
- Отворете PDF файла в Acrobat или Acrobat Reader, за да проверите дали подписът е валиден.
