Signature de documents à distance avec l'API eSigner CSC

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

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

Si vous souhaitez ignorer la création d'un compte Sandbox et la commande de test, vous pouvez également essayer l'eSigner Sandbox avec un compte de démonstration et un certificat. Lisez s'il vous plaît Informations d'identification et certificats de démonstration eSigner pour les informations d'identification et de configuration.
  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.
    Tableau de bord Sandbox
  2. Cliquez outils de développement.
    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.
    lien de détails
  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.
    modifier le titulaire
  7. Ajoutez des informations sur le candidat pour le certificat de test, puis cliquez sur le bouton Suivant >> .
    information relative aux demandeurs
  8. Saisissez les informations du destinataire, puis cliquez sur le bouton Suivant >> .
    Renseignements sur le destinataire
  9. Cliquez Skip pour ignorer le téléchargement des documents de validation pour le certificat de test.
    Bouton Ignorer
  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.
    Validation en attente

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

  1. 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.
    Localiser la commande
  2. Cliquez sur la commande détails lien.
    détails
  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.
    Créer un code PIN
  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.
    code QR
  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.
    OTP dans Authy
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.

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 .

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 et Collection Postman API de signature de document (voir https://www.postman.com/sslcom pour les collections d'API SSL.com en ligne).
    Collections du facteur
  2. Téléchargez et installez le Client REST Postman.
    Téléchargement du client Postman REST
  3. Lancez Postman, puis créez un nouveau compte Postman ou connectez-vous à un compte existant.
    Connexion Postman
  4. Cliquez L’ .
    Bouton d'importation
  5. Cliquez Transférer des fichiers bouton, accédez aux fichiers de collection d'API décompressés (csc-api-prod.postman_collection.json et document-signing-api-prod.postman_collection.json) et ouvrez-les.
    Transférer des fichiers
  6. Cliquez L’ .
    Cliquez sur le bouton d'importation
  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.
    Demandes d'API

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.
    sélectionner la demande d'API
  2. Sélectionnez le Autorisation onglet et sélectionnez OAuth 2.0 du Type menu.
    Onglet Autorisation
  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 .
    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 .
    Connexion au compte
  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.
    Jeton d'accès
  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.
    Récupérer le jeton d'accès

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 .
    Envoyer une demande d'informations CSC
  2. Les informations sur le service de signature cloud apparaîtront dans un objet JSON dans Postman's Réponse champ.
    Informations sur le SCC
  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:
    Obtenir des informations sur le SCC

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.
    Onglet Autorisation
  2. Selectionnez Jeton porteur du Type menu, collez votre jeton d'accès dans le Token puis cliquez sur le champ Envoyer .
    Envoyer une demande de liste d'informations d'identification
  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.
    Identifiants d'identification
  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.
    Identifiants d'identification

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.
    onglet d'autorisation
  2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
    Coller le jeton
  3. Sélectionnez le Transformation onglet, puis collez votre identifiant comme valeur de credentialID.
    Coller l'ID d'identification
  4. Cliquez Envoyer .
    Envoyer
  5. Un objet JSON avec votre chaîne de certificats de signature et d'autres informations apparaîtra dans le Réponse champ.
    Informations d'identification
  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 et 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:
    Informations sur les informations d'identification du SCC

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.
    Onglet Autorisation
  2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
    coller le jeton
  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.
    Onglet Corps
  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.
    SAD
  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.
    Identifiants Autoriser

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.
    Onglet Autorisation
  2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
    Coller le jeton
  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 .
    Onglet Corps
  4. Un objet JSON avec votre signature apparaîtra dans le Réponse champ.
    Signature
  1. Entrez la commande suivante. Remplacer MY-ACCESS-TOKENMY-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.
    Signer le hachage

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

Collection d'API de signature de documents

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.
    Onglet Autorisation
  2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
    Coller le jeton
  3. Sélectionnez le En-têtes et collez votre identifiant dans le Valeur colonne.
    Onglet En-têtes
  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é.
    supprimer le nom de fichier d'exemple
  5. Cliquez Choisir le dossier , puis accédez au fichier que vous souhaitez télécharger.
    Choisir le dossier
  6. Cliquez Envoyer .
    Envoyer
  7. Sélectionnez et copiez le id valeur dans la réponse à utiliser dans la prochaine requête.
    ID
  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.
    Télécharger le PDF

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.
       Autorisation
  2. Selectionnez Jeton porteur du Type menu, puis collez votre jeton d'accès dans le Token champ.
    Coller le jeton
  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 .
    Envoyer la demande
  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.
    Enregistrer le PDF dans un fichier
  5. Ouvrez le fichier dans Acrobat pour confirmer que le fichier a été signé.
    Signature valide
  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é:
    Signer le PDF
  3. Ouvrez le PDF dans Acrobat ou Acrobat Reader pour vérifier que la signature est valide.
    Signature valide

Twitter
Facebook
LinkedIn
Reddit
Email

Restez informé et en sécurité

SSL.com est un leader mondial de la cybersécurité, PKI et les certificats numériques. Inscrivez-vous pour recevoir les dernières nouvelles de l'industrie, des conseils et des annonces de produits de SSL.com.

Nous aimerions recevoir vos commentaires

Répondez à notre enquête et faites-nous part de votre avis sur votre récent achat.