Integrationsvejledning til test af ekstern dokumentsignering med eSigner CSC API

Denne guide fører dig gennem underskrivelse af en dokumenthash og PDF-fil med SSL.com's eSigner sky signeringstjeneste og Cloud Signature Consortium (CSC) API. Alle eksempler på API-anmodninger vises med Postman, og vi anbefaler at installere Postbud desktop-app på din computer, hvis du vil gennemgå eksemplerne. cURL kommandoeksempler på API-anmodninger er også inkluderet.

Opret en testordre

1. Først skal du oprette en dokumentsigneringsordre i Sandbox. Begynd med at logge ind på din Sandbox-konto og gå til Hovedmenu fane.
   
2. Klik udviklingsværktøjer.
   
3. Type eSigner-dokumentunderskrivelse, og klik derefter på Opret testordre .
   
4. En dialogboks vises. Klik på OK .
   
5. Find din testordre, og klik derefter på detaljer .
   
6. Klik rediger registrant for at begynde at indtaste ansøger- og modtageroplysninger til din testordre. Bemærk, at da disse oplysninger ikke vil blive brugt til at udstede et gyldigt dokumentsigneringscertifikat, kan du indtaste fiktive oplysninger, hvis det ønskes.
   
7. Tilføj ansøgeroplysninger til testcertifikatet, og klik derefter på Næste >> .
   
8. Indtast modtageroplysninger, og klik derefter på Næste >> .
   
9. Klik på knappen Spring knappen for at springe over upload af valideringsdokumenter til testcertifikatet.
   
10. Din testordre skal nu have status som afventer validering. Kontakt SSL.com supportteamet på Support@SSL.com for at få dit testcertifikat valideret.
    

Tilmeld dig eSigner og opsæt tofaktorautentificering

1. Når din testordre er valideret af SSL.com supportmedarbejdere, kan du tilmelde den til eSigner. Naviger til Mine Ordrer fanen i din SSL.com-sandkassekonto og find din testordre.
   
2. Klik på ordren detaljer .
   
3. Opret og bekræft en firecifret PIN-kode, og klik derefter på Opret PIN .
   
   Hvis du har brug for at nulstille din eSigner-pinkode, skal du læse denne vej.
   
4. En QR-kode vises.
   
   Næste gang du genindlæser siden, vil QR-koden ikke være synlig. Hvis du har brug for at se eller nulstille din eSigner QR-kode, skal du læse denne vej.
   
5. Scan koden til en 2-faktor-godkendelsesapp på din mobilenhed, såsom Google Authenticator eller Authy. Appen giver dig engangsadgangskoder (OTP'er) til brug ved signering. Hver OTP er gyldig i 30 sekunder.
   

Installer Postman og Import CSC API Collection

1. Download og pakk ud CSC API Postman-samling (Se https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation for de seneste api-slutpunkter eller samlingsdownloads).
   
2. Download og installer Postbudets REST-klient.
   
3. Start Postman, og opret derefter en ny Postman-konto, eller log ind på en eksisterende.
   
4. Klik på knappen Importere .
   
5. Klik på knappen Upload filer knap, naviger til den udpakkede API-indsamlingsfil (CSC-API.postman_collection.json), og åbn den.
   
6. Klik på knappen Importere .
   
7. Klik på knappen Kollektioner på Postman, og udvid CSC API-samlingen for at se de fem POST-anmodninger, du vil arbejde med:
   • CSC info
   • CSC legitimationsoplysninger
   • Info om CSC-legitimationsoplysninger
   • Legitimationsoplysninger Godkend
   • Underskriv Hash

   

Hent adgangstoken

1. Det næste trin er at hente et adgangstoken fra SSL.com. Før du anmoder om dit adgangstoken, skal du bruge et kunde-id (også kendt som en Ansøgnings-id. Vær sød at henvise til denne vej for instruktioner om generering af denne legitimationsoplysninger).
2. Vælg Tilladelse fanebladet, vælg OAuth 2.0 fra Type , og klik på Få nyt adgangstoken .
   
3. Indtast følgende oplysninger i formularen:
   • Token Navn: SandBox CSC (eller ethvert andet let at huske navn, som du foretrækker)
   • Tilskudstype: Autorisation kode
   • URL til tilbagekaldelse: [Efterlad blank]
   • Godkend ved hjælp af browser: afkrydset
   • Godkend URL: https://oauth-sandbox.ssl.com/oauth2/authorize
   • Adgangstoken-URL: https://oauth-sandbox.ssl.com/oauth2/token
   • Klient-id: [Dit klient-id]
   • Klienthemmelighed: [Din klienthemmelighed]
   • Anvendelsesområde: tjeneste
   • Tilstand: [Efterlad blank]
   • Klientgodkendelse: Send som Basic Auth-overskrift

   Når du er færdig, skal du klikke på Anmodningstoken .
   

4. En loginformular vises i din webbrowser. Indtast dit SSL.com-brugernavn og din adgangskode, og klik derefter på Medlem Login .
   
5. Dit nye adgangstoken skal vises i Postman. Vælg adgangstokenteksten, og kopier den til udklipsholderen, og luk derefter Administrer adgangstokens dialog boks. Indsæt dit adgangstoken i en teksteditor, hvor du nemt kan få adgang til det. Hvert adgangstoken udløber efter en time.
   
   Du kan også gemme dit token til genbrug i Postman anmodninger, men vi har fundet ud af, at det er mest pålideligt at kopiere og indsætte tokenet direkte i hver anmodning.
   

Skriv en Hash

Nu hvor du har et adgangstoken, kan du begynde at lave API-anmodninger og oprette signaturer. Dette afsnit fører dig gennem de fem tilgængelige anmodninger i Postmand CSC samling, hvilket resulterer i oprettelsen af ​​en digital signatur fra en dokumenthash.

Få CSC Info (valgfri)

1. Du kan bruge CSC info anmodning om at få oplysninger om SSL.coms cloud signatur-tjeneste. Bemærk, at i modsætning til de andre i samlingen kræver denne anmodning ikke dit adgangstoken. Vælg for at sende anmodningen CSC info fra CSC API samling, og klik derefter på Send .
   
2. Oplysninger om cloud-signaturtjenesten vises i et JSON-objekt i Postman's Respons felt.
   

cURL-kommando

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

CSC legitimationsoplysninger

1.  CSC legitimationsoplysninger anmodning henter en legitimationsoplysninger, du vil bruge i senere API-anmodninger. Vælg CSC legitimationsoplysninger og klik på Tilladelse fane.
   
2. Vælg Bærertoken fra Type menuen, indsæt dit adgangstoken i Polet , og klik derefter på Send .
   
3. Et JSON-objekt med en liste over legitimations-id'er, der er knyttet til brugeren, vises i Respons Mark. Din liste indeholder sandsynligvis én værdi. Kopier og indsæt dit legitimations-id i en teksteditor til brug i senere anmodninger.
   

cURL-kommando

udskifte MY-ACCESS-TOKEN med dit faktiske adgangstoken:

krøll - placering - anmodning POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN "\ --data-raw" {} "

Hvis du bruger et eseal-certifikat (dokumentsigneringscertifikat med kun organisationsoplysninger; inkluderet med din gratis esigner.com-konto), skal du inkludere "clientData": "DS_ESEAL" (bemærk: eseals kræver ikke OTP-godkendelse). Andre muligheder for "clientData" er "EVCS" for EV Code Signing og "DS" (standard) for IV eller IV+OV Document Signing:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorisation: Bearer MY-ACCESS-TOKEN" \ --data-raw "{\"clientData\": \"DS_ESEAL\"}"

Info om CSC-legitimationsoplysninger (valgfri)

1. Info om CSC-legitimationsoplysninger anmodning returnerer certifikater og andre oplysninger tilknyttet et legitimations-id og er ikke påkrævet for signering. Vælg for at bruge denne anmodning Info om CSC-legitimationsoplysninger fra samlingen, og klik på Tilladelse fane.
   
2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
   
3. Vælg Fylde fanen, og indsæt derefter dit legitimations-id som værdien for credentialID.
   
4. Klik på knappen Send .
   
5. Et JSON-objekt med din signaturcertifikatkæde og andre oplysninger vises i Respons felt.
   

cURL-kommando

udskifte MY-ACCESS-TOKEN , MY-CREDENTIAL-ID med dine faktiske oplysninger:

curl --location --quest POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "certifikater \": \ "kæde \", \ "certInfo \": sandt, \ "authInfo \": sand} "

Legitimationsoplysninger Godkend

1. Legitimationsoplysninger Godkend anmodning henter tilladelse til at underskrive en hash. Begynd med at vælge Legitimationsoplysninger Godkend fra samlingen og klikke på Tilladelse fane.
   
2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
   
3. Vælg Fylde fanen. Indsæt dit legitimations-id som credentialID værdi og en hash af det dokument, du vil underskrive som hash værdi. Hent og indtast en OTP fra din godkendelsesapp, og indtast den som værdien for OTP, og klik derefter på Send .
   
4. Et JSON-objekt med dine signaturaktiveringsdata (SAD) vises i Respons Mark. Kopier og indsæt denne værdi i en teksteditor til brug i anmodningen om hashsignering.
   

cURL-kommando

udskifte MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHog MY-OTP med dine faktiske oplysninger:

krøll - placering - anmodning POST "https://cs-try.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "numSignatures \": 1, \ "hash \": [\ "MY-HASH \ "], \" OTP \ ": \" MY-OTP \ "}"

Underskriv Hash

1. Nu er vi klar til at underskrive dokumentets hash. Vælg Underskriv Hash fra samlingen, og vælg derefter Tilladelse fane.
   
2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
   
3. Vælg Fylde fanen. Indsæt dit legitimations-id som credentialID værdi, dine signaturaktiveringsdata som SAD værdi og en hash af det dokument, du vil underskrive som hash værdi, og klik derefter på Send .
   
4. Et JSON-objekt med din signatur vises i Respons felt.
   

cURL-kommando

udskifte MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADog MY-HASH med dine faktiske oplysninger:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application / json" \ --header "Authorization: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "SAD \": \ "MY-SAD \", \ "hash \": [\ "MY-HASH \"], \ "signAlgo \": \ "1.2.840.113549.1.1.11 \"} "

Skriv en PDF

Ud over at underskrive dokumenthasker kan du også uploade og underskrive en PDF-fil. Start med at downloade og importere Document Signing API Postman-samling (Se https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation for de seneste api-slutpunkter og samlingsdownloads), efter det samme installationstrin du fulgte ovenfor for CSC API -samlingen.

• Upload PDF-dokument
• Underskriv PDF-dokument

Du kan genbruge den legitimationsoplysninger, du har hentet ovenfor med CSC legitimationsoplysninger anmodning. Du bliver sandsynligvis også nødt til at hente en ny adgangstoken.

Upload PDF-dokument

1. Vælg Upload PDF-dokument anmodning og klik på Tilladelse fane.
   
2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
   
3. Vælg Headers fanen og indsæt dit legitimations-id i Værdi kolonne.
   
4. Vælg Fylde fanebladet og klik på knappen × siden hello.pdf for at fjerne dette pladsholderfilnavn.
   
5. Klik på knappen Vælg fil knappen, og naviger derefter til den fil, du vil uploade.
   
6. Klik på knappen Send .
   
7. Vælg og kopier id værdi i svaret, der skal bruges i den næste anmodning.
   

cURL-kommando

udskifte MY-CREDENTIAL-ID, MY-ACCESS-TOKENog /PATH/TO/FILE.pdf med dine faktiske oplysninger:

curl --location --quest POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Authorization: Bearer MY-ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

Bemærk: For synlige signaturer henvises til følgende HTTP-anmodningsoverskrifter (/v1/pdf/upload):

Underskriv PDF-dokument

1. Nu kan du underskrive PDF'en. Vælg Upload PDF-dokument anmodning og klik på Tilladelse fane.
     
2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
   
3. Vælg fanen Krop, og indsæt i id værdi fra det forrige trin.
   
4. Indtast en OTP fra din godkendelsesapp, og klik på Send .
   
5. PDF-dataene vises nedenfor i Respons Mark. Vælge Gem i en fil fra Gem svar menuen, og giv derefter filen et navn.
   
6. Åbn filen i Acrobat for at bekræfte, at filen er underskrevet. (Bemærk, at SSL.com's RSA-udviklingsrod i skærmbilledet nedenfor er blevet betroet manuelt i Acrobat.)
   

cURL-kommando

udskifte MY-CREDENTIAL-ID, MY-FILE-IDog MY-OTP med dine faktiske oplysninger:

krøll - placering - anmodning POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Content-Type : application / json "\ --header" Autorisation: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \", \ "otp \": \ "MY-OTP \"} "

 Går live med produktion

For at gå live skal du fjerne "-tryk" fra underdomænet. For eksempel, for at gå live med ds-try.ssl.com, skal du fjerne “-tryk”, så underdomænet bliver til ds.ssl.com.