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.

Denne vejledning dækker brug af CSC API i SSL.com's sandkasse testmiljø, så du er velkommen til at eksperimentere med API'en uden at bekymre dig om at blive faktureret. Se vores Sandkassevejledning for instruktioner om opsætning af din Sandbox-konto.

Hvis du er klar til at arbejde med CSC API i SSLcoms produktions eSigner-miljø, bedes du læse Fjern dokumentsignering med eSigner CSC API.

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.
    Sandkasse Dashboard
  2. Klik udviklingsværktøjer.
    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 .
    link til 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.
    rediger registrant
  7. Tilføj ansøgeroplysninger til testcertifikatet, og klik derefter på Næste >> .
    Ansøger Oplysninger
  8. Indtast modtageroplysninger, og klik derefter på Næste >> .
    modtagerinformation
  9. Klik på knappen Spring knappen for at springe over upload af valideringsdokumenter til testcertifikatet.
    Spring over knap
  10. Din testordre skal nu have status som afventer validering. Kontakt SSL.com supportteamet på Support@SSL.com for at få dit testcertifikat valideret.
    afventer validering

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.
    Naviger til ordre
  2. Klik på ordren detaljer .
    link til 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.
    Opret PIN-kode
  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.
    QR kode
  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.
    OTP i Authy

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).
    CSC API Postman Collection
  2. Download og installer Postbudets REST-klient.
    Postmand REST Client download
  3. Start Postman, og opret derefter en ny Postman-konto, eller log ind på en eksisterende.
    Postbogs login
  4. Klik på knappen Importere .
    Import-knap
  5. Klik på knappen Upload filer knap, naviger til den udpakkede API-indsamlingsfil (CSC-API.postman_collection.json), og åbn den.
    Upload filer
  6. Klik på knappen Importere .
    Import-knap
  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

    CSC API-samling

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 .
    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 .
    Få nyt adgangstoken

  4. En loginformular vises i din webbrowser. Indtast dit SSL.com-brugernavn og din adgangskode, og klik derefter på Medlem Login .
    Konto login formular
  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.
    Adgang Token

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 .
    CSC Info Anmodning
  2. Oplysninger om cloud-signaturtjenesten vises i et JSON-objekt i Postman's Respons felt.
    CSC info

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.
    CSC legitimationsoplysninger
  2. Vælg Bærertoken fra Type menuen, indsæt dit adgangstoken i Polet , og klik derefter på Send .
    Tilføj token og send anmodning
  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.
    Legitimations-id

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.
    Info om CSC-legitimationsoplysninger
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    indsæt autorisationstoken
  3. Vælg Fylde fanen, og indsæt derefter dit legitimations-id som værdien for credentialID.
    Indtast legitimations-id
  4. Klik på knappen Send .
    Klik på knappen Send
  5. Et JSON-objekt med din signaturcertifikatkæde og andre oplysninger vises i Respons felt.
    Oplysninger om legitimations-id

cURL-kommando

udskifte MY-ACCESS-TOKEN og 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.
    Legitimationsoplysninger Godkend
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    indsæt token
  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 .
    indtast legitimations-id, hash og OTP
  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.
    SAD

cURL-kommando

udskifte MY-ACCESS-TOKENMY-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.
    Underskriv Hash
  2. Vælg Bærertoken fra Type menuen, og indsæt derefter dit adgangstoken i Polet felt.
    indsæt token
  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 .
    Indsæt SAD og hash, send anmodning
  4. Et JSON-objekt med din signatur vises i Respons felt.
    signatur

cURL-kommando

udskifte MY-ACCESS-TOKENMY-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.

OTP-autorisation er ikke påkrævet, når du signerer med et signeringscertifikat for eseling-dokument. Ignorer alle OTP-parametre i den følgende vejledning, hvis du bruger et underskriftscertifikat for eselling. (Kunder med en eksisterende Organisationens valideringsdokument underskrive certifikat kan kontakte support@ssl.com for at få det konverteret til et eSealing-certifikat.)
Når du underskriver en PDF, arbejder du med to POST-anmodninger:

  • Upload PDF-dokument
  • Underskriv PDF-dokument

Dokumentsignering API -samling

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

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):

Anmodningshoved

Beskrivelse

Legitimations-id

Unikt legitimations-id tildelt nøglen – obligatorisk

Underskrivelse-grund

Tilføj underskriftsgrund for at tilføje i signaturudseende og også i signaturordbog – Valgfrit, f.eks. godkender jeg dette dokument

Signering-Placering

Tilføj signeringssted i signaturordbogen – Valgfrit, f.eks. Houston, Texas

Kontaktoplysninger

Tilføj kontaktoplysninger i signaturordbog – Valgfrit, f.eks. Telefonnummer

Signatur-felt-position

Signaturfeltposition, hvor visuel signatur vises. Formatet er "x,y,bredde,højde" - Valgfri

Sidenummer

Sidenummer, hvor signaturen skal tegnes – Valgfrit

Hånd-signatur

Base64-kodet PNG-billede af håndsignatur – valgfrit




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.
    indsæt token
  3. Vælg fanen Krop, og indsæt i id værdi fra det forrige trin.
    indtast id
  4. Indtast en OTP fra din godkendelsesapp, og klik på Send .
    indtast OTP, 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.
    Gem til en fil
  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.)
    digital signatur i Adobe 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.

Brugere kan signere kode med eSigners Extended Validation Code Signing-funktion. Klik nedenfor for mere info.

LÆR MERE

Twitter
Facebook
LinkedIn
Reddit
E-mail

Hold dig informeret og sikker

SSL.com er en global leder inden for cybersikkerhed, PKI og digitale certifikater. Tilmeld dig for at modtage de seneste industrinyheder, tips og produktmeddelelser fra SSL.com.

Vi vil meget gerne have din feedback

Tag vores undersøgelse og fortæl os dine tanker om dit seneste køb.