Ten przewodnik pokaże Ci, jak zarejestrować zamówienie na certyfikat podpisywania dokumentów w SSL.com e-podpisujący obsługiwać i używać interfejsu API Cloud Signature Consortium (CSC) do cyfrowego podpisywania skrótu dokumentu i pliku PDF. Możesz skorzystać z tego przewodnika w obu przypadkach cURL or Listonosz. Zalecamy, aby użytkownicy programu Postman zainstalowali Aplikacja komputerowa do pracy z przykładami. Przykłady w tym przewodniku mają zastosowanie zarówno do produkcyjnych, jak i testowych środowisk eSigner i eSealing SSL.com. Różnice w poleceniach między trybami produkcyjnym i testowym zostały wyjaśnione w poniższych sekcjach.
Aby wykonać te instrukcje, będziesz potrzebować:
- Zweryfikowane zamówienie na certyfikat podpisujący dokument. Proszę przeczytaj to instrukcje aby uzyskać pełne instrukcje dotyczące zamawiania i walidacji.
- A identyfikator klienta (znany również jako ID aplikacji. Należy zapoznać się to instrukcje aby uzyskać instrukcje dotyczące generowania tego poświadczenia).
Zamów certyfikat do podpisywania dokumentów SSL.com
Jak zamówić certyfikat w środowisku produkcyjnym
Zapoznaj się z tym artykułem przewodnika, aby uzyskać instrukcje dotyczące zamawiania certyfikatu podpisywania dokumentu produkcyjnego: Proces zamawiania certyfikatów do podpisywania kodu i dokumentów
Jak zamówić certyfikat testowy w piaskownicy SSL.com
SSL.com oferuje dedykowane środowisko Sandbox, odzwierciedlające nasz działający portal SSL.com i SWS API, zapewniając wolną od ryzyka przestrzeń eksperymentalną. To ustawienie „laboratoryjne” pozwala użytkownikom eksplorować i testować usługi SSL.com bez obawy o spowodowanie zakłóceń lub poniesienie rzeczywistych kosztów.
Artykuł, Korzystanie z piaskownicy SSL.com do testowania i integracji, pomoże Ci poruszać się po procesie zakładania konta Sandbox, inicjowania zamówienia testowego i integracji Sandbox z API SWS.
Po utworzeniu certyfikatu testowego skontaktuj się z zespołem pomocy technicznej SSL.com, aby go zweryfikować. Możesz to zrobić, klikając przycisk czatu online w prawym dolnym rogu strony SSL.com stronę internetową lub wysłać e-mail na adres support@ssl.com.
Zarejestruj się w eSigner i skonfiguruj uwierzytelnianie dwuskładnikowe
Zanim zaczniesz korzystać z interfejsu API CSC, musisz zarejestrować się w usłudze podpisywania w chmurze eSigner firmy SSL.com. Zatwierdzone zamówienia można zarejestrować w eSigner, postępując zgodnie z poniższymi instrukcjami:
- . Przejdź do Zamówienia na swoim koncie SSL.com i zlokalizuj swoje zamówienie.
- Kliknij zamówienie detale łącze.
- Utwórz i potwierdź 4-cyfrowy kod PIN, a następnie kliknij utwórz PIN przycisk.
Jeśli chcesz zresetować swój PIN eSigner, przeczytaj to instrukcje.
- Pojawi się kod QR.
Następnym razem, gdy ponownie załadujesz stronę, kod QR nie będzie widoczny. Jeśli chcesz wyświetlić lub zresetować swój kod QR eSigner, przeczytaj to instrukcje.
- Zeskanuj kod do aplikacji uwierzytelniania dwuskładnikowego na urządzeniu mobilnym, takiej jak Google Authenticator or Authy. Aplikacja zapewni Ci jednorazowe hasła (OTP) do użycia podczas podpisywania. Każde hasło jednorazowe jest ważne przez 30 sekund.
Opcjonalnie: Przekonwertuj swój certyfikat podpisywania dokumentu OV na certyfikat zapieczętowania
Uwaga: Ta sekcja jest przeznaczona tylko dla użytkowników, którzy chcą wykonać zapieczętowanie. Aby zautomatyzować podpisywanie dokumentów i uniknąć monitów o hasła jednorazowe (OTP), użytkownicy samodzielnie konwertują swój certyfikat podpisywania dokumentów OV (Organization Validation) na certyfikat zapieczętowania na swoich kontach SSL.com. Należy pamiętać, że certyfikatu podpisywania dokumentu z weryfikacją indywidualną (IV) nie można konwertować w celu opieczętowania. Instrukcje dotyczące konwersji uszczelnienia są szczegółowo opisane poniżej:
- Kliknij Zamówienia w górnym menu Twojego konta SSL.com.
- Znajdź swój certyfikat i kliknij przycisk pobierz / szczegóły łącze.
- Kliknij USUŃ 2FA przycisk.
Zainstaluj Postman i Importuj kolekcje API
Instrukcje w tej sekcji są przeznaczone wyłącznie dla użytkowników programu Postman. Jeśli używasz cURL z CSC API, możesz przejść do następnej sekcji.
- Pobierz i rozpakuj Kolekcja CSC API Postman i Kolekcja Postman interfejsu API podpisywania dokumentów (Patrz https://www.postman.com/sslcom dla kolekcji online SSL.com API).
- Pobierz i zainstaluj Klient REST Postman.
- Uruchom Postman, a następnie utwórz nowe konto Postman lub zaloguj się do istniejącego.
- Kliknij import przycisk.
- Kliknij Prześlij pliki przycisk, przejdź do rozpakowanych plików kolekcji API (
csc-api-prod.postman_collection.jsonidocument-signing-api-prod.postman_collection.json) i otwórz je.
- Kliknij import przycisk.
- Żądania API, z którymi będziesz pracować, są teraz dostępne w Kategorie kartę po lewej stronie okna Listonosza.
Pobierz token dostępu
Następnym krokiem jest pobranie tokenu dostępu z SSL.com. Będziesz potrzebować swojego identyfikator klienta dostępne, a także nazwę użytkownika i hasło do konta SSL.com. Tokeny dostępu są ważne przez jedną godzinę po ich wystawieniu.
Skorzystaj z klikalnych kart poniżej, aby wybrać instrukcje dla Postman lub cURL:
- Wybierz żądanie API z kolekcji CSC API.
- Wybierz Autoryzacja I wybierz opcję Uwierzytelnianie OA 2.0 z Typ menu.
- Wpisz w formularzu następujące informacje:
- Prefiks nagłówka:
Bearer - Nazwa tokena:
SSLCOM CSC(lub dowolna inna łatwa do zapamiętania nazwa, którą wolisz) - Rodzaj dotacji:
Authorization Code - URL wywołania zwrotnego:
https://upload.esigner.com - Autoryzuj za pomocą przeglądarki: niezaznaczone
- Adres URL autoryzacji:
https://login.ssl.com/oauth2/authorizedla środowiska produkcyjnego;https://oauth-sandbox.ssl.com/oauth2/authorizedla środowiska piaskownicy. - Adres URL tokena dostępu:
https://login.ssl.com/oauth2/tokendla środowiska produkcyjnego;https://oauth-sandbox.ssl.com/oauth2/tokendla środowiska piaskownicy. - Identyfikator klienta: [Twój identyfikator klienta]
- Tajemnica klienta: [Twój sekret klienta]
- Zakres:
service - Stan: [Pozostaw puste]
- Uwierzytelnianie klienta:
Send as Basic Auth header
Po zakończeniu kliknij Uzyskaj nowy token dostępu przycisk.
- Prefiks nagłówka:
- Pojawi się formularz logowania. Wprowadź swoją nazwę użytkownika i hasło SSL.com, a następnie kliknij Logowanie przycisk.
- Twój nowy token dostępu powinien pojawić się w Postman. Wybierz tekst tokena dostępu i skopiuj go do schowka, a następnie zamknij plik Zarządzaj tokenami dostępu Okno dialogowe. Wklej swój token dostępu do edytora tekstu, aby mieć do niego łatwy dostęp. Każdy token dostępu wygaśnie po godzinie.
Możesz także zapisać swój token do ponownego wykorzystania w żądaniach listonosza, ale okazało się, że najbardziej niezawodne jest kopiowanie i wklejanie tokena bezpośrednio do każdego żądania.
- Użyj następującego polecenia, aby zażądać tokenu dostępu. Zastąp wartości pokazane WIELKIMI LITERAMI rzeczywistymi wartościami:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id": "TWÓJ -ID-KLIENTA", "tajemny_klient" : "TWÓJ-TAJNY-KLIENT", "typ_grantu": "hasło", "nazwa_użytkownika": "TWOJA-NAZWA-UŻYTKOWNIKA", "hasło" : "TWOJE-HASŁO" }' - Powinieneś otrzymać obiekt JSON zawierający token dostępu i token odświeżania. Skopiuj wartość tokenu dostępu, aby wkleić ją do żądań interfejsu API. W tych przykładach nie będziesz potrzebować tokena odświeżania.
Podpisz skrót
Teraz, gdy masz token dostępu, możesz rozpocząć tworzenie żądań API i tworzenie podpisów. Ta sekcja poprowadzi Cię przez pięć dostępnych żądań w kolekcji Postman CSC, skutkując utworzeniem podpisu cyfrowego na podstawie skrótu dokumentu.
- Do manipulowania plikiem PDF w celu wprowadzenia skrótu i późniejszego osadzenia PKCS#7 w dokumencie PDF potrzebna jest biblioteka PDF. (np. ApachePDFBox w Javie).
- Biblioteka Crypto do tworzenia PKCS#7 z surowych podpisów otrzymanych z API eSigner (np. BouncyCastle w Javie).
Uzyskaj informacje CSC (opcjonalnie)
- Możesz użyć Informacje CSC prośba o informacje o usłudze podpisu w chmurze SSL.com. Zwróć uwagę, że w przeciwieństwie do innych w kolekcji to żądanie nie wymaga tokena dostępu. Aby wysłać żądanie, wybierz Informacje CSC z API CSC kolekcji, a następnie kliknij Wyślij przycisk.
- Informacje o usłudze podpisu w chmurze pojawią się w obiekcie JSON w aplikacji Postman Odpowiedź pole.
- Użyj następującego polecenia, aby uzyskać informacje o usłudze CSC API SSL.com. Jeśli jesteś w środowisku piaskownicy, użyj
https://cs-try.ssl.com/csc/v0/infozamiast.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Otrzymasz obiekt JSON ze szczegółami dotyczącymi usługi:
Lista poświadczeń CSC
Opona Lista poświadczeń CSC request pobierze dane uwierzytelniające, których będziesz używać w późniejszych żądaniach API.
- Wybierz Lista poświadczeń CSC i kliknij Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, wklej swój token dostępu do pliku żeton pole, a następnie kliknij Wyślij przycisk.
- Obiekt JSON z listą identyfikatorów poświadczeń skojarzonych z użytkownikiem pojawi się w pliku Odpowiedź pole. Twoja lista będzie prawdopodobnie zawierać jedną wartość. Skopiuj i wklej swój identyfikator poświadczenia do edytora tekstu do wykorzystania w późniejszych żądaniach.
- Wprowadź następujące polecenie. (Zastąp MÓJ-TOKEN DOSTĘPU swoim rzeczywistym tokenem dostępu). Jeśli jesteś w środowisku piaskownicy, użyj
https://cs-try.ssl.com/csc/v0/credentials/listzamiast:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autoryzacja: Nośnik MY- ŻETON-DOSTĘPU "\ --data-raw" {} "W przypadku korzystania z certyfikatu eseal (certyfikat do podpisywania dokumentów zawierający wyłącznie informacje o organizacji; dołączony do bezpłatnego konta esigner.com), dołącz „clientData”: „DS_ESEAL” (uwaga: pieczęci nie wymagają uwierzytelniania OTP). Inne opcje dla „clientData” to „EVCS” dla podpisywania kodu EV i „DS” (domyślnie) dla podpisywania dokumentów IV lub IV+OV:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autoryzacja: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Powinieneś otrzymać obiekt JSON z listą identyfikatorów poświadczeń powiązanych z użytkownikiem. Twoja lista będzie prawdopodobnie zawierać jedną wartość. Skopiuj i wklej swój identyfikator poświadczenia do edytora tekstu, aby móc go później użyć.
Informacje o poświadczeniach CSC (opcjonalnie)
Opona Informacje o poświadczeniach CSC żądanie zwróci certyfikaty i inne informacje związane z identyfikatorem poświadczeń i nie jest wymagane do podpisania.
- Aby skorzystać z tego żądania, wybierz Informacje o poświadczeniach CSC z kolekcji i kliknij Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, a następnie wklej swój token dostępu do pliku żeton pole.
- Wybierz Ciało a następnie wklej swój identyfikator poświadczenia jako wartość
credentialID.
- Kliknij Wyślij przycisk.
- Obiekt JSON z łańcuchem certyfikatów podpisujących i innymi informacjami pojawi się w pliku Odpowiedź pole.
- Wprowadź następujące polecenie. Jeśli jesteś w środowisku piaskownicy, użyj
https://cs-try.ssl.com/csc/v0/credentials/infozastąpićMY-ACCESS-TOKENiMY-CREDENTIAL-IDz Twoimi aktualnymi informacjami:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autoryzacja: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - Powinieneś otrzymać obiekt JSON z łańcuchem certyfikatów podpisujących i innymi informacjami:
Autoryzacja poświadczeń
Opona Autoryzacja poświadczeń Żądanie pobierze autoryzację do podpisania skrótu.
- Rozpocznij od wybrania Autoryzacja poświadczeń z kolekcji i klikając Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, a następnie wklej swój token dostępu do pliku żeton pole.
- Wybierz Ciało patka. Wklej swój identyfikator poświadczenia jako plik
credentialIDwartość i skrót dokumentu, który chcesz podpisać jako plikhashwartość. Pobierz i wprowadź hasło jednorazowe z aplikacji uwierzytelniającej i wprowadź je jako wartośćOTP, a następnie kliknij przycisk Wyślij przycisk. Uwaga: OTP nie jest wymagane do plombowania certyfikatów.
- Obiekt JSON z danymi aktywacji podpisu (SAD) pojawi się w pliku Odpowiedź pole. Skopiuj i wklej tę wartość do edytora tekstu, aby użyć jej w żądaniu podpisania skrótu.
- Użyj następującego polecenia. Zastąpić
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-HASHz Twoimi aktualnymi informacjami. Uzyskaj jednorazowe hasło z aplikacji 2FA i użyj go jako wartościMY-OTP. Uwaga: OTP nie jest wymagane do plombowania certyfikatów.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autoryzacja: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP „}” - Powinieneś otrzymać obiekt JSON z danymi aktywacji podpisu (SAD). Skopiuj i wklej tę wartość do edytora tekstu, aby użyć jej w żądaniu podpisania skrótu.
Znak haszy
Teraz możesz podpisać skrót dokumentu.
- Wybierz Znak haszy z kolekcji, a następnie wybierz plik Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, a następnie wklej swój token dostępu do pliku żeton pole.
- Wybierz Ciało patka. Wklej swój identyfikator poświadczenia jako plik
credentialIDwartość, Twoje dane aktywacji podpisu jako plikSADwartość i skrót dokumentu, który chcesz podpisać jako plikhashwartość, a następnie kliknij Wyślij przycisk.
- Obiekt JSON z Twoim podpisem pojawi się w Odpowiedź pole.
- Wpisz następujące polecenie. Zastąpić
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SAD,MY-HASHz Twoimi aktualnymi informacjami:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autoryzacja: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Powinieneś otrzymać obiekt JSON zawierający Twój podpis.
Podpisz plik PDF
Oprócz podpisywania skrótów dokumentów można również przesłać i podpisać plik PDF.
Podczas podpisywania pliku PDF będziesz pracować z dwoma żądaniami POST:
- Prześlij dokument PDF
- Podpisz dokument PDF
Możesz ponownie użyć danych logowania pobranych powyżej z rozszerzeniem Lista poświadczeń CSC żądanie. Prawdopodobnie będziesz musiał również odzyskać nowy plik token dostępu.
Prześlij dokument PDF
- Wybierz Prześlij dokument PDF żądanie i kliknij Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, a następnie wklej swój token dostępu do pliku żeton pole.
- Wybierz Nagłówki i wklej swój identyfikator poświadczenia w wartość Kolumna.
- Wybierz Ciało i kliknij przycisk × obok
hello.pdfaby usunąć tę zastępczą nazwę pliku.
- Kliknij Wybierz Plik , a następnie przejdź do pliku, który chcesz przesłać.
- Kliknij Wyślij przycisk.
- Wybierz i skopiuj plik
idwartość w odpowiedzi do użycia w następnym żądaniu.
- Użyj następującego polecenia. Zastąpić
MY-CREDENTIAL-ID,MY-ACCESS-TOKEN,/PATH/TO/FILE.pdfz Twoimi aktualnymi informacjami:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autoryzacja: Bearer MY- TOKEN DOSTĘPU "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Otrzymasz obiekt JSON z wartością dla
id. Skopiuj tę wartość, aby użyć jej w następnym żądaniu.
Uwaga: Aby uzyskać widoczne podpisy, zapoznaj się z następującymi nagłówkami żądań HTTP (/v1/pdf/upload):
|
Identyfikator poświadczeń |
Unikalny identyfikator poświadczeń przypisany do klucza – Obowiązkowe |
|
Powód podpisu |
Dodaj powód podpisu, aby dodać w wyglądzie podpisu, a także w słowniku podpisów – Opcjonalnie np. Zatwierdzam ten dokument |
|
Lokalizacja podpisywania |
Dodaj lokalizację podpisywania w słowniku podpisów – opcjonalnie, np. Houston, Texas |
|
Informacje kontaktowe |
Dodaj informacje kontaktowe w słowniku podpisów – Opcjonalne, np. Numer telefonu |
|
Pozycja w polu podpisu |
Pozycja pola podpisu, w której wyświetlany jest podpis wizualny. Format to „x,y,szerokość,wysokość” - Opcjonalny |
|
Numer strony |
Numer strony, na której należy narysować podpis – Opcjonalnie |
|
Podpis odręczny |
Zakodowany w Base64 obraz podpisu odręcznego w formacie PNG — opcjonalnie |
Podpisz dokument PDF
Teraz możesz podpisać plik PDF.
- Wybierz Prześlij dokument PDF żądanie i kliknij Autoryzacja patka.
- Dodaj Token okaziciela z Typ menu, a następnie wklej swój token dostępu do pliku żeton pole.
- Wybierz kartę Treść, wklej plik
idwartość z poprzedniego kroku i hasło jednorazowe z aplikacji uwierzytelniającej, a następnie kliknij Wyślij przycisk.
- Dane PDF pojawią się poniżej w Odpowiedź pole. Wybierać Zapisz do pliku z Zapisz odpowiedź menu, a następnie nadaj plikowi nazwę.
- Otwórz plik w programie Acrobat, aby potwierdzić, że plik został podpisany.
- Wpisz następujące polecenie. Zastąpić
MY-CREDENTIAL-ID,MY-FILE-ID,OUTPUT-FILENAMEz Twoimi aktualnymi informacjami. Uzyskaj hasło jednorazowe (OTP) z aplikacji 2FA i wprowadź je jakoMY-OTP. Uwaga: OTP nie jest wymagane do plombowania certyfikatów:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autoryzacja: Nośnik MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -output OUTPUT-FILENAME - cURL pobierze podpisany plik i zapisze go pod podaną nazwą:
- Otwórz plik PDF w programie Acrobat lub Acrobat Reader, aby sprawdzić, czy podpis jest ważny.
