Ce guide vous montrera comment inscrire une commande de certificat de signature de document avec SSL.com e-signataire service et utilisez l'API Cloud Signature Consortium (CSC) pour signer numériquement un hachage de document et un fichier PDF. Vous pouvez utiliser ce guide avec cURL or Facteur. Nous recommandons aux utilisateurs de Postman d'installer le application de bureau pour travailler sur les exemples. Les exemples de ce guide s'appliquent à la fois aux environnements de production et de test eSigner et eSealing de SSL.com. Les différences de commandes entre les modes de production et de test sont expliquées dans les sections suivantes.
Pour suivre ces instructions, vous aurez besoin de:
- Une commande de certificat de signature de document validée. Lisez s'il vous plaît ce mode d'emploi pour des instructions complètes sur la commande et la validation.
- A 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).
Commandez votre certificat de signature de document SSL.com
Comment commander un certificat dans l'environnement de production
Veuillez vous référer à cet article du guide pour savoir comment commander un certificat de signature de document de production : Processus de commande des certificats de signature de code et de document
Comment commander un certificat de test sur la Sandbox de SSL.com
- 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.
- Cliquez outils de développement.
- Sélectionnez Signature de document eSigner, Puis cliquez sur le Créer une commande de test .
- Une boîte de dialogue apparaîtra. Clique le OK .
- Localisez votre commande de test, puis cliquez sur le bouton détails lien.
- 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.
- Ajoutez des informations sur le candidat pour le certificat de test, puis cliquez sur le bouton Suivant >> .
- Saisissez les informations du destinataire, puis cliquez sur le bouton Suivant >> .
- Cliquez Skip pour ignorer le téléchargement des documents de validation pour le certificat de test.
- 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
- Avant de pouvoir commencer à utiliser l'API CSC, vous devez vous inscrire à eSigner. Accédez au Mes Commandes onglet dans votre compte SSL.com et localisez votre commande.
- Cliquez sur la commande détails lien.
- 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.
- 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.
- Scannez le code dans une application d'authentification à 2 facteurs sur votre appareil mobile, telle que Authentificateur Google or 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 Postman et importer des collections d'API
Les instructions de cette section sont destinées aux utilisateurs de Postman uniquement. Si vous utilisez cURL avec l'API CSC, vous pouvez passer à la section suivante.
- Téléchargez et décompressez le Collection CSC API Postman et Collection Postman API de signature de document (voir https://www.postman.com/sslcom pour les collections d'API SSL.com en ligne).
- Téléchargez et installez le Client REST Postman.
- Lancez Postman, puis créez un nouveau compte Postman ou connectez-vous à un compte existant.
- Cliquez L’ .
- Cliquez Transférer des fichiers bouton, accédez aux fichiers de collection d'API décompressés (
csc-api-prod.postman_collection.jsonetdocument-signing-api-prod.postman_collection.json) et ouvrez-les.
- Cliquez L’ .
- Les requêtes API avec lesquelles vous allez travailler sont désormais disponibles dans le Collections onglet sur le côté gauche de la fenêtre Postman.
Récupérer le jeton d'accès
L'étape suivante consiste à récupérer un jeton d'accès sur SSL.com. Vous aurez besoin de votre identité du client disponible, ainsi que le nom d'utilisateur et le mot de passe de votre compte SSL.com. Les jetons d'accès sont valables une heure après leur émission.
Utilisez les onglets cliquables ci-dessous pour choisir les instructions pour Postman ou cURL:
- Sélectionnez une demande d'API dans la collection d'API CSC.
- Sélectionnez le Autorisation onglet et sélectionnez OAuth 2.0 du Type menu.
- Saisissez les informations suivantes dans le formulaire:
- Préfixe d'en-tête:
Bearer - Nom du jeton:
SSLCOM CSC(ou tout autre nom facile à retenir que vous préférez) - Type de subvention:
Authorization Code - URL de rappel:
https://upload.esigner.com - Autoriser à l'aide du navigateur: incontrôlé
- URL d'authentification:
https://login.ssl.com/oauth2/authorizepour l'environnement de production ;https://oauth-sandbox.ssl.com/oauth2/authorizepour l'environnement Sandbox. - URL du jeton d'accès:
https://login.ssl.com/oauth2/tokenpour l'environnement de production ;https://oauth-sandbox.ssl.com/oauth2/tokenpour l'environnement Sandbox. - Identité du client: [Votre identifiant client]
- Secret du client: [Votre secret client]
- Portée:
service - État: [laisser vide]
- Authentification du client:
Send as Basic Auth header
Lorsque vous avez terminé, cliquez sur le Obtenir un nouveau jeton d'accès .
- Préfixe d'en-tête:
- Un formulaire de connexion apparaîtra. Saisissez votre nom d'utilisateur et votre mot de passe SSL.com, puis cliquez sur le bouton Accès Membres .
- 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 jeton pour le réutiliser dans les demandes Postman, mais nous avons constaté qu'il est plus fiable de copier et coller le jeton directement dans chaque demande.
- Utilisez la commande suivante pour demander un jeton d'accès. Remplacez les valeurs affichées en MAJUSCULES par vos valeurs réelles:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Type de contenu : application/json" \ --data-raw '{ "id_client" : "VOTRE -CLIENT-ID", "client_secret" : "VOTRE-CLIENT-SECRET", "grant_type" : "mot de passe", "nom d'utilisateur" : "VOTRE-NOM D'UTILISATEUR", "mot de passe" : "VOTRE-MOT DE PASSE" }' - Vous devriez recevoir un objet JSON contenant un jeton d'accès et un jeton d'actualisation. Copiez la valeur du jeton d'accès à coller dans vos requêtes API. Vous n'aurez pas besoin du jeton d'actualisation pour ces exemples.
Signer un hachage
Maintenant que vous disposez d'un jeton d'accès, vous pouvez commencer à faire des requêtes API et à créer des signatures. Cette section vous guidera à travers les cinq demandes disponibles dans la collection Postman CSC, résultant en la création d'une signature numérique à partir d'un hachage de document.
Obtenir des informations sur le CSC (facultatif)
- 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 .
- Les informations sur le service de signature cloud apparaîtront dans un objet JSON dans Postman's Réponse champ.
- Utilisez la commande suivante pour obtenir des informations sur le service API CSC de SSL.com. Si vous êtes dans un environnement sandbox, utilisez
https://cs-try.ssl.com/csc/v0/infoà la place.
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Type de contenu: application / json" \ --data-raw "{}" - Vous recevrez un objet JSON avec des détails sur le service:
Liste des références du SCC
Les Liste des références du SCC request récupérera un identifiant que vous utiliserez dans les demandes d'API ultérieures.
- Sélectionnez Liste des références du SCC Et cliquez sur le Autorisation languette.
- Selectionnez Jeton porteur du Type menu, collez votre jeton d'accès dans le Token
puis cliquez sur le champ Envoyer .
- 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.
- Entrez la commande suivante. (Remplacez MY-ACCESS-TOKEN par votre jeton d'accès actuel). Si vous êtes dans un environnement sandbox, utilisez
https://cs-try.ssl.com/csc/v0/credentials/listau lieu:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application / json" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN "\ --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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type : application/json" \ --header "Autorisation : Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Vous devriez recevoir un objet JSON avec une liste d'identifiants d'identification associés à l'utilisateur. Votre liste contiendra probablement une valeur. Copiez et collez votre identifiant d'identification dans un éditeur de texte pour une utilisation dans les demandes ultérieures.
Informations sur les informations d'identification du SCC (facultatif)
Les Informations sur les informations d'identification du SCC request renverra les certificats et autres informations associées à 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.
- Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Body onglet, puis collez votre identifiant comme valeur de
credentialID.
- Cliquez Envoyer .
- Un objet JSON avec votre chaîne de certificats de signature et d'autres informations apparaîtra dans le Réponse champ.
- Entrez la commande suivante. Si vous êtes dans l'environnement sandbox, utilisez
https://cs-try.ssl.com/csc/v0/credentials/inforemplacerMY-ACCESS-TOKENetMY-CREDENTIAL-IDavec vos informations réelles:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type : application/json" \ --header "Autorisation : Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": vrai, "authInfo": vrai }' - Vous devriez recevoir un objet JSON avec votre chaîne de certificats de signature et d'autres informations:
Identifiants Autoriser
Les 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.
- Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Body languette. Collez votre identifiant comme
credentialIDvaleur et un hachage du document que vous souhaitez signer en tant quehashvaleur. Récupérez et entrez un OTP à partir de votre application d'authentification et entrez-le comme valeur pourOTP, Puis cliquez sur le Envoyer bouton. Remarque : OTP n'est pas requis pour sceller les certificats.
- 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.
- Utilisez la commande suivante. Remplacer
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDetMY-HASHavec vos informations réelles. Obtenez un mot de passe à usage unique de votre application 2FA et utilisez-le comme valeur pourMY-OTP. Remarque : OTP n'est pas requis pour sceller les certificats.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type : application/json" \ --header "Autorisation : Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MON-OTP " }' - Vous devriez recevoir un objet JSON avec vos données d'activation de signature (SAD). Copiez et collez cette valeur dans un éditeur de texte pour l'utiliser dans la demande de signature de hachage.
Signer le hachage
Vous êtes maintenant prêt à signer le hachage du document.
- Sélectionnez Signer le hachage dans la collection, puis sélectionnez le Autorisation languette.
- Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Body languette. Collez votre identifiant comme
credentialIDvaleur, vos données d'activation de signature en tant queSADvaleur et un hachage du document que vous souhaitez signer en tant quehashvaleur, puis cliquez sur le Envoyer .
- Un objet JSON avec votre signature apparaîtra dans le Réponse champ.
- Entrez la commande suivante. Remplacer
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADetMY-HASHavec vos informations réelles:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type : application/json" \ --header "Autorisation : Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Vous devriez recevoir un objet JSON contenant votre signature.
Signer un PDF
En plus de signer des hachages de documents, vous pouvez également télécharger et signer un fichier PDF.
Lors de la signature d'un PDF, vous travaillerez avec deux demandes POST:
- 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
- Sélectionnez le Télécharger un document PDF demandez et cliquez sur le Autorisation languette.
- Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le En-têtes et collez votre identifiant dans le Valeur colonne.
- Sélectionnez le Body onglet et cliquez sur le × à côté de
hello.pdfpour supprimer ce nom de fichier d'espace réservé.
- Cliquez Choisir le dossier , puis accédez au fichier que vous souhaitez télécharger.
- Cliquez Envoyer .
- Sélectionnez et copiez le
idvaleur dans la réponse à utiliser dans la prochaine requête.
- Utilisez la commande suivante. Remplacer
MY-CREDENTIAL-ID,MY-ACCESS-TOKENet/PATH/TO/FILE.pdfavec vos informations réelles:
curl --location --request POST "https://ds.ssl.com/v1/pdf/upload" \ --header "Credential-Id: MY-CREDENTIAL-ID" \ --header "Autorisation: Bearer MY- ACCESS-TOKEN "\ --header" Content-Type: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "
- Vous recevrez un objet JSON avec une valeur pour
id. Copiez cette valeur à utiliser dans la prochaine demande.
Remarque : Pour les signatures visibles, veuillez vous reporter aux en-têtes de requête HTTP suivants (/v1/pdf/upload) :
|
ID d'identification |
ID d'identification unique attribué à la clé - Obligatoire |
|
Signature-Raison |
Ajouter un motif de signature à ajouter dans l'apparence de la signature et également dans le dictionnaire de signature - Facultatif, par exemple, j'approuve ce document |
|
Lieu de signature |
Ajouter l'emplacement de signature dans le dictionnaire de signature - Facultatif, par exemple Houston, Texas |
|
Informations de contact |
Ajouter des informations de contact dans le dictionnaire de signature - Facultatif, par exemple, numéro de téléphone |
|
Position du champ de signature |
Position du champ de signature où la signature visuelle s'affiche. La forme est "x, y, largeur, hauteur" - Optionnel |
|
Numéro de page |
Numéro de page où dessiner la signature - Facultatif |
|
Signature à la main |
Image PNG encodée en Base64 de la signature manuscrite – Facultatif |
Signer un document PDF
Vous pouvez maintenant signer le PDF.
- Sélectionnez le Télécharger un document PDF demandez et cliquez sur le Autorisation languette.
- Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez l'onglet Corps, collez dans le
idvaleur de l'étape précédente et un OTP de votre application d'authentification, puis cliquez sur le Envoyer .
- 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.
- Ouvrez le fichier dans Acrobat pour confirmer que le fichier a été signé.
- Entrez la commande suivante. Remplacer
MY-CREDENTIAL-ID,MY-FILE-IDetOUTPUT-FILENAMEavec vos informations réelles. Obtenez un mot de passe à usage unique (OTP) de votre application 2FA et saisissez-le commeMY-OTP. Remarque : OTP n'est pas requis pour sceller les certificats :
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Content-Transfer-Encoding: application / json' \ --header 'Content-Type: application / json '\ --header' Autorisation: Support MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -sortie OUTPUT-FILENAME - cURL téléchargera le fichier signé et l'enregistrera sous le nom de fichier que vous avez spécifié:
- Ouvrez le PDF dans Acrobat ou Acrobat Reader pour vérifier que la signature est valide.
