SSL.com

Signature de documents à distance avec l'API eSigner CSC

Équipe d'assistance SSL.com

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:

Commandez votre certificat de signature de document SSL.com

Vous pouvez ignorer cette section si vous disposez déjà d'un certificat de signature de document émis. Si tel est le cas, veuillez passer à la section suivante qui explique comment inscrire votre certificat dans eSigner.

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.

Haut de Page

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 : 

  1. . Naviguez vers le Mes Commandes onglet dans votre compte SSL.com et localisez votre commande.
    Localiser la commande
  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 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.
Conseil: Vous pouvez utiliser eSigner pour partager des certificats de signature validés par l'organisation (OV) entre vos coéquipiers. Lisez s'il vous plaît Partage d'équipe pour les certificats de signature de documents eSigner et de code EV pour obtenir des instructions.
Haut de Page

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 :

  1. Cliquez Mes Commandes dans le menu supérieur de votre compte SSL.com. 
  2. Localisez votre certificat et cliquez sur le téléchargement / détails lien.
  3. Cliquez SUPPRIMER 2FA .
Haut de Page

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.

  1. Téléchargez et décompressez le Collection CSC API Postman ainsi que Collection Postman API de signature de document (voir https://www.postman.com/sslcom pour les collections d'API SSL.com en ligne).
  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 aux fichiers de collection d'API décompressés (csc-api-prod.postman_collection.json ainsi que document-signing-api-prod.postman_collection.json) et ouvrez-les.
  6. Cliquez L’ .
  7. 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.
Haut de Page

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:

Instructions du facteurInstructions cURL
  1. Sélectionnez une demande d'API dans la collection d'API CSC.
  2. Sélectionnez le Autorisation onglet et sélectionnez OAuth 2.0 du Type menu.
  3. 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/authorize pour l'environnement de production ; https://oauth-sandbox.ssl.com/oauth2/authorize pour l'environnement Sandbox.
    • URL du jeton d'accès: https://login.ssl.com/oauth2/token pour l'environnement de production ; https://oauth-sandbox.ssl.com/oauth2/token pour 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 .

  4. 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 .
  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 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.
  1. 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" }'
  2. 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.
Haut de Page

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.

L'algorithme SHA 256 doit être utilisé pour calculer le hachage du document PDF. 
  1. 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). 
  2. 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)

Instructions du facteurInstructions cURL
  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.
  1. 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 "{}"
  2. Vous recevrez un objet JSON avec des détails sur le service:

Liste des références du SCC

La Liste des références du SCC request récupérera un identifiant que vous utiliserez dans les demandes d'API ultérieures.

Instructions du facteurInstructions cURL
  1. Sélectionnez 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.
  1. 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/list au 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"}'
  2. 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)

La 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.

Instructions du facteurInstructions cURL
  1. 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.
  1. Entrez la commande suivante. Si vous êtes dans l'environnement sandbox, utilisez https://cs-try.ssl.com/csc/v0/credentials/info  remplacer MY-ACCESS-TOKEN ainsi que MY-CREDENTIAL-ID avec 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 }'
  2. Vous devriez recevoir un objet JSON avec votre chaîne de certificats de signature et d'autres informations:

Identifiants Autoriser

La Identifiants Autoriser request récupérera l'autorisation de signer un hachage.

Instructions du facteurInstructions cURL
  1. 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 bouton. Remarque : OTP n'est pas requis pour sceller les certificats.
  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.
  1. Utilisez la commande suivante. Remplacer MY-ACCESS-TOKEN, MY-CREDENTIAL-IDet MY-HASH avec vos informations réelles. Obtenez un mot de passe à usage unique de votre application 2FA et utilisez-le comme valeur pour MY-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 " }'
  2. 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.

Instructions du facteurInstructions cURL
  1. Sélectionnez 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.
  1. Entrez la commande suivante. Remplacer MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SADet MY-HASH avec 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" }'
  2. Vous devriez recevoir un objet JSON contenant votre signature.
Haut de Page

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:

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

Instructions du facteurInstructions cURL
  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.
  1. Utilisez la commande suivante. Remplacer MY-CREDENTIAL-ID, MY-ACCESS-TOKENet /PATH/TO/FILE.pdf avec 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 "
  2. 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) :

En-tête de demande

Description

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.

L'autorisation OTP n'est pas requise lors de la signature à l'aide d'un certificat de signature de document à sceller. Ignorez tous les paramètres OTP dans le guide suivant si vous utilisez un certificat de signature de document à sceller.
Instructions du facteurInstructions cURL
  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 l'onglet Corps, collez dans le id valeur de l'étape précédente et un OTP de votre application d'authentification, puis cliquez sur le Envoyer .
  4. 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.
  5. Ouvrez le fichier dans Acrobat pour confirmer que le fichier a été signé.
  1. Entrez la commande suivante. Remplacer MY-CREDENTIAL-ID, MY-FILE-IDet OUTPUT-FILENAME avec vos informations réelles. Obtenez un mot de passe à usage unique (OTP) de votre application 2FA et saisissez-le comme MY-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
  2. cURL téléchargera le fichier signé et l'enregistrera sous le nom de fichier que vous avez spécifié:
  3. Ouvrez le PDF dans Acrobat ou Acrobat Reader pour vérifier que la signature est valide.

Quitter la version mobile