Questa guida ti mostrerà come registrare un ordine di certificato di firma del documento con SSL.com firmatario elettronico servizio e utilizzare l'API Cloud Signature Consortium (CSC) per firmare digitalmente un hash del documento e un file PDF. Puoi usare questa guida con entrambi cURL or Postino. Si consiglia agli utenti di Postman di installare il file applicazione desktop per lavorare con gli esempi. Gli esempi in questa guida sono entrambi applicabili agli ambienti di produzione e test di eSigner e eSealing di SSL.com. Le differenze nei comandi tra le modalità di produzione e test sono spiegate nelle sezioni seguenti.
Per seguire queste istruzioni avrai bisogno di:
- Un ordine di certificato di firma del documento convalidato. Si prega di leggere questo come fare per istruzioni complete su ordinazione e convalida.
- A ID cliente (noto anche come un ID dell'applicazione. Per favore riferisci a questo come fare per istruzioni sulla generazione di questa credenziale).
Ordina il tuo certificato di firma del documento SSL.com
Come ordinare un certificato nell'ambiente di produzione
Fare riferimento a questo articolo della guida per le istruzioni su come ordinare un certificato di firma del documento di produzione: Processo di ordinazione per certificati di firma di codici e documenti
Come ordinare un certificato di prova sulla sandbox di SSL.com
SSL.com offre un ambiente Sandbox dedicato, che rispecchia il nostro portale SSL.com live e l'API SWS, per uno spazio di sperimentazione senza rischi. Questa impostazione di "laboratorio" consente agli utenti di esplorare e testare i servizi di SSL.com senza la preoccupazione di causare interruzioni o incorrere in costi effettivi.
L'articolo, Utilizzo di SSL.com Sandbox per test e integrazione, ti aiuterà a orientarti nel processo di creazione di un account Sandbox, avviando un ordine di prova e integrando Sandbox con l'API SWS.
Una volta creato il certificato di prova, contatta il team di supporto di SSL.com per farlo convalidare. Puoi farlo facendo clic sul pulsante della chat online nell'angolo in basso a destra del SSL.com sito web o inviando un'e-mail a support@ssl.com.
Iscriviti a eSigner e configura l'autenticazione a due fattori
Prima di poter iniziare a utilizzare l'API CSC, dovrai iscriverti al servizio di firma cloud eSigner di SSL.com. Gli ordini convalidati possono essere registrati in eSigner seguendo le istruzioni seguenti:
- . Vai a Ordini scheda nel tuo account SSL.com e individua il tuo ordine.
- Fare clic sull'ordine dettagli collegamento.
- 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.
- 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.
- Scansiona il codice in un'app di autenticazione a 2 fattori sul tuo dispositivo mobile, ad esempio Google Authenticator or Authy. L'app ti fornirà password monouso (OTP) da utilizzare durante la firma. Ogni OTP è valida per 30 secondi.
Facoltativo: converti il tuo certificato di firma del documento OV in un certificato di sigillatura
Nota: Questa sezione è riservata solo agli utenti che desiderano eseguire la sigillatura. Per automatizzare la firma dei documenti e non ricevere richieste da One Time Password (OTP), gli utenti convertono automaticamente il proprio certificato di firma dei documenti di convalida dell'organizzazione (OV) in un certificato di sigillatura sui propri account SSL.com. Tieni presente che un certificato di firma del documento di convalida individuale (IV) non può essere convertito per la sigillatura. Le istruzioni per sigillare la conversione sono dettagliate di seguito:
- Clicchi Ordini nel menu in alto del tuo account SSL.com.
- Individua il tuo certificato e fai clic su scaricare / dettagli collegamento.
- Clicca su RIMUOVERE 2FA pulsante.
Installa Postman e importa le raccolte API
Le istruzioni in questa sezione sono solo per gli utenti di Postman. Se stai usando cURL con l'API CSC, puoi passare alla sezione successiva.
- Scarica e decomprimi il Raccolta Postman API CSC ed Raccolta Postman dell'API di firma dei documenti (Vedi https://www.postman.com/sslcom per le raccolte API SSL.com online).
- Scaricare e installare il Postino REST Client.
- Avvia Postman, quindi crea un nuovo account Postman o accedi a uno esistente.
- Clicca su Importare pulsante.
- Clicca su Carica file pulsante, vai ai file di raccolta API decompressi (
csc-api-prod.postman_collection.jsoneddocument-signing-api-prod.postman_collection.json) e aprirli.
- Clicca su Importare pulsante.
- Le richieste API con cui lavorerai sono ora disponibili in Collezioni scheda sul lato sinistro della finestra del postino.
Recupera il token di accesso
Il passaggio successivo consiste nel recuperare un token di accesso da SSL.com. Avrai bisogno del tuo ID cliente disponibile, così come il nome utente e la password per il tuo account SSL.com. I token di accesso sono validi per un'ora dopo l'emissione.
Utilizza le schede cliccabili di seguito per scegliere le istruzioni per Postman o cURL:
- Seleziona una richiesta API dalla raccolta API CSC.
- Seleziona il Autorizzazione Scheda e seleziona OAuth2.0 dal Tipologia menu.
- Immettere le seguenti informazioni nel modulo:
- Prefisso intestazione:
Bearer - Nome del token:
SSLCOM CSC(o qualsiasi altro nome facile da ricordare che preferisci) - Tipo di sovvenzione:
Authorization Code - URL di richiamata:
https://upload.esigner.com - Autorizza utilizzando il browser: incontrollato
- URL di autenticazione:
https://login.ssl.com/oauth2/authorizeper Ambiente di produzione;https://oauth-sandbox.ssl.com/oauth2/authorizeper l'ambiente sandbox. - URL token di accesso:
https://login.ssl.com/oauth2/tokenper Ambiente di produzione;https://oauth-sandbox.ssl.com/oauth2/tokenper l'ambiente sandbox. - Identificativo cliente: [Il tuo ID cliente]
- Client Secret: [Segreto del tuo cliente]
- Scopo:
service - Stato: [lasciare in bianco]
- Autenticazione client:
Send as Basic Auth header
Quando hai finito, fai clic su Ottieni un nuovo token di accesso pulsante.
- Prefisso intestazione:
- Apparirà un modulo di login. Immettere il nome utente e la password di SSL.com, quindi fare clic su Accesso utenti pulsante.
- 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 token per riutilizzarlo nelle richieste di Postman, ma abbiamo riscontrato che è più affidabile copiare e incollare il token direttamente in ciascuna richiesta.
- Utilizzare il comando seguente per richiedere un token di accesso. Sostituisci i valori mostrati in MAIUSCOLO con i tuoi valori effettivi:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{ "client_id" : "IL TUO -CLIENT-ID", "client_secret" : "YOUR-CLIENT-SECRET", "grant_type" : "password", "username" : "YOUR-USERNAME", "password" : "YOUR-PASSSWORD" }' - Dovresti ricevere un oggetto JSON contenente un token di accesso e un token di aggiornamento. Copia il valore del token di accesso da incollare nelle tue richieste API. Non avrai bisogno del token di aggiornamento per questi esempi.
Firma un hash
Ora che hai un token di accesso, puoi iniziare a effettuare richieste API e creare firme. Questa sezione ti guiderà attraverso le cinque richieste disponibili nella raccolta CSC di Postman, con conseguente creazione di una firma digitale da un hash del documento.
- È necessaria una libreria PDF per manipolare il PDF per l'input dell'hash e successivamente incorporare il PKCS#7 nel documento PDF. (es. ApachePDFBox in Java).
- Una libreria Crypto per creare PKCS#7 dalle firme grezze ricevute dall'API eSigner (es. BouncyCastle in Java).
Ottieni informazioni CSC (opzionale)
- È 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.
- Le informazioni sul servizio di firma cloud verranno visualizzate in un oggetto JSON in Postman's Risposta campo.
- Utilizza il comando seguente per ottenere informazioni sul servizio API CSC di SSL.com. Se sei in un ambiente sandbox, usa
https://cs-try.ssl.com/csc/v0/infoanziché.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Content-Type: application / json" \ --data-raw "{}" - Riceverai un oggetto JSON con i dettagli sul servizio:
Elenco delle credenziali CSC
I Elenco delle credenziali CSC request recupererà una credenziale che utilizzerai nelle successive richieste API.
- Seleziona Elenco delle credenziali CSC e fare clic sul Autorizzazione scheda.
- Scegli Token al portatore dal Tipologia menu, incolla il tuo token di accesso nel file Token campo, quindi fare clic sul Invia pulsante.
- 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.
- Immettere il seguente comando. (Sostituisci MY-ACCESS-TOKEN con il tuo vero token di accesso). Se sei in un ambiente sandbox, usa
https://cs-try.ssl.com/csc/v0/credentials/listanziché:
curl --location --request POST "https://cs.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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Autorizzazione: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Dovresti ricevere un oggetto JSON con un elenco di ID credenziali associati all'utente. Il tuo elenco conterrà probabilmente un valore. Copia e incolla l'ID credenziale in un editor di testo da utilizzare nelle richieste successive.
Informazioni sulle credenziali CSC (facoltativo)
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.
- Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
- Seleziona il Corpo scheda, quindi incolla l'ID credenziale come valore per
credentialID.
- Clicca su Invia pulsante.
- Un oggetto JSON con la catena del certificato di firma e altre informazioni apparirà nel file Risposta campo.
- Immettere il seguente comando. Se ti trovi nell'ambiente sandbox, usa
https://cs-try.ssl.com/csc/v0/credentials/infosostituireMY-ACCESS-TOKENedMY-CREDENTIAL-IDcon le tue informazioni reali:
curl --location --request POST "https://cs.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 }' - Dovresti ricevere un oggetto JSON con la catena del certificato di firma e altre informazioni:
Autorizza credenziali
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.
- Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
- Seleziona il Corpo tab. Incolla il tuo ID credenziale come
credentialIDvalore e un hash del documento che desideri firmare comehashvalore. Recupera e inserisci una OTP dalla tua app di autenticazione e inseriscila come valore perOTP, Quindi fare clic sul Invia pulsante. Nota: l'OTP non è richiesto per l'esealing dei certificati.
- 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.
- Usa il seguente comando. Sostituire
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDeMY-HASHcon le tue informazioni reali. Ottieni una password monouso dalla tua applicazione 2FA e usala come valore perMY-OTP. Nota: l'OTP non è richiesto per l'esealing dei certificati.
curl --location --request POST "https://cs.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 " }' - Dovresti ricevere un oggetto JSON con i tuoi dati di attivazione della firma (SAD). Copia e incolla questo valore in un editor di testo da utilizzare nella richiesta di firma hash.
Firma hash
Ora sei pronto per firmare l'hash del documento.
- Seleziona Firma hash dalla raccolta, quindi seleziona il file Autorizzazione scheda.
- Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
- Seleziona il Corpo tab. Incolla il tuo ID credenziale come
credentialIDvalore, i dati di attivazione della firma comeSADvalore e un hash del documento che desideri firmare comehashvalore, quindi fare clic su Invia pulsante.
- Un oggetto JSON con la tua firma apparirà nel file Risposta campo.
- Immettere il seguente comando. Sostituire
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADeMY-HASHcon le tue informazioni reali:
curl --location --request POST "https://cs.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" }' - Dovresti ricevere un oggetto JSON contenente la tua firma.
Firma un PDF
Oltre a firmare gli hash dei documenti, puoi anche caricare e firmare un file PDF.
Quando firmi un PDF, lavorerai con due richieste POST:
- 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
- Seleziona il Carica documento PDF richiesta e fare clic su Autorizzazione scheda.
- Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
- Seleziona il Headers scheda e incolla l'ID credenziale nel file Valore colonna.
- Seleziona il Corpo scheda e fare clic su × accanto a
hello.pdfper rimuovere questo nome di file segnaposto.
- Clicca su Selezionare File , quindi vai al file che desideri caricare.
- Clicca su Invia pulsante.
- Seleziona e copia il file
idvalore nella risposta da utilizzare nella richiesta successiva.
- Usa il seguente comando. Sostituire
MY-CREDENTIAL-ID,MY-ACCESS-TOKENe/PATH/TO/FILE.pdfcon le tue informazioni reali:
curl --location --request POST "https://ds.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 "
- Riceverai un oggetto JSON con un valore per
id. Copia questo valore da utilizzare nella richiesta successiva.
Nota: per le firme visibili, fare riferimento alle seguenti intestazioni di richiesta HTTP (/v1/pdf/upload):
|
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
Ora puoi firmare il PDF.
- Seleziona il Carica documento PDF richiesta e fare clic su Autorizzazione scheda.
- Scegli Token al portatore dal Tipologia menu, quindi incolla il tuo token di accesso nel file Token campo.
- Seleziona la scheda Corpo, incolla il file
idvalore del passaggio precedente e un OTP dall'app di autenticazione, quindi fare clic su Invia pulsante.
- 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.
- Apri il file in Acrobat per confermare che il file è stato firmato.
- Immettere il seguente comando. Sostituire
MY-CREDENTIAL-ID,MY-FILE-IDeOUTPUT-FILENAMEcon le tue informazioni reali. Ottieni una password monouso (OTP) dalla tua app 2FA e inseriscila comeMY-OTP. Nota: l'OTP non è richiesto per l'esealing dei certificati:
curl --location --request POST 'https://ds.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"} '\ - -uscita OUTPUT-FILENAME - cURL scaricherà il file firmato e lo salverà nel nome file specificato:
- Apri il PDF in Acrobat o Acrobat Reader per verificare che la firma sia valida.
