Integrationsleitfaden zum Testen der Remote-Unterzeichnung von Dokumenten mit der eSigner CSC-API

Dieses Handbuch führt Sie durch das Signieren eines Dokument-Hashs und einer PDF-Datei mit SSL.com eSignierer Cloud-Signaturdienst und die CSC-API (Cloud Signature Consortium). Alle API-Anforderungsbeispiele werden mit angezeigt Postman, und wir empfehlen die Installation der Postbote Desktop-App auf Ihrem Computer, wenn Sie die Beispiele durcharbeiten möchten. Beispiele für cURL-Befehle der API-Anforderungen sind ebenfalls enthalten.

Erstellen Sie einen Testauftrag

1. Zunächst müssen Sie in der Sandbox eine Dokumentensignaturreihenfolge erstellen. Melden Sie sich zunächst in Ihrem Sandbox-Konto an und gehen Sie zu Dashboard Tab.
   
2. Klicken Sie Entwickler-Tools.
   
3. Select Signieren von eSigner-Dokumenten, Dann klicken Sie auf die Testauftrag erstellen .
   
4. Ein Dialogfeld wird angezeigt. Drücke den OK .
   
5. Suchen Sie Ihren Testauftrag und klicken Sie auf Details Link.
   
6. Klicken Sie Registranten bearbeiten um mit der Eingabe von Bewerber- und Empfängerinformationen für Ihre Testbestellung zu beginnen. Da diese Informationen nicht zur Ausstellung eines gültigen Signaturzertifikats für Dokumente verwendet werden, können Sie bei Bedarf fiktive Informationen eingeben.
   
7. Fügen Sie Bewerberinformationen für das Testzertifikat hinzu und klicken Sie auf Weiter >> .
   
8. Geben Sie die Empfängerinformationen ein und klicken Sie auf Weiter >> .
   
9. Klicken Sie auf die überspringen Schaltfläche zum Überspringen des Hochladens von Validierungsdokumenten für das Testzertifikat.
   
10. Ihr Testauftrag sollte jetzt den Status haben Bis zur Validierung. Wenden Sie sich an das SSL.com-Supportteam unter Support@SSL.com um Ihr Testzertifikat validieren zu lassen.
    

Melden Sie sich bei eSigner an und richten Sie die Zwei-Faktor-Authentifizierung ein

1. Sobald Ihr Testauftrag von den Mitarbeitern des SSL.com-Supports validiert wurde, können Sie ihn in eSigner registrieren. Navigieren Sie zu Bestellungen Klicken Sie in Ihrem SSL.com-Sandbox-Konto auf die Registerkarte und suchen Sie Ihren Testauftrag.
   
2. Klicken Sie auf die Bestellung Details Link.
   
3. Erstellen und bestätigen Sie eine 4-stellige PIN und klicken Sie dann auf PIN erstellen .
   
   Wenn Sie Ihre eSigner-PIN zurücksetzen müssen, lesen Sie bitte diese Anleitung.
   
4. Ein QR-Code wird angezeigt.
   
   Wenn Sie die Seite das nächste Mal neu laden, wird der QR-Code nicht angezeigt. Wenn Sie Ihren eSigner-QR-Code anzeigen oder zurücksetzen müssen, lesen Sie bitte diese Anleitung.
   
5. Scannen Sie den Code in eine 2-Faktor-Authentifizierungs-App auf Ihrem Mobilgerät, z. B. Google Authenticator oder Authy. Die App stellt Ihnen Einmalkennwörter (OTPs) zur Verfügung, die Sie beim Signieren verwenden können. Jedes OTP ist 30 Sekunden lang gültig.
   

Installieren Postman und CSC-API-Sammlung importieren

1. Downloaden und entpacken Sie die CSC API Postman-Sammlung (sehen https://www.postman.com/sslcom/workspace/public/collection/3420801-f2df0995-1293-45da-8719-73467c9f0ca7?ctx=documentation für die neuesten API-Endpunkte oder Sammlungsdownloads).
   
2. Laden Sie die Postbote REST Client.
   
3. Starten Sie Postman und erstellen Sie ein neues Postman-Konto oder melden Sie sich bei einem vorhandenen an.
   
4. Klicken Sie auf die Import .
   
5. Klicken Sie auf die Daten hochladen Klicken Sie auf die Schaltfläche zur entpackten API-Erfassungsdatei (CSC-API.postman_collection.json) und öffne es.
   
6. Klicken Sie auf die Import .
   
7. Klicken Sie auf die Kollektionen Klicken Sie in Postman auf die Registerkarte und erweitern Sie die CSC-API-Sammlung, um die fünf POST-Anforderungen anzuzeigen, mit denen Sie arbeiten werden:
   • CSC-Info
   • Liste der CSC-Anmeldeinformationen
   • Informationen zu CSC-Anmeldeinformationen
   • Anmeldeinformationen autorisieren
   • Zeichen Hash

   

Zugriffstoken abrufen

1. Der nächste Schritt besteht darin, ein Zugriffstoken von SSL.com abzurufen. Bevor Sie Ihr Zugriffstoken anfordern, benötigen Sie ein Kunden-ID (auch bekannt als Anwendungs-ID. Bitte beziehen Sie sich auf diese Anleitung Anweisungen zum Generieren dieses Berechtigungsnachweises).
2. Wähle aus Genehmigung Registerkarte, wählen Sie OAuth 2.0 von dem Typ Menü und klicken Sie auf Holen Sie sich ein neues Zugangstoken .
   
3. Geben Sie die folgenden Informationen in das Formular ein:
   • Token Name: SandBox CSC (oder ein anderer leicht zu merkender Name, den Sie bevorzugen)
   • Zuschusstyp: Autorisierungscode
   • Rückruf-URL: [freilassen]
   • Mit Browser autorisieren: geprüft
   • Authentifizierungs-URL: https://oauth-sandbox.ssl.com/oauth2/authorize
   • Zugriffstoken-URL: https://oauth-sandbox.ssl.com/oauth2/token
   • Kunden ID: [Ihre Kunden-ID]
   • Kundengeheimnis: [Ihr Client-Geheimnis]
   • Umfang:
   • Bundesland/ Kanton: [freilassen]
   • Client-Authentifizierung: Als Basic Auth-Header senden

   Wenn Sie fertig sind, klicken Sie auf Anfrage Token .
   

4. In Ihrem Webbrowser wird ein Anmeldeformular angezeigt. Geben Sie Ihren SSL.com-Benutzernamen und Ihr Passwort ein und klicken Sie auf Mitgliederzugang .
   
5. Ihr neues Zugriffstoken sollte in Postman angezeigt werden. Wählen Sie den Zugriffstoken-Text aus, kopieren Sie ihn in die Zwischenablage und schließen Sie die Zugriffstoken verwalten Dialogbox. Fügen Sie Ihr Zugriffstoken in einen Texteditor ein, auf den Sie problemlos zugreifen können. Jeder Zugriffstoken läuft nach einer Stunde ab.
   
   Sie können Ihren Token auch zur Wiederverwendung in speichern Postman Anfragen, aber wir haben festgestellt, dass es am zuverlässigsten ist, das Token direkt in jede Anfrage zu kopieren und einzufügen.
   

Unterschreibe einen Hash

Da Sie nun über ein Zugriffstoken verfügen, können Sie damit beginnen, API-Anfragen zu stellen und Signaturen zu erstellen. Dieser Abschnitt führt Sie durch die fünf verfügbaren Anfragen im Postbote CSC-Sammlung, was zur Erstellung einer digitalen Signatur aus einem Dokument-Hash führt.

CSC-Informationen abrufen (optional)

1. Sie können die Verwendung CSC-Info Fordern Sie Informationen zum Cloud-Signaturdienst von SSL.com an. Beachten Sie, dass für diese Anforderung im Gegensatz zu den anderen in der Sammlung kein Zugriffstoken erforderlich ist. Um die Anfrage zu senden, wählen Sie CSC-Info von dem CSC-API Sammlung, dann klicken Sie auf die Absenden .
   
2. Informationen zum Cloud-Signaturdienst werden in einem JSON-Objekt in Postman's angezeigt Antwort Feld.
   

cURL-Befehl

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

Liste der CSC-Anmeldeinformationen

1. Der Liste der CSC-Anmeldeinformationen Die Anforderung ruft einen Berechtigungsnachweis ab, den Sie in späteren API-Anforderungen verwenden werden. Wählen Liste der CSC-Anmeldeinformationen Und klicken Sie auf die Genehmigung Tab.
   
2. Wählen Inhaber-Token von dem Typ Menü, fügen Sie Ihren Zugriffstoken in das Token Klicken Sie auf das Feld Absenden .
   
3. Ein JSON-Objekt mit einer Liste der dem Benutzer zugeordneten Anmeldeinformations-IDs wird in angezeigt Antwort Feld. Ihre Liste wird wahrscheinlich einen Wert enthalten. Kopieren Sie Ihre Anmeldeinformations-ID und fügen Sie sie in einen Texteditor ein, um sie in späteren Anforderungen zu verwenden.
   

cURL-Befehl

Ersetzen MY-ACCESS-TOKEN mit Ihrem tatsächlichen Zugriffstoken:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/list" \ --header "Inhaltstyp: application / json" \ --header "Autorisierung: Inhaber MY-ACCESS-TOKEN "\ --data-raw" {} "

Wenn Sie ein eseal-Zertifikat verwenden (Dokumentensignaturzertifikat mit nur Organisationsinformationen; in Ihrem kostenlosen esigner.com-Konto enthalten), dann fügen Sie „clientData“ ein: „DS_ESEAL“ (Hinweis: eseals erfordern keine OTP-Authentifizierung). Andere Optionen für „clientData“ sind „EVCS“ für EV Code Signing und „DS“ (Standard) für IV oder IV+OV Document Signing:

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

Informationen zu CSC-Anmeldeinformationen (optional)

1. Der Informationen zu CSC-Anmeldeinformationen Die Anforderung gibt Zertifikate und andere Informationen zurück, die mit einer Anmeldeinformations-ID verknüpft sind, und ist für die Signatur nicht erforderlich. Um diese Anforderung zu verwenden, wählen Sie Informationen zu CSC-Anmeldeinformationen aus der Sammlung und klicken Sie auf Genehmigung Tab.
   
2. Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
   
3. Wähle aus Korpus Fügen Sie dann Ihre Anmeldeinformations-ID als Wert für ein credentialID.
   
4. Klicken Sie auf die Absenden .
   
5. Ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen wird in der angezeigt Antwort Feld.
   

cURL-Befehl

Ersetzen MY-ACCESS-TOKEN und dem MY-CREDENTIAL-ID mit Ihren tatsächlichen Informationen:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/credentials/info" \ --header "Inhaltstyp: application / json" \ --header "Autorisierung: Inhaber MY-ACCESS-TOKEN "\ --data-raw" {"credentialID": "MY-CREDENTIAL-ID", "Zertifikate": "Kette", "certInfo": true, "authInfo": true}

Anmeldeinformationen autorisieren

1. Der Anmeldeinformationen autorisieren Die Anforderung ruft die Berechtigung zum Signieren eines Hash ab. Beginnen Sie mit der Auswahl Anmeldeinformationen autorisieren aus der Sammlung und klicken Sie auf Genehmigung Tab.
   
2. Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
   
3. Wähle aus Korpus Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein credentialID Wert und ein Hash des Dokuments, das Sie als signieren möchten hash Wert. Rufen Sie ein OTP aus Ihrer Authentifizierungs-App ab, geben Sie es ein und geben Sie es als Wert für ein OTP, Dann klicken Sie auf die Absenden .
   
4. Ein JSON-Objekt mit Ihren Signaturaktivierungsdaten (SAD) wird im angezeigt Antwort Feld. Kopieren Sie diesen Wert und fügen Sie ihn in einen Texteditor ein, um ihn in der Hash-Signaturanforderung zu verwenden.
   

cURL-Befehl

Ersetzen MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-HASH und MY-OTP mit Ihren tatsächlichen Informationen:

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

Zeichen Hash

1. Jetzt können wir den Dokument-Hash signieren. Wählen Zeichen Hash Wählen Sie dann aus der Sammlung die aus Genehmigung Tab.
   
2. Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
   
3. Wähle aus Korpus Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein credentialID Wert, Ihre Signaturaktivierungsdaten als SAD Wert und ein Hash des Dokuments, das Sie als signieren möchten hash Wert, dann klicken Sie auf die Absenden .
   
4. Ein JSON-Objekt mit Ihrer Signatur wird in der angezeigt Antwort Feld.
   

cURL-Befehl

Ersetzen MY-ACCESS-TOKEN,  MY-CREDENTIAL-ID, MY-SAD und MY-HASH mit Ihren tatsächlichen Informationen:

curl --location --request POST "https://cs-try.ssl.com/csc/v0/signatures/signHash" \ --header "Inhaltstyp: application / json" \ --header "Autorisierung: Inhaber MY-ACCESS-TOKEN "\ --data-raw" {"credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "Hash": ["MY-HASH"], "signAlgo": "1.2.840.113549.1.1.11"} "

Unterschreiben Sie ein PDF

Neben dem Signieren von Dokument-Hashes können Sie auch eine PDF-Datei hochladen und signieren. Beginnen Sie mit dem Herunterladen und Importieren der Document Signing API Postman-Sammlung (sehen https://www.postman.com/sslcom/workspace/public/collection/3454644-277d8427-f749-4a94-93bf-c3478b79b999?ctx=documentation für die neuesten API-Endpunkte und Sammlungs-Downloads), folgen Sie dem gleichen Installationsschritte Sie sind oben für die CSC-API-Sammlung gefolgt.

• PDF-Dokument hochladen
• PDF-Dokument unterschreiben

Sie können den oben abgerufenen Berechtigungsnachweis mit dem wiederverwenden Liste der CSC-Anmeldeinformationen Anfrage. Sie müssen wahrscheinlich auch eine neue abrufen Zugangstoken.

PDF-Dokument hochladen

1. Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
   
2. Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
   
3. Wähle aus Headers Klicken Sie auf die Registerkarte und fügen Sie Ihre Anmeldeinformations-ID in das Feld ein Wert Spalte.
   
4. Wähle aus Korpus Registerkarte und klicken Sie auf die × neben hello.pdf um diesen Platzhalter-Dateinamen zu entfernen.
   
5. Klicken Sie auf die Datei Auswählen Klicken Sie auf die Schaltfläche und navigieren Sie zu der Datei, die Sie hochladen möchten.
   
6. Klicken Sie auf die Absenden .
   
7. Wählen und kopieren Sie die id Wert in der Antwort, der in der nächsten Anforderung verwendet werden soll.
   

Befehl cURL

Ersetzen MY-CREDENTIAL-ID, MY-ACCESS-TOKEN und /PATH/TO/FILE.pdf mit Ihren tatsächlichen Informationen:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/upload" \ --header "Berechtigungsnachweis-ID: MY-CREDENTIAL-ID" \ --header "Autorisierung: Inhaber MY-ACCESS-TOKEN "\ --header" Inhaltstyp: application / pdf "\ --data-binary" @ / PATH / TO / FILE.pdf "

Hinweis: Informationen zu sichtbaren Signaturen finden Sie in den folgenden HTTP-Anforderungsheadern (/v1/pdf/upload):

PDF-Dokument unterschreiben

1. Jetzt können Sie das PDF unterschreiben. Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
     
2. Wählen Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
   
3. Wählen Sie die Registerkarte Body und fügen Sie sie ein id Wert aus dem vorherigen Schritt.
   
4. Geben Sie ein OTP aus Ihrer Authentifizierungs-App ein und klicken Sie auf Absenden .
   
5. Die PDF-Daten werden unten in der angezeigt Antwort Feld. Wählen In einer Datei speichern von dem Antwort speichern Menü, dann geben Sie der Datei einen Namen.
   
6. Öffnen Sie die Datei in Acrobat, um zu bestätigen, dass die Datei signiert wurde. (Beachten Sie, dass im folgenden Screenshot das RSA-Entwicklungsstammverzeichnis von SSL.com in Acrobat manuell als vertrauenswürdig eingestuft wurde.)
   

cURL-Befehl

Ersetzen MY-CREDENTIAL-ID, MY-FILE-ID und MY-OTP mit Ihren tatsächlichen Informationen:

curl --location --request POST "https://ds-try.ssl.com/v1/pdf/sign" \ --header "Inhaltsübertragungscodierung: application / json" \ --header "Inhaltstyp : application / json "\ --header" Autorisierung: Inhaber MY-ACCESS-TOKEN "\ --data-raw" {"id": "MY-FILE-ID", "otp": \ "MY-OTP \"} "

 Mit der Produktion live gehen

Um live zu gehen, müssen Sie „-try“ aus der Subdomain entfernen. Um beispielsweise mit ds-try.ssl.com live zu gehen, entfernen Sie „-try“, damit die Subdomain zu ds.ssl.com wird.