Tato příručka vám ukáže, jak zaregistrovat objednávku certifikátu pro podepisování dokumentů na stránkách SSL.com eSigner službu a pomocí API Cloud Signature Consortium (CSC) digitálně podepsat hash dokumentu a soubor PDF. Tuto příručku můžete použít s oběma kučera or Listonoš. Doporučujeme uživatelům Postmanu nainstalovat app desktop pro práci s příklady. Příklady v této příručce jsou použitelné pro produkční a testovací prostředí eSigner a eSealing SSL.com. Rozdíly v příkazech mezi produkčním a testovacím režimem jsou vysvětleny v následujících částech.
Chcete-li postupovat podle těchto pokynů, budete potřebovat:
- Objednávka certifikátu pro podepisování ověřeného dokumentu. Přečtěte si prosím to jak na to úplné pokyny k objednání a ověření.
- A ID zákazníka (také známý jako ID aplikace. Obraťte se prosím na to jak na to pokyny k vygenerování tohoto pověření).
Objednejte si certifikát pro podepisování dokumentů SSL.com
Jak si objednat certifikát v produkčním prostředí
Pokyny k objednání certifikátu pro podpis produkčního dokumentu naleznete v tomto článku průvodce: Proces objednávání certifikátů pro podepisování kódu a dokumentů
Jak si objednat testovací certifikát na Sandboxu SSL.com
SSL.com nabízí vyhrazené prostředí Sandbox, které zrcadlí náš živý portál SSL.com a SWS API, pro prostor pro experimenty bez rizika. Toto „laboratorní“ nastavení umožňuje uživatelům prozkoumávat a testovat služby SSL.com, aniž by se museli obávat, že způsobí narušení provozu nebo že vzniknou skutečné náklady.
Článek, Použití karantény SSL.com pro testování a integraci, vám pomůže orientovat se v procesu založení účtu Sandbox, zahájení testovací objednávky a integrace Sandboxu s SWS API.
Jakmile vytvoříte svůj testovací certifikát, kontaktujte tým podpory SSL.com, aby jej ověřil. Můžete to udělat kliknutím na tlačítko online chatu v pravém dolním rohu SSL.com webové stránky nebo odesláním e-mailu support@ssl.com.
Zaregistrujte se do eSigneru a nastavte dvoufaktorové ověřování
Než budete moci začít používat CSC API, musíte se zaregistrovat do služby cloudového podepisování eSigner SSL.com. Ověřené objednávky lze do eSigner zaregistrovat podle následujících pokynů:
- . Přejděte na Objednávky ve svém účtu SSL.com a vyhledejte svou objednávku.
- Klikněte na objednávku podrobnosti odkaz.
- Vytvořte a potvrďte čtyřmístný PIN, poté klikněte na vytvořit PIN .
Pokud potřebujete resetovat PIN eSigneru, přečtěte si jej to jak na to.
- Objeví se QR kód.
Při příštím načtení stránky nebude QR kód viditelný. Pokud potřebujete zobrazit nebo resetovat QR kód eSigneru, přečtěte si jej to jak na to.
- Naskenujte kód do aplikace pro dvoufaktorové ověřování na vašem mobilním zařízení, například Google Authenticator or Authy. Aplikace vám poskytne jednorázová hesla (OTP) pro použití při podepisování. Každé OTP je platné po dobu 30 sekund.
Volitelné: Převeďte svůj certifikát podpisu dokumentů OV na certifikát esealing
Poznámka: Tato sekce je pouze pro uživatele, kteří chtějí provádět těsnění. Aby bylo možné automatizovat podepisování dokumentů a nemuseli být vyzváni k zadání jednorázových hesel (OTP), uživatelé sami převedou svůj certifikát pro podepisování dokumentů pro ověření organizace (OV) na certifikát esealing na svých účtech SSL.com. Vezměte na vědomí, že certifikát podpisu dokumentu pro individuální ověření (IV) nelze převést za účelem zapečetění. Pokyny pro zapečetění převodu jsou podrobně uvedeny níže:
- klikněte Objednávky v horní nabídce vašeho účtu SSL.com.
- Najděte svůj certifikát a klikněte na stáhnout / podrobnosti odkaz.
- Klepněte na tlačítko ODSTRANIT 2FA .
Nainstalujte Postman a importujte kolekce API
Pokyny v této části jsou pouze pro uživatele služby Postman. Pokud používáte cURL s CSC API, můžete přejít na další část.
- Stáhněte a rozbalte soubor Sbírka Postman CSC API a Sbírka Postman API pro podepisování dokumentů (Viz https://www.postman.com/sslcom pro online kolekce SSL.com API).
- Stáhněte a nainstalujte Pošťák REST klient.
- Spusťte Postmana, poté vytvořte nový účet Postmana nebo se přihlaste ke stávajícímu.
- Klepněte na tlačítko import .
- Klepněte na tlačítko Nahrát soubory tlačítko, přejděte na rozbalené soubory kolekce API (
csc-api-prod.postman_collection.jsonadocument-signing-api-prod.postman_collection.json) a otevřete je.
- Klepněte na tlačítko import .
- Požadavky API, se kterými budete pracovat, jsou nyní k dispozici v Kolekce záložka na levé straně okna Pošťák.
Načíst přístupový token
Dalším krokem je získání přístupového tokenu z SSL.com. Budete potřebovat svoji ID zákazníka dostupné, stejně jako uživatelské jméno a heslo pro váš účet SSL.com. Přístupové tokeny jsou platné jednu hodinu po jejich vydání.
Pomocí záložek, na které lze kliknout, vyberte pokyny pro Postmana nebo CURL:
- Vyberte požadavek API ze sbírky CSC API.
- Vybrat Povolení Kartu a vyberte OAuth 2.0 z Styl menu.
- Do formuláře zadejte následující informace:
- Předpona záhlaví:
Bearer - Jméno jména:
SSLCOM CSC(nebo jakýkoli jiný snadno zapamatovatelný název, který preferujete) - Typ grantu:
Authorization Code - URL zpětného volání:
https://upload.esigner.com - Autorizovat pomocí prohlížeče: nekontrolovaný
- Ověřovací adresa URL:
https://login.ssl.com/oauth2/authorizepro produkční prostředí;https://oauth-sandbox.ssl.com/oauth2/authorizepro prostředí Sandbox. - URL přístupového tokenu:
https://login.ssl.com/oauth2/tokenpro produkční prostředí;https://oauth-sandbox.ssl.com/oauth2/tokenpro prostředí Sandbox. - ID klienta: [Vaše ID klienta]
- Tajemství klienta: [Tajné tajemství vašeho klienta]
- Rozsah:
service - Stát: [ponechejte prázdné]
- Ověření klienta:
Send as Basic Auth header
Po dokončení klikněte na Získejte nový přístupový token .
- Předpona záhlaví:
- Zobrazí se přihlašovací formulář. Zadejte své uživatelské jméno a heslo pro SSL.com a poté klikněte na Přihlášení uživatele .
- Váš nový přístupový token by se měl objevit v Postmanu. Vyberte text přístupového tokenu, zkopírujte jej do schránky a poté zavřete Spravujte přístupové tokeny dialogové okno. Vložte svůj přístupový token do textového editoru, kde k němu máte snadný přístup. Každý přístupový token vyprší po jedné hodině.
Token můžete také uložit k opětovnému použití v požadavcích Postmana, ale zjistili jsme, že je nejspolehlivější token zkopírovat a vložit přímo do každého požadavku.
- Pomocí následujícího příkazu požádejte o přístupový token. Nahraďte hodnoty zobrazené v ALL-CAPS vašimi skutečnými hodnotami:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "VAŠE -CLIENT-ID", "client_secret" : "VAŠE-KLIENTSKÉ-TAJENSTVÍ", "grant_type" : "heslo", "username" : "VAŠE-UŽIVATELSKÉ JMÉNO", "heslo" : "VAŠE-HESLO" }' - Měli byste obdržet objekt JSON obsahující přístupový token a obnovovací token. Zkopírujte hodnotu přístupového tokenu a vložte ji do svých požadavků API. U těchto příkladů nebudete potřebovat obnovovací token.
Podepsat hash
Nyní, když máte přístupový token, můžete začít vytvářet požadavky API a vytvářet podpisy. Tato část vás provede pěti dostupnými požadavky ve sbírce Postman CSC, což povede k vytvoření digitálního podpisu z hodnoty hash dokumentu.
- K manipulaci s PDF pro vstup hash a pozdějšímu vložení PKCS#7 do dokumentu PDF je potřeba knihovna PDF. (např. ApachePDFBox v Javě).
- Knihovna Crypto pro vytváření PKCS#7 z nezpracovaných podpisů přijatých z eSigner API (např. BouncyCastle v Javě).
Získat informace o CSC (volitelně)
- Můžete použít Informace o CSC požádat o získání informací o cloudové podpisové službě SSL.com. Všimněte si, že na rozdíl od ostatních v kolekci tento požadavek nevyžaduje váš přístupový token. Chcete-li odeslat požadavek, vyberte Informace o CSC z CSC API kolekce a poté klikněte na Poslat .
- Informace o cloudové podpisové službě se objeví v objektu JSON v Postman's Odpověď pole.
- Pomocí následujícího příkazu získáte informace o službě CSC API SSL.com. Pokud jste v prostředí sandbox, použijte
https://cs-try.ssl.com/csc/v0/infonamísto.
curl --location --request POST "https://www.ssl.com/cs/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Obdržíte objekt JSON s podrobnostmi o službě:
Seznam pověření CSC
Projekt Seznam pověření CSC požadavek načte pověření, které použijete v pozdějších požadavcích API.
- vybrat Seznam pověření CSC a klepněte na tlačítko Povolení Karta.
- Vybrat Token na doručitele z Styl vložit svůj přístupový token do Známka klepněte na pole Poslat .
- Objekt JSON se seznamem ID pověření přidružených k uživateli se zobrazí v Odpověď pole. Váš seznam bude pravděpodobně obsahovat jednu hodnotu. Zkopírujte a vložte ID pověření do textového editoru pro použití v pozdějších požadavcích.
- Zadejte následující příkaz. (Nahraďte MY-ACCESS-TOKEN svým skutečným přístupovým tokenem). Pokud se nacházíte v prostředí sandbox, použijte
https://cs-try.ssl.com/csc/v0/credentials/listnamísto:
curl --location --request POST "https://www.ssl.com/cs/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorizace: Nositel MY- ACCESS-TOKEN "\ --data-raw" {} "Pokud používáte certifikát eseal (certifikát pro podepisování dokumentů pouze s informacemi o organizaci; součástí vašeho bezplatného účtu esigner.com), zadejte „clientData“: „DS_ESEAL“ (poznámka: eseals nevyžadují ověření OTP). Další možnosti pro „clientData“ jsou „EVCS“ pro podepisování kódu EV a „DS“ (výchozí) pro IV nebo IV+OV podepisování dokumentů:
curl --location --request POST "https://www.ssl.com/cs/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorizace: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Měli byste obdržet objekt JSON se seznamem ID pověření přidružených k uživateli. Váš seznam bude pravděpodobně obsahovat jednu hodnotu. Zkopírujte a vložte ID pověření do textového editoru pro použití v pozdějších požadavcích.
Informace o pověřeních CSC (volitelně)
Projekt Informace o pověření CSC požadavek vrátí certifikáty a další informace spojené s ID pověření a není pro podpis vyžadován.
- Chcete-li použít tento požadavek, vyberte Informace o pověření CSC ze sbírky a klikněte na Povolení Karta.
- Vybrat Token na doručitele z Styl do nabídky a poté vložte přístupový token do složky Známka pole.
- Vybrat Tělo kartu, poté vložte ID pověření jako hodnotu pro
credentialID.
- Klepněte na tlačítko Poslat .
- Objekt JSON s řetězcem podpisového certifikátu a dalšími informacemi se objeví v Odpověď pole.
- Zadejte následující příkaz. Pokud se nacházíte v prostředí sandbox, použijte
https://cs-try.ssl.com/csc/v0/credentials/infoNahraditMY-ACCESS-TOKENaMY-CREDENTIAL-IDs vašimi skutečnými informacemi:
curl --location --request POST "https://www.ssl.com/cs/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Autorizace: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "ID pověření": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - Měli byste obdržet objekt JSON s řetězcem podpisového certifikátu a dalšími informacemi:
Autorizace pověření
Projekt Autorizace pověření požadavek načte oprávnění k podpisu hash.
- Začněte výběrem Autorizace pověření ze sbírky a kliknutím na Povolení Karta.
- Vybrat Token na doručitele z Styl do nabídky a poté vložte přístupový token do složky Známka pole.
- Vybrat Tělo záložka. Vložte své identifikační údaje jako
credentialIDhodnotu a hash dokumentu, který chcete podepsat jakohashhodnota. Načtěte a zadejte OTP z vaší ověřovací aplikace a zadejte jej jako hodnotu proOTP, poté klepněte na tlačítko Poslat knoflík. Poznámka: OTP není vyžadováno pro zapečetění certifikátů.
- Objekt JSON s vašimi daty aktivace podpisu (SAD) se objeví v Odpověď pole. Zkopírujte a vložte tuto hodnotu do textového editoru pro použití v požadavku na podpis hash.
- Použijte následující příkaz. Nahradit
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID, aMY-HASHs vašimi skutečnými informacemi. Získejte jednorázové heslo ze své aplikace 2FA a použití je jako hodnota proMY-OTP. Poznámka: OTP není vyžadováno pro zapečetění certifikátů.
curl --location --request POST "https://www.ssl.com/cs/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Autorizace: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "ID pověření": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}" - Měli byste obdržet objekt JSON s vašimi daty aktivace podpisu (SAD). Zkopírujte a vložte tuto hodnotu do textového editoru pro použití v požadavku na podpis hash.
Podepsat hash
Nyní jste připraveni podepsat hash dokumentu.
- vybrat Podepsat hash ze sbírky a poté vyberte Povolení Karta.
- Vybrat Token na doručitele z Styl do nabídky a poté vložte přístupový token do složky Známka pole.
- Vybrat Tělo záložka. Vložte své identifikační údaje jako
credentialIDhodnota, vaše aktivační data podpisu jakoSADhodnota a hash dokumentu, který chcete podepsat jakohashhodnotu a poté klikněte na Poslat .
- Objekt JSON s vaším podpisem se objeví v Odpověď pole.
- Zadejte následující příkaz. Nahradit
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SAD, aMY-HASHs vašimi skutečnými informacemi:
curl --location --request POST "https://www.ssl.com/cs/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Autorizace: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "ID pověření": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Měli byste obdržet objekt JSON obsahující váš podpis.
Podepište PDF
Kromě podepisování hodnot hash dokumentů můžete také nahrát a podepsat soubor PDF.
Při podepisování PDF budete pracovat se dvěma požadavky POST:
- Nahrajte dokument PDF
- Podepsat dokument PDF
Pověření, které jste získali výše, můžete znovu použít pomocí Seznam pověření CSC žádost. Pravděpodobně budete také muset získat nový přístupový token.
Nahrajte dokument PDF
- Vybrat Nahrajte dokument PDF požádat a kliknout na Povolení Karta.
- Vybrat Token na doručitele z Styl do nabídky a poté vložte přístupový token do složky Známka pole.
- Vybrat Záhlaví na kartu a vložte ID pověření do Hodnota sloupec.
- Vybrat Tělo a klepněte na tlačítko × vedle
hello.pdfodebrat tento zástupný název souboru.
- Klepněte na tlačítko Zvolte soubor poté přejděte na soubor, který chcete nahrát.
- Klepněte na tlačítko Poslat .
- Vyberte a zkopírujte
idhodnota v odpovědi, která se použije v příštím požadavku.
- Použijte následující příkaz. Nahradit
MY-CREDENTIAL-ID,MY-ACCESS-TOKEN, a/PATH/TO/FILE.pdfs vašimi skutečnými informacemi:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorizace: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Obdržíte objekt JSON s hodnotou pro
id. Zkopírujte tuto hodnotu a použijte ji v dalším požadavku.
Poznámka: Viditelné podpisy naleznete v následujících záhlavích požadavků HTTP (/v1/pdf/upload):
|
ID pověření |
Jedinečné ID pověření přiřazené ke klíči – Povinné |
|
Důvod podpisu |
Přidat důvod podpisu pro přidání do vzhledu podpisu a také do podpisového slovníku – Nepovinné, např. Souhlasím s tímto dokumentem |
|
Umístění podpisu |
Přidejte umístění podpisu do slovníku podpisů – volitelné, např. Houston, Texas |
|
Kontaktní informace |
Přidejte kontaktní informace do podpisového slovníku – volitelné, např. telefonní číslo |
|
Podpis-pole-pozice |
Pozice pole podpisu, kde se zobrazuje vizuální podpis. Formát je "x,y,šířka,výška" - Volitelné |
|
Číslo stránky |
Číslo stránky, kam nakreslit podpis – Nepovinné |
|
Ruční podpis |
Obrázek podpisu ruky PNG zakódovaný v Base64 – volitelné |
Podepsat dokument PDF
Nyní můžete PDF podepsat.
- Vybrat Nahrajte dokument PDF požádat a kliknout na Povolení Karta.
- Vybrat Token na doručitele z Styl do nabídky a poté vložte přístupový token do složky Známka pole.
- Vyberte kartu Tělo a vložte do
idhodnotu z předchozího kroku a OTP z vaší ověřovací aplikace, poté klikněte na Poslat .
- Data PDF se objeví níže v souboru Odpověď pole. Vybrat Uložit do souboru z Uložit odpověď v nabídce, pak pojmenujte soubor.
- Otevřete soubor v Acrobatu a ověřte, zda je soubor podepsán.
- Zadejte následující příkaz. Nahradit
MY-CREDENTIAL-ID,MY-FILE-ID, aOUTPUT-FILENAMEs vašimi skutečnými informacemi. Získejte jednorázové heslo (OTP) ze své aplikace 2FA a zadejte jej jakoMY-OTP. Poznámka: OTP není vyžadováno pro zapečetění certifikátů:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autorizace: Nositel MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -výstup OUTPUT-FILENAME - cURL stáhne podepsaný soubor a uloží jej do zadaného názvu souboru:
- Otevřete PDF v aplikaci Acrobat nebo Acrobat Reader a zkontrolujte, zda je podpis platný.
