Guide d'intégration pour tester la signature de documents à distance avec l'API eSigner CSC

Ce guide vous guidera dans la signature d'un hachage de document et d'un fichier PDF avec SSL.com e-signataire service de signature dans le cloud et l'API Cloud Signature Consortium (CSC). Tous les exemples de demande d'API seront affichés avec Facteur, et nous vous recommandons d'installer le Application de bureau Postman sur votre ordinateur si vous souhaitez parcourir les exemples. Des exemples de commande cURL des requêtes API sont également inclus.

Créer une commande de test

1. Tout d'abord, vous devez créer un ordre de signature de document dans le bac à sable. Commencez par vous connecter à votre compte Sandbox et accédez au Tableau de bord languette.
   
2. Cliquez outils de développement.
   
3. Sélectionnez Signature de document eSigner, Puis cliquez sur le Créer une commande de test .
   
4. Une boîte de dialogue apparaîtra. Clique le OK .
   
5. Localisez votre commande de test, puis cliquez sur le bouton détails lien.
   
6. Cliquez modifier le titulaire pour commencer à saisir les informations du candidat et du destinataire pour votre commande de test. Notez que puisque ces informations ne seront pas utilisées pour émettre un certificat de signature de document valide, vous pouvez saisir des informations fictives si vous le souhaitez.
   
7. Ajoutez des informations sur le candidat pour le certificat de test, puis cliquez sur le bouton Suivant >> .
   
8. Saisissez les informations du destinataire, puis cliquez sur le bouton Suivant >> .
   
9. Cliquez Skip pour ignorer le téléchargement des documents de validation pour le certificat de test.
   
10. Votre commande test doit désormais avoir le statut Validation en attente. Contactez l'équipe d'assistance SSL.com au Support@SSL.com pour faire valider votre certificat de test.
    

S'inscrire à eSigner et configurer l'authentification à deux facteurs

1. Une fois votre commande test validée par l'équipe d'assistance SSL.com, vous pouvez l'inscrire dans eSigner. Accédez au Mes Commandes dans votre compte sandbox SSL.com et recherchez votre commande de test.
   
2. Cliquez sur la commande détails lien.
   
3. Créez et confirmez un code PIN à 4 chiffres, puis cliquez sur le bouton créer un code PIN .
   
   Si vous devez réinitialiser votre code PIN eSigner, veuillez lire ce mode d'emploi.
   
4. Un code QR apparaîtra.
   
   La prochaine fois que vous rechargerez la page, le code QR ne sera pas visible. Si vous devez afficher ou réinitialiser votre code QR eSigner, veuillez lire ce mode d'emploi.
   
5. Scannez le code dans une application d'authentification à 2 facteurs sur votre appareil mobile, telle que Google Authenticator ou Authy. L'application vous fournira des mots de passe à usage unique (OTP) à utiliser lors de la signature. Chaque OTP est valide pendant 30 secondes.
   

Installer Facteur et importer la collection d'API CSC

1. Téléchargez et décompressez le Collection CSC API Postman (voir https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation pour les derniers points de terminaison d'API ou les téléchargements de collection).
   
2. Téléchargez et installez le Client REST Postman.
   
3. Lancez Postman, puis créez un nouveau compte Postman ou connectez-vous à un compte existant.
   
4. Cliquez L’ .
   
5. Cliquez Téléverser des fichiers bouton, accédez au fichier de collection d'API décompressé (CSC-API.postman_collection.json) et ouvrez-le.
   
6. Cliquez L’ .
   
7. Cliquez Collections dans Postman et développez la collection d'API CSC pour afficher les cinq requêtes POST avec lesquelles vous travaillerez:
   • Informations sur le SCC
   • Liste des références du SCC
   • Informations sur les informations d'identification du SCC
   • Identifiants Autoriser
   • Signer le hachage

   

Récupérer le jeton d'accès

1. L'étape suivante consiste à récupérer un jeton d'accès sur SSL.com. Avant de demander votre jeton d'accès, vous aurez besoin d'un identité du client (également connu sous le nom d'un ID d'application. Prière de se référer à ce mode d'emploi pour obtenir des instructions sur la génération de ces informations d'identification).
2. Sélectionnez le Autorisation onglet, sélectionnez OAuth 2.0 du Type menu, et cliquez sur le Obtenir un nouveau jeton d'accès .
   
3. Saisissez les informations suivantes dans le formulaire:
   • Nom du jeton: SandBox CSC (ou tout autre nom facile à retenir que vous préférez)
   • Type de subvention: Code d'autorisation
   • URL de rappel: [laisser vide]
   • Autoriser à l'aide du navigateur: vérifié
   • URL d'authentification: https://oauth-sandbox.ssl.com/oauth2/authorize
   • URL du jeton d'accès: https://oauth-sandbox.ssl.com/oauth2/token
   • Identité du client: [Votre identifiant client]
   • Secret du client: [Votre secret client]
   • Portée: service
   • État: [laisser vide]
   • Authentification du client: Envoyer en tant qu'en-tête d'authentification de base

   Lorsque vous avez terminé, cliquez sur le Demande de jeton .
   

4. Un formulaire de connexion apparaîtra dans votre navigateur Web. Saisissez votre nom d'utilisateur et votre mot de passe SSL.com, puis cliquez sur le bouton Accès Membres .
   
5. Votre nouveau jeton d'accès devrait apparaître dans Postman. Sélectionnez le texte du jeton d'accès et copiez-le dans le presse-papiers, puis fermez le Gérer les jetons d'accès boite de dialogue. Collez votre jeton d'accès dans un éditeur de texte où vous pouvez y accéder facilement. Chaque jeton d'accès expirera après une heure.
   
   Vous pouvez également enregistrer votre token pour le réutiliser dans Facteur demandes, mais nous avons constaté qu'il est plus fiable de copier et coller le jeton directement dans chaque demande.
   

Signer un hachage

Maintenant que vous disposez d'un jeton d'accès, vous pouvez commencer à faire des demandes d'API et à créer des signatures. Cette section vous guidera à travers les cinq demandes disponibles dans le Collection du facteur SCC, entraînant la création d'une signature numérique à partir d'un hachage de document.

Obtenir des informations sur le CSC (facultatif)

1. Vous pouvez utiliser le Informations sur le SCC demander des informations sur le service de signature cloud de SSL.com. Notez que, contrairement aux autres de la collection, cette demande ne nécessite pas votre jeton d'accès. Pour envoyer la demande, sélectionnez Informations sur le SCC du API CSC collection, puis cliquez sur le Envoyer .
   
2. Les informations sur le service de signature cloud apparaîtront dans un objet JSON dans Postman's Réponse champ.
   

Commande cURL

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

Liste des références du SCC

1. La Liste des références du SCC request récupérera un identifiant que vous utiliserez dans les demandes d'API ultérieures. Sélectionner Liste des références du SCC Et cliquez sur le Autorisation languette.
   
2. Selectionnez Jeton porteur du Type menu, collez votre jeton d'accès dans le Token puis cliquez sur le champ Envoyer .
   
3. Un objet JSON avec une liste d'identifiants d'identification associés à l'utilisateur apparaîtra dans le Réponse champ. Votre liste contiendra probablement une valeur. Copiez et collez votre ID d'identification dans un éditeur de texte pour une utilisation dans les demandes ultérieures.
   

Commande cURL

remplacer MY-ACCESS-TOKEN avec votre jeton d'accès réel:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorisation: porteur MON-JETON D'ACCÈS "\ --data-raw" {} "

Si vous utilisez un certificat eseal (certificat de signature de document contenant uniquement des informations sur l'organisation ; inclus avec votre compte gratuit esigner.com), incluez « clientData » : « DS_ESEAL » (remarque : les eseals ne nécessitent pas d'authentification OTP). Les autres options pour « clientData » sont « EVCS » pour la signature de code EV et « DS » (par défaut) pour la signature de document IV ou IV+OV :

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Type de contenu : application/json" \ --header "Autorisation : porteur MY-ACCESS-TOKEN" \ --data-raw "{\"clientData\": \"DS_ESEAL\"}"

Informations sur les informations d'identification du SCC (facultatif)

1. La Informations sur les informations d'identification du SCC request renverra les certificats et autres informations associés à un identifiant et n'est pas nécessaire pour la signature. Pour utiliser cette demande, sélectionnez Informations sur les informations d'identification du SCC de la collection et cliquez sur le Autorisation languette.
   
2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
   
3. Sélectionnez le Transformation onglet, puis collez votre identifiant comme valeur de credentialID.
   
4. Cliquez Envoyer .
   
5. Un objet JSON avec votre chaîne de certificats de signature et d'autres informations apparaîtra dans le Réponse champ.
   

Commande cURL

remplacer MY-ACCESS-TOKEN et MY-CREDENTIAL-ID avec vos informations réelles:

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

Identifiants Autoriser

1. La Identifiants Autoriser request récupérera l'autorisation de signer un hachage. Commencez par sélectionner Identifiants Autoriser de la collection et en cliquant sur le Autorisation languette.
   
2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
   
3. Sélectionnez le Transformation languette. Collez votre identifiant comme credentialID valeur et un hachage du document que vous souhaitez signer en tant que hash valeur. Récupérez et entrez un OTP à partir de votre application d'authentification et entrez-le comme valeur pour OTP, Puis cliquez sur le Envoyer .
   
4. Un objet JSON avec vos données d'activation de signature (SAD) apparaîtra dans le Réponse champ. Copiez et collez cette valeur dans un éditeur de texte pour l'utiliser dans la demande de signature de hachage.
   

Commande cURL

remplacer MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASHet MY-OTP avec vos informations réelles:

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

Signer le hachage

1. Nous sommes maintenant prêts à signer le hachage du document. Sélectionner Signer le hachage dans la collection, puis sélectionnez le Autorisation languette.
   
2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
   
3. Sélectionnez le Transformation languette. Collez votre identifiant comme credentialID valeur, vos données d'activation de signature en tant que SAD valeur et un hachage du document que vous souhaitez signer en tant que hash valeur, puis cliquez sur le Envoyer .
   
4. Un objet JSON avec votre signature apparaîtra dans le Réponse champ.
   

Commande cURL

remplacer MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADet MY-HASH avec vos informations réelles:

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

Signer un PDF

En plus de signer des hachages de documents, vous pouvez également télécharger et signer un fichier PDF. Commencez par télécharger et importer le Collection Postman API de signature de document (voir https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation pour les derniers points de terminaison d'API et les téléchargements de collection), en suivant le même étapes d'installation vous avez suivi ci-dessus pour la collection API CSC.

• Télécharger un document PDF
• Signer un document PDF

Vous pouvez réutiliser les informations d'identification que vous avez récupérées ci-dessus avec le Liste des références du SCC demande. Vous devrez probablement également récupérer un nouveau jeton d'accès.

Télécharger un document PDF

1. Sélectionnez le Télécharger un document PDF demandez et cliquez sur le Autorisation languette.
   
2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
   
3. Sélectionnez le En-têtes et collez votre identifiant dans le Valeur colonne.
   
4. Sélectionnez le Transformation onglet et cliquez sur le × à côté de hello.pdf pour supprimer ce nom de fichier d'espace réservé.
   
5. Cliquez Choisir le dossier , puis accédez au fichier que vous souhaitez télécharger.
   
6. Cliquez Envoyer .
   
7. Sélectionnez et copiez le id valeur dans la réponse à utiliser dans la prochaine requête.
   

commande cURL

remplacer MY-CREDENTIAL-ID, MY-ACCESS-TOKENet /PATH/TO/FILE.pdf avec vos informations réelles:

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 "

Remarque : Pour les signatures visibles, veuillez vous reporter aux en-têtes de requête HTTP suivants (/v1/pdf/upload) :

Signer un document PDF

1. Vous pouvez maintenant signer le PDF. Sélectionnez le Télécharger un document PDF demandez et cliquez sur le Autorisation languette.
     
2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
   
3. Sélectionnez l'onglet Corps et collez-le dans le id valeur de l'étape précédente.
   
4. Entrez un OTP à partir de votre application d'authentification et cliquez sur le bouton Envoyer .
   
5. Les données PDF apparaîtront ci-dessous dans le Réponse champ. Choisir Enregistrer dans un fichier du Enregistrer la réponse menu, puis attribuez un nom au fichier.
   
6. Ouvrez le fichier dans Acrobat pour confirmer que le fichier a été signé. (Notez que dans la capture d'écran ci-dessous, la racine de développement RSA de SSL.com a été manuellement approuvée dans Acrobat.)
   

Commande cURL

remplacer MY-CREDENTIAL-ID, MY-FILE-IDet MY-OTP avec vos informations réelles:

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

 Lancer la production

Pour passer en ligne, vous devez supprimer « -try » du sous-domaine. Par exemple, pour mettre en ligne ds-try.ssl.com, supprimez "-try" afin que le sous-domaine devienne ds.ssl.com.