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.

Questa guida copre l'uso dell'API CSC in SSL.com sandbox ambiente di test, così puoi sentirti libero di sperimentare con l'API senza preoccuparti di essere fatturato. Si prega di fare riferimento al nostro Guida sandbox per istruzioni sulla configurazione del tuo account Sandbox.

Se sei pronto per lavorare con l'API CSC nell'ambiente eSigner di produzione di SSLcom, leggi Firma remota dei documenti con eSigner CSC API.

Crea un ordine di prova

Se desideri saltare la creazione di un account Sandbox e l'ordine di prova, puoi anche provare eSigner Sandbox con un account demo e un certificato. Si prega di leggere Credenziali e certificati demo eSigner per credenziali e informazioni di configurazione.
  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.
    Pannello sandbox
  2. Clicchi strumenti di sviluppo.
    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.
    collegamento dettagli
  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.
    modifica registrante
  7. Aggiungere le informazioni sul richiedente per il certificato di prova, quindi fare clic su Avanti >> pulsante.
    Informazioni del richiedente
  8. Immettere le informazioni sul destinatario, quindi fare clic su Avanti >> pulsante.
    informazioni sul destinatario
  9. Clicca su Saltare pulsante per saltare il caricamento dei documenti di convalida per il certificato di prova.
    Pulsante Salta
  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.
    in attesa di convalida

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.
    Vai all'ordine
  2. Fare clic sull'ordine dettagli collegamento.
    collegamento dettagli
  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.
    Crea PIN
  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.
    QR Code
  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.
    OTP ad Authy

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).
    Raccolta postino API CSC
  2. Scaricare e installare il Postino REST Client.
    Download del client REST di Postman
  3. Avvia Postman, quindi crea un nuovo account Postman o accedi a uno esistente.
    Login postino
  4. Clicca su Importare pulsante.
    Pulsante di importazione
  5. Clicca su Carica file pulsante, vai al file di raccolta API decompresso (CSC-API.postman_collection.json) e aprirlo.
    Carica file
  6. Clicca su Importare pulsante.
    Pulsante di importazione
  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

    Raccolta API CSC

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.
    Ottieni un nuovo token di accesso
  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.
    Ottieni un nuovo token di accesso

  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.
    Modulo di accesso all'account
  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.
    Token di accesso

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.
    Richiesta informazioni CSC
  2. Le informazioni sul servizio di firma cloud verranno visualizzate in un oggetto JSON in Postman's Risposta campo.
    Informazioni CSC

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. Le 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.
    Elenco delle credenziali CSC
  2. Scegli Token al portatore dal Tipologia menu, incolla il tuo token di accesso nel file Token campo, quindi fare clic sul Invia pulsante.
    Aggiungi token e invia richiesta
  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.
    ID credenziale

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. Le 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.
    Informazioni sulle credenziali CSC
  2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
    incolla il token di autorizzazione
  3. Seleziona il Corpo scheda, quindi incolla l'ID credenziale come valore per credentialID.
    Immettere l'ID credenziale
  4. Clicca su Invia pulsante.
    Fare clic sul pulsante di invio
  5. Un oggetto JSON con la catena del certificato di firma e altre informazioni apparirà nel file Risposta campo.
    Informazioni sull'ID credenziale

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. Le Autorizza credenziali request recupererà l'autorizzazione per la firma di un hash. Inizia selezionando Autorizza credenziali dalla raccolta e facendo clic su Autorizzazione scheda.
    Autorizza credenziali
  2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
    incolla il token
  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.
    inserisci ID credenziale, hash e OTP
  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.
    SAD

Comando cURL

sostituire MY-ACCESS-TOKENMY-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.
    Firma hash
  2. Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
    incolla il token
  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.
    Incolla SAD e hash, invia richiesta
  4. Un oggetto JSON con la tua firma apparirà nel file Risposta campo.
    firma

Comando cURL

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

L'autorizzazione OTP non è richiesta quando si firma utilizzando un certificato di firma del documento sigillante. Ignora tutti i parametri OTP nella seguente guida se utilizzi un certificato di firma del documento sigillante. (Clienti con un file esistente Certificato di firma del documento di convalida dell'organizzazione può contattare support@ssl.com per convertirlo in un certificato eSealing.)
Quando firmi un PDF, lavorerai con due richieste POST:

  • Carica documento PDF
  • Firma documento PDF

Raccolta API per la firma dei documenti

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

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

Intestazione richiesta

Descrizione

ID-credenziale

ID credenziale univoco assegnato alla chiave – Obbligatorio

Firma-Motivo

Aggiungi il motivo della firma da aggiungere nell'aspetto della firma e anche nel dizionario delle firme – Facoltativo, ad es. Approvo questo documento

Firma-Posizione

Aggiungi la posizione della firma nel dizionario delle firme – Facoltativo, ad esempio Houston, Texas

Informazioni di contatto

Aggiungi le informazioni di contatto nel dizionario delle firme – Opzionale, ad es. Numero di telefono

Posizione campo firma

Posizione del campo della firma in cui viene visualizzata la firma visiva. Il formato è "x,y,larghezza,altezza" - Facoltativo

Numero di pagina

Numero di pagina dove disegnare la firma – Facoltativo

Firma a mano

Immagine PNG con codifica Base64 della firma manuale – Opzionale




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.
    incolla il token
  3. Seleziona la scheda Corpo e incolla il file id valore dal passaggio precedente.
    inserire l'ID
  4. Immettere una OTP dall'app di autenticazione e fare clic su Invia pulsante.
    inserisci OTP e fai clic su Invia
  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.
    Salva in un 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.)
    firma digitale in Adobe 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.

Gli utenti possono firmare il codice con la funzionalità Extended Validation Code Signing di eSigner. Clicca sotto per maggiori informazioni.

SCOPRI DI PIÙ

Twitter
Facebook
LinkedIn
Reddit
E-mail

Rimani informato e sicuro

SSL.com è un leader globale nella sicurezza informatica, PKI e certificati digitali. Iscriviti per ricevere le ultime notizie del settore, suggerimenti e annunci di prodotti da SSL.com.

Ci piacerebbe il tuo feedback

Partecipa al nostro sondaggio e facci sapere cosa ne pensi del tuo recente acquisto.