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
SSL.com propose un environnement Sandbox dédié, reflétant notre portail SSL.com en direct et notre API SWS, pour un espace d'expérimentation sans risque. Ce paramètre de « laboratoire » permet aux utilisateurs d'explorer et de tester les services de SSL.com sans craindre de provoquer des interruptions ou d'engager des coûts réels.
L'article, Utilisation du bac à sable SSL.com pour les tests et l'intégration, vous aidera à naviguer dans le processus de création d'un compte Sandbox, de lancement d'une commande test et d'intégration de Sandbox à l'API SWS.
Une fois que vous avez créé votre certificat de test, veuillez contacter l'équipe d'assistance SSL.com pour le faire valider. Vous pouvez le faire en cliquant sur le bouton de discussion en ligne dans le coin inférieur droit de l'écran. SSL.com site Web ou en envoyant un e-mail à support@ssl.com.
S'inscrire à eSigner et configurer l'authentification à deux facteurs
Avant de pouvoir commencer à utiliser l'API CSC, vous devrez vous inscrire au service de signature cloud eSigner de SSL.com. Les commandes validées peuvent être inscrites dans eSigner en suivant les instructions ci-dessous :
- . Naviguez vers le 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.
Facultatif : convertissez votre certificat de signature de document OV en certificat e-sealing
Remarque : Cette section est réservée aux utilisateurs qui souhaitent faire du esealing. Pour automatiser la signature de documents et ne pas être invité par les mots de passe à usage unique (OTP), les utilisateurs convertissent eux-mêmes leur certificat de signature de document de validation d'organisation (OV) en un certificat e-sealing sur leurs comptes SSL.com. Veuillez noter qu'un certificat de signature de document de Validation Individuelle (IV) ne peut pas être converti pour être scellé.. Les instructions pour la conversion étanche sont détaillées ci-dessous :
- Cliquez Commandes dans le menu supérieur de votre compte SSL.com.
- Localisez votre certificat et cliquez sur le téléchargement / détails lien.
- Cliquez SUPPRIMER 2FA .
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 Importer .
- Cliquez Téléverser 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 Importer .
- 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.
- Une bibliothèque PDF est nécessaire pour manipuler le PDF pour la saisie de hachage et intégrer ultérieurement le PKCS#7 dans le document PDF. (ex. ApachePDFBox en Java).
- Une bibliothèque Crypto pour créer PKCS#7 à partir de signatures brutes reçues de l'API eSigner (ex. BouncyCastle en Java).
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
Votre Liste des références du SCC request récupérera un identifiant que vous utiliserez dans les demandes d'API ultérieures.
- Choisir Liste des références du SCC Et cliquez sur le Autorisation languette.
- Choisir 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)
Votre 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.
- Choisir Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Corps 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
Votre 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.
- Choisir Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Corps 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.
- Choisir Signer le hachage dans la collection, puis sélectionnez le Autorisation languette.
- Choisir Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token
champ.
- Sélectionnez le Corps 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.
- Choisir 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 Propositions colonne.
- Sélectionnez le Corps 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.
- Choisir 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.
