Guida all'integrazione per testare la firma di documenti in remoto con l'API CSC di eSigner

Questa guida ti guiderà attraverso la firma di un hash del documento e di un file PDF con SSL.com firmatario elettronico servizio di firma cloud e API Cloud Signature Consortium (CSC). Tutti gli esempi di richieste API verranno mostrati con Postinoe consigliamo di installare il App desktop Postman sul tuo computer se vuoi lavorare con gli esempi. Sono inclusi anche esempi di comandi cURL delle richieste API.

Crea un ordine di prova

1. Innanzitutto, dovrai creare un ordine di firma del documento nella sandbox. Inizia accedendo al tuo account Sandbox e andando su Performance modelli/hostess scheda.
   
2. Clicchi strumenti di sviluppo.
   
3. Seleziona Firma del documento eSigner, Quindi fare clic sul Crea ordine di prova pulsante.
   
4. Apparirà una finestra di dialogo. Clicca il OK pulsante.
   
5. Individua l'ordine di prova, quindi fai clic su dettagli collegamento.
   
6. Clicchi modifica registrante per iniziare a inserire le informazioni sul richiedente e sul destinatario per l'ordine di prova. Si noti che poiché queste informazioni non verranno utilizzate per emettere un certificato di firma del documento valido, è possibile inserire informazioni fittizie se lo si desidera.
   
7. Aggiungere le informazioni sul richiedente per il certificato di prova, quindi fare clic su Avanti >> pulsante.
   
8. Immettere le informazioni sul destinatario, quindi fare clic su Avanti >> pulsante.
   
9. Clicca su Saltare pulsante per saltare il caricamento dei documenti di convalida per il certificato di prova.
   
10. Il tuo ordine di prova dovrebbe ora avere lo stato in attesa di convalida. Contatta il team di supporto di SSL.com all'indirizzo Support@SSL.com per far convalidare il certificato di prova.
    

Iscriviti a eSigner e configura l'autenticazione a due fattori

1. Una volta che il tuo ordine di prova è stato convalidato dal personale di supporto di SSL.com, puoi registrarlo in eSigner. Vai al file Ordini scheda nel tuo account sandbox SSL.com e individua l'ordine di prova.
   
2. Fare clic sull'ordine dettagli collegamento.
   
3. Crea e conferma un PIN di 4 cifre, quindi fai clic su creare PIN pulsante.
   
   Se è necessario reimpostare il PIN eSigner, leggere questo come fare.
   
4. Apparirà un codice QR.
   
   La prossima volta che ricarichi la pagina, il codice QR non sarà visibile. Se devi visualizzare o reimpostare il codice QR del tuo eSigner, leggi questo come fare.
   
5. Scansiona il codice in un'app di autenticazione a 2 fattori sul tuo dispositivo mobile, come Google Authenticator o Authy. L'app ti fornirà password monouso (OTP) da utilizzare durante la firma. Ogni OTP è valida per 30 secondi.
   

Installazione Postino e importa raccolta API CSC

1. Scarica e decomprimi il Raccolta Postman API CSC (Vedi https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation per gli ultimi endpoint API o download di raccolte).
   
2. Scaricare e installare il Postino REST Client.
   
3. Avvia Postman, quindi crea un nuovo account Postman o accedi a uno esistente.
   
4. Clicca su Importare pulsante.
   
5. Clicca su Carica file pulsante, vai al file di raccolta API decompresso (CSC-API.postman_collection.json) e aprirlo.
   
6. Clicca su Importare pulsante.
   
7. Clicca su Collezioni scheda in Postman ed espandere la raccolta API CSC per visualizzare le cinque richieste POST con cui lavorerai:
   • Informazioni CSC
   • Elenco delle credenziali CSC
   • Informazioni sulle credenziali CSC
   • Autorizza credenziali
   • Firma hash

   

Recupera il token di accesso

1. Il passaggio successivo consiste nel recuperare un token di accesso da SSL.com. Prima di richiedere il tuo token di accesso, avrai bisogno di un file ID cliente (noto anche come un ID dell'applicazione. Per favore riferisci a questo come fare per istruzioni sulla generazione di questa credenziale).
2. Seleziona il Autorizzazione scheda, selezionare OAuth2.0 dal Tipologia menu e fare clic sul Ottieni un nuovo token di accesso pulsante.
   
3. Immettere le seguenti informazioni nel modulo:
   • Nome del token: SandBox CSC (o qualsiasi altro nome facile da ricordare che preferisci)
   • Tipo di sovvenzione: codice di autorizzazione
   • URL di richiamata: [lasciare in bianco]
   • Autorizza utilizzando il browser: controllato
   • URL di autenticazione: https://oauth-sandbox.ssl.com/oauth2/authorize
   • URL token di accesso: https://oauth-sandbox.ssl.com/oauth2/token
   • Identificativo cliente: [Il tuo ID cliente]
   • Client Secret: [Segreto del tuo cliente]
   • Scopo: servizio
   • Stato: [lasciare in bianco]
   • Autenticazione client: Invia come intestazione di autenticazione di base

   Quando hai finito, fai clic su Richiedi token pulsante.
   

4. Un modulo di accesso apparirà nel tuo browser web. Immettere il nome utente e la password di SSL.com, quindi fare clic su Accesso utenti pulsante.
   
5. Il tuo nuovo token di accesso dovrebbe apparire in Postman. Seleziona il testo del token di accesso e copialo negli appunti, quindi chiudi il file Gestisci token di accesso la finestra di dialogo. Incolla il tuo token di accesso in un editor di testo dove puoi accedervi facilmente. Ogni token di accesso scadrà dopo un'ora.
   
   Puoi anche salvare il tuo token per riutilizzarlo in Postino richieste, ma abbiamo scoperto che è più affidabile copiare e incollare il token direttamente in ogni richiesta.
   

Firma un hash

Ora che hai un token di accesso, puoi iniziare a fare richieste API e creare firme. Questa sezione ti guiderà attraverso le cinque richieste disponibili nel Collezione Postino CSC, con conseguente creazione di una firma digitale da un hash del documento.

Ottieni informazioni CSC (opzionale)

1. È possibile utilizzare il Informazioni CSC richiesta di ottenere informazioni sul servizio di firma cloud di SSL.com. Tieni presente che, a differenza delle altre nella raccolta, questa richiesta non richiede il tuo token di accesso. Per inviare la richiesta, selezionare Informazioni CSC dal API CSC raccolta, quindi fai clic su Invia pulsante.
   
2. Le informazioni sul servizio di firma cloud verranno visualizzate in un oggetto JSON in Postman's Risposta campo.
   

Comando cURL

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

Elenco delle credenziali CSC

1. I Elenco delle credenziali CSC request recupererà una credenziale che utilizzerai nelle successive richieste API. Selezionare Elenco delle credenziali CSC e fare clic sul Autorizzazione scheda.
   
2. Scegli Token al portatore dal Tipologia menu, incolla il tuo token di accesso nel file Token campo, quindi fare clic sul Invia pulsante.
   
3. Un oggetto JSON con un elenco di ID credenziali associati all'utente verrà visualizzato nel file Risposta campo. Il tuo elenco conterrà probabilmente un valore. Copia e incolla l'ID credenziale in un editor di testo da utilizzare nelle richieste successive.
   

Comando cURL

sostituire MY-ACCESS-TOKEN con il tuo effettivo token di accesso:

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

Se si utilizza un certificato eseal (certificato di firma del documento con solo informazioni sull'organizzazione; incluso nel proprio account esigner.com gratuito), includere "clientData": "DS_ESEAL" (nota: gli eseal non richiedono l'autenticazione OTP). Altre opzioni per "clientData" sono "EVCS" per EV Code Signing e "DS" (predefinito) per IV o 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\"}"

Informazioni sulle credenziali CSC (facoltativo)

1. I Informazioni sulle credenziali CSC richiesta restituirà certificati e altre informazioni associate a un ID credenziale e non è necessario per la firma. Per utilizzare questa richiesta, seleziona Informazioni sulle credenziali CSC dalla raccolta e fare clic su Autorizzazione scheda.
   
2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
   
3. Seleziona il Corpo scheda, quindi incolla l'ID credenziale come valore per credentialID.
   
4. Clicca su Invia pulsante.
   
5. Un oggetto JSON con la catena del certificato di firma e altre informazioni apparirà nel file Risposta campo.
   

Comando cURL

sostituire MY-ACCESS-TOKEN ed MY-CREDENTIAL-ID con le tue informazioni reali:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application / json" \ --header "Autorizzazione: Bearer MY-ACCESS-TOKEN "\ --data-raw" {\ "credentialID \": \ "MY-CREDENTIAL-ID \", \ "certificates \": \ "chain \", \ "certInfo \": true, \ "authInfo \": true} "

Autorizza credenziali

1. I Autorizza credenziali request recupererà l'autorizzazione per la firma di un hash. Inizia selezionando Autorizza credenziali dalla raccolta e facendo clic su Autorizzazione scheda.
   
2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
   
3. Seleziona il Corpo tab. Incolla il tuo ID credenziale come credentialID valore e un hash del documento che desideri firmare come hash valore. Recupera e inserisci una OTP dalla tua app di autenticazione e inseriscila come valore per OTP, Quindi fare clic sul Invia pulsante.
   
4. Un oggetto JSON con i tuoi dati di attivazione della firma (SAD) apparirà nel file Risposta campo. Copia e incolla questo valore in un editor di testo da utilizzare nella richiesta di firma hash.
   

Comando cURL

sostituire MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHe MY-OTP con le tue informazioni reali:

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

Firma hash

1. Ora siamo pronti per firmare l'hash del documento. Selezionare Firma hash dalla raccolta, quindi seleziona il file Autorizzazione scheda.
   
2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
   
3. Seleziona il Corpo tab. Incolla il tuo ID credenziale come credentialID valore, i dati di attivazione della firma come SAD valore e un hash del documento che desideri firmare come hash valore, quindi fare clic su Invia pulsante.
   
4. Un oggetto JSON con la tua firma apparirà nel file Risposta campo.
   

Comando cURL

sostituire MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADe MY-HASH con le tue informazioni reali:

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

Firma un PDF

Oltre a firmare gli hash dei documenti, puoi anche caricare e firmare un file PDF. Inizia scaricando e importando il file Raccolta Postman dell'API di firma dei documenti (Vedi https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation per gli ultimi endpoint API e download di raccolte), seguendo lo stesso passaggi di installazione hai seguito sopra per la raccolta dell'API CSC.

• Carica documento PDF
• Firma documento PDF

Puoi riutilizzare le credenziali recuperate sopra con l'estensione Elenco delle credenziali CSC richiesta. Probabilmente dovrai anche recuperare un nuovo file token di accesso.

Carica documento PDF

1. Seleziona il Carica documento PDF richiesta e fare clic su Autorizzazione scheda.
   
2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
   
3. Seleziona il Headers scheda e incolla l'ID credenziale nel file Valore colonna.
   
4. Seleziona il Corpo scheda e fare clic su × accanto a hello.pdf per rimuovere questo nome di file segnaposto.
   
5. Clicca su Selezionare File , quindi vai al file che desideri caricare.
   
6. Clicca su Invia pulsante.
   
7. Seleziona e copia il file id valore nella risposta da utilizzare nella richiesta successiva.
   

comando cURL

sostituire MY-CREDENTIAL-ID, MY-ACCESS-TOKENe /PATH/TO/FILE.pdf con le tue informazioni reali:

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

Nota: per le firme visibili, fare riferimento alle seguenti intestazioni di richiesta HTTP (/v1/pdf/upload):

Firma documento PDF

1. Ora puoi firmare il PDF. Seleziona il Carica documento PDF richiesta e fare clic su Autorizzazione scheda.
     
2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
   
3. Seleziona la scheda Corpo e incolla il file id valore dal passaggio precedente.
   
4. Immettere una OTP dall'app di autenticazione e fare clic su Invia pulsante.
   
5. I dati PDF verranno visualizzati sotto nel file Risposta campo. Scegliere Salva in un file dal Salva risposta menu, quindi assegna un nome al file.
   
6. Apri il file in Acrobat per confermare che il file è stato firmato. (Si noti che nella schermata seguente, la radice di RSA Development di SSL.com è stata considerata attendibile manualmente in Acrobat.)
   

Comando cURL

sostituire MY-CREDENTIAL-ID, MY-FILE-IDe MY-OTP con le tue informazioni reali:

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

 Andare in diretta con la produzione

Per andare in diretta, devi rimuovere "-try" dal sottodominio. Ad esempio, per andare in diretta con ds-try.ssl.com, rimuovi "-try" in modo che il sottodominio diventi ds.ssl.com.