Integrasjonsveiledning for testing av ekstern dokumentsignering med eSigner CSC API

Denne guiden vil lede deg gjennom å signere en dokumenthash og PDF-fil med SSL.com eSigner sky signeringstjeneste og Cloud Signature Consortium (CSC) API. Alle API-forespørseleksempler vises med Postbud, og vi anbefaler å installere Postmann skrivebordsprogram på datamaskinen din hvis du vil arbeide gjennom eksemplene. cURL kommandoeksempler på API-forespørsler er også inkludert.

Opprett en testordre

1. Først må du opprette en dokumentsigneringsordre i Sandkassen. Begynn med å logge på Sandbox-kontoen din og gå til Dashbord fanen.
   
2. Klikk utviklerverktøy.
   
3. Plukke ut eSigner dokumentunderskrift, klikk deretter på Opprett testordre knapp.
   
4. En dialogboks vises. Klikk på OK knapp.
   
5. Finn testordren din, og klikk deretter på detaljer kobling.
   
6. Klikk rediger registrant for å begynne å oppgi søker- og mottakerinformasjon for testordren din. Vær oppmerksom på at siden denne informasjonen ikke vil bli brukt til å utstede et gyldig dokumentsigneringssertifikat, kan du legge inn fiktiv informasjon hvis ønskelig.
   
7. Legg til søkerinformasjon for testsertifikatet, og klikk deretter på Neste >> knapp.
   
8. Skriv inn mottakerinformasjon, og klikk deretter på Neste >> knapp.
   
9. Klikk på Hopp knappen for å hoppe over opplasting av valideringsdokumenter for testsertifikatet.
   
10. Testbestillingen din skal nå ha status på i påvente av validering. Kontakt SSL.com supportteam på Support@SSL.com for å få validert testsertifikatet.
    

Registrer deg i eSigner og sett opp tofaktorautentisering

1. Når testordren din er validert av SSL.com supportpersonale, kan du registrere den i eSigner. Naviger til Mine ordre fanen i SSL.com-sandkassekontoen din, og finn testordren din.
   
2. Klikk på ordren detaljer kobling.
   
3. Opprett og bekreft en firesifret PIN-kode, og klikk deretter på opprette PIN knapp.
   
   Hvis du trenger å tilbakestille eSigner-PIN-koden, kan du lese hvordan du gjør det.
   
4. En QR-kode vises.
   
   Neste gang du laster inn siden på nytt, vil ikke QR-koden være synlig. Hvis du trenger å se eller tilbakestille eSigner QR-koden, kan du lese hvordan du gjør det.
   
5. Skann koden til en 2-faktor autentiseringsapp på mobilenheten din, for eksempel Google Authenticator eller Authy. Appen vil gi deg engangspassord (OTP) som du kan bruke når du signerer. Hver OTP er gyldig i 30 sekunder.
   

Install Postbud og Importer CSC API-samling

1. Last ned og pakke ut CSC API Postman-samling (Se https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation for de nyeste API-endepunktene eller samlingsnedlastinger).
   
2. Last ned og installer Postmann REST Client.
   
3. Start Postman, og opprett deretter en ny Postman-konto eller logg deg på en eksisterende.
   
4. Klikk på Import knapp.
   
5. Klikk på Last opp filer , naviger til den utpakkede API-samlingsfilen (CSC-API.postman_collection.json), og åpne den.
   
6. Klikk på Import knapp.
   
7. Klikk på Kategorier fanen i Postman og utvid CSC API-samlingen for å se de fem POST-forespørslene du skal jobbe med:
   • CSC -informasjon
   • CSC legitimasjonsliste
   • Informasjon om CSC-legitimasjon
   • Legitimasjonsgodkjenning
   • Signer Hash

   

Hent tilgangstoken

1. Neste trinn er å hente et tilgangstoken fra SSL.com. Før du ber om tilgangstoken, trenger du en kunde-ID (også kjent som en Søknads-ID. Vennligst se hvordan du gjør det for instruksjoner om hvordan du genererer denne legitimasjonen).
2. Velg autorisasjon kategorien, velg OAuth 2.0 fra typen og klikk på Få nytt tilgangstoken knapp.
   
3. Skriv inn følgende informasjon i skjemaet:
   • Tokenavn: SandBox CSC (eller et annet lett å huske navn du foretrekker)
   • Tilskuddstype: Godkjennelseskoden
   • URL for tilbakeringing: [la stå tom]
   • Autoriser ved hjelp av nettleser: sjekket
   • Godkjennings-URL: https://oauth-sandbox.ssl.com/oauth2/authorize
   • Tilgangstoken-URL: https://oauth-sandbox.ssl.com/oauth2/token
   • Klient-ID: [Din klient-ID]
   • Klienthemmelighet: [Din klienthemmelighet]
   • Omfang: tjeneste
   • Tilstand: [la stå tom]
   • Klientgodkjenning: Send som Basic Auth-overskrift

   Når du er ferdig, klikker du på Be om token knapp.
   

4. Et påloggingsskjema vises i nettleseren din. Skriv inn SSL.com brukernavnet og passordet ditt, og klikk deretter på Medlem Logg inn knapp.
   
5. Det nye tilgangstokenet ditt skal vises i Postman. Velg tilgangstokenteksten og kopier den til utklippstavlen, og lukk deretter Administrer tilgangstokener dialogboks. Lim inn tilgangstokenet ditt i et tekstredigeringsprogram der du enkelt kan få tilgang til det. Hvert tilgangstoken utløper etter en time.
   
   Du kan også lagre tokenet ditt for gjenbruk i Postbud forespørsler, men vi har funnet ut at det er mest pålitelig å kopiere og lime inn tokenet direkte i hver forespørsel.
   

Signer en Hash

Nå som du har et tilgangstoken, kan du begynne å lage API-forespørsler og lage signaturer. Denne delen vil lede deg gjennom de fem tilgjengelige forespørslene i Postman CSC samling, noe som resulterer i opprettelsen av en digital signatur fra en dokumenthash.

Få CSC-informasjon (valgfritt)

1. Du kan også bruke det CSC -informasjon forespørsel om å få informasjon om SSL.coms nettskytjeneste. Merk at, i motsetning til de andre i samlingen, krever denne forespørselen ikke tilgangstokenet ditt. Velg for å sende forespørselen CSC -informasjon fra CSC API samling, og klikk deretter på sent knapp.
   
2. Informasjon om skysignaturtjenesten vil vises i et JSON-objekt i Postmans Respons feltet.
   

cURL-kommando

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

CSC legitimasjonsliste

1. De CSC legitimasjonsliste forespørsel vil hente en legitimasjon du vil bruke i senere API-forespørsler. Plukke ut CSC legitimasjonsliste og klikk på autorisasjon fanen.
   
2. Velg Bærertoken fra typen menyen, lim inn tilgangstokenet i Pollett og klikk deretter på sent knapp.
   
3. Et JSON-objekt med en liste over legitimasjons-ID-er tilknyttet brukeren vises i Respons felt. Listen din vil sannsynligvis inneholde en verdi. Kopier og lim inn legitimasjons-ID-en din i et tekstredigeringsprogram for bruk i senere forespørsler.
   

cURL-kommando

Erstatt MY-ACCESS-TOKEN med ditt faktiske tilgangstoken:

curl --location --request 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 bruker et eseal-sertifikat (dokumentsigneringssertifikat med kun organisasjonsinformasjon; inkludert med din gratis esigner.com-konto), inkluder deretter "clientData": "DS_ESEAL" (merk: eseals krever ikke OTP-autentisering). Andre alternativer 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 "Authorization: Bearer MY-ACCESS-TOKEN" \ --data-raw "{\"clientData\": \"DS_ESEAL\"}"

Informasjon om CSC-legitimasjon (valgfritt)

1. De Informasjon om CSC-legitimasjon forespørsel vil returnere sertifikater og annen informasjon tilknyttet en legitimasjons-ID, og ​​er ikke nødvendig for signering. Velg for å bruke denne forespørselen Informasjon om CSC-legitimasjon fra samlingen og klikk på autorisasjon fanen.
   
2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
   
3. Velg Body kategorien, og lim deretter inn påloggings-ID-en din som verdien for credentialID.
   
4. Klikk på sent knapp.
   
5. Et JSON-objekt med signeringssertifikatkjeden og annen informasjon vises i Respons feltet.
   

cURL-kommando

Erstatt MY-ACCESS-TOKEN og MY-CREDENTIAL-ID med din faktiske informasjon:

curl --location --request 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 \", \ "certificate \": \ "chain \", \ "certInfo \": true, \ "authInfo \": true} "

Legitimasjonsgodkjenning

1. De Legitimasjonsgodkjenning forespørsel vil hente autorisasjon for signering av en hash. Begynn med å velge Legitimasjonsgodkjenning fra samlingen og klikke på autorisasjon fanen.
   
2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
   
3. Velg Body kategorien. Lim inn legitimasjons-ID-en din som credentialID verdi og en hash av dokumentet du vil signere som hash verdi. Hent og skriv inn en OTP fra autentiseringsappen din, og skriv den inn som verdien for OTP, klikk deretter på sent knapp.
   
4. Et JSON-objekt med signaturaktiveringsdataene dine (SAD) vises i Respons felt. Kopier og lim inn denne verdien i et tekstredigeringsprogram for bruk i hash-signeringsforespørselen.
   

cURL-kommando

Erstatt MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHog MY-OTP med din faktiske informasjon:

curl --location --request 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 \ "}"

Signer Hash

1. Nå er vi klare til å signere dokumenthashen. Plukke ut Signer Hash fra samlingen, og velg deretter autorisasjon fanen.
   
2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
   
3. Velg Body kategorien. Lim inn legitimasjons-ID-en din som credentialID verdi, blir dine signaturaktiveringsdata som SAD verdi, og en hash av dokumentet du vil signere som hash verdi, og klikk deretter på sent knapp.
   
4. Et JSON-objekt med signaturen din vises i Respons feltet.
   

cURL-kommando

Erstatt MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADog MY-HASH med din faktiske informasjon:

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 \"} "

Signer en PDF

I tillegg til å signere dokumenthash, kan du også laste opp og signere en PDF-fil. Begynn med å laste ned 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 siste API-endepunktene og samlingsnedlastingene), følger det samme installasjonstrinn du fulgte ovenfor for CSC API -samlingen.

• Last opp PDF-dokument
• Signer PDF-dokument

Du kan bruke påloggingsinformasjonen du hentet ovenfor med CSC legitimasjonsliste be om. Du må sannsynligvis også hente en ny tilgangstoken.

Last opp PDF-dokument

1. Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
   
2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
   
3. Velg Headers kategorien og lim inn legitimasjons-ID-en din i Verdi kolonne.
   
4. Velg Body kategorien og klikk på × ved siden av hello.pdf for å fjerne dette plassholderfilnavnet.
   
5. Klikk på Velg Fil , og naviger deretter til filen du vil laste opp.
   
6. Klikk på sent knapp.
   
7. Velg og kopier id verdi i svaret som skal brukes i neste forespørsel.
   

cURL-kommando

Erstatt MY-CREDENTIAL-ID, MY-ACCESS-TOKENog /PATH/TO/FILE.pdf med din faktiske informasjon:

curl --location --request 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 "

Merk: For synlige signaturer, se følgende HTTP-forespørselshoder (/v1/pdf/upload):

Signer PDF-dokument

1. Nå kan du signere PDF-en. Velg Last opp PDF-dokument forespørsel og klikk på autorisasjon fanen.
     
2. Velg Bærertoken fra typen menyen, og lim deretter inn tilgangstokenet i Pollett feltet.
   
3. Velg hovedfanen, og lim inn i id verdi fra forrige trinn.
   
4. Skriv inn en OTP fra autentiseringsappen din og klikk på sent knapp.
   
5. PDF-dataene vises nedenfor i Respons felt. Velge Lagre i en fil fra Lagre svar menyen, og gi filen et navn.
   
6. Åpne filen i Acrobat for å bekrefte at filen er signert. (Merk at på SSL-skjermbildet nedenfor har SSL.s RSA-utviklingsrot blitt klarert manuelt i Acrobat.)
   

cURL-kommando

Erstatt MY-CREDENTIAL-ID, MY-FILE-IDog MY-OTP med din faktiske informasjon:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Content-Transfer-Encoding: application / json" \ --header "Content-Type : application / json "\ --header" Autorisasjon: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "id \": \ "MY-FILE-ID \", \ "otp \": \ "MY-OTP \"} "

 Går live med produksjon

For å gå live må du fjerne "-try" fra underdomenet. For eksempel, for å gå live med ds-try.ssl.com, fjern "-try" slik at underdomenet blir ds.ssl.com.