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.

Dieses Handbuch behandelt die Verwendung der CSC-API in SSL.com Sandkasten Testumgebung, sodass Sie jederzeit mit der API experimentieren können, ohne sich Gedanken über die Abrechnung machen zu müssen. Bitte beachten Sie unsere Sandkastenführer Anweisungen zum Einrichten Ihres Sandbox-Kontos finden Sie hier.

Wenn Sie bereit sind, mit der CSC-API in der eSigner-Produktionsumgebung von SSLcom zu arbeiten, lesen Sie bitte Remote Document Signing mit der eSigner CSC API.

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.
    Sandbox-Dashboard
  2. Klicken Sie auf Kostenlos erhalten und dann auf Installieren. Entwickler-Tools.
    Entwickler-Tools
  3. Auswählen 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.
    Details Link
  6. Klicken Sie auf Kostenlos erhalten und dann auf Installieren. 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.
    Registranten bearbeiten
  7. Fügen Sie Bewerberinformationen für das Testzertifikat hinzu und klicken Sie auf Weiter >> .
    Bewerbungsinformation
  8. Geben Sie die Empfängerinformationen ein und klicken Sie auf Weiter >> .
    Empfängerinformation
  9. Klicken Sie auf die überspringen Schaltfläche zum Überspringen des Hochladens von Validierungsdokumenten für das Testzertifikat.
    Schaltfläche "Überspringen"
  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.
    Bis zur Validierung

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.
    Navigieren Sie zur Bestellung
  2. Klicken Sie auf die Bestellung Details Link.
    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.
    PIN erstellen
  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.
    QR Code
  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.
    OTP in Authy

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).
    CSC API Postboten-Sammlung
  2. Laden Sie die Postbote REST Client.
    Postman REST Client herunterladen
  3. Starten Sie Postman und erstellen Sie ein neues Postman-Konto oder melden Sie sich bei einem vorhandenen an.
    Postbote Login
  4. Klicken Sie auf die Import .
    Schaltfläche "Importieren"
  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.
    Daten hochladen
  6. Klicken Sie auf die Import .
    Schaltfläche "Importieren"
  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

    CSC API-Sammlung

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 Art Menü und klicken Sie auf Holen Sie sich ein neues Zugangstoken .
    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 .
    Holen Sie sich ein neues Zugriffstoken

  4. In Ihrem Webbrowser wird ein Anmeldeformular angezeigt. Geben Sie Ihren SSL.com-Benutzernamen und Ihr Passwort ein und klicken Sie auf Mitgliederzugang .
    Konto-Anmeldeformular
  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.
    Zugangstoken

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 .
    CSC-Info-Anfrage
  2. Informationen zum Cloud-Signaturdienst werden in einem JSON-Objekt in Postman's angezeigt Antwort Feld.
    CSC-Info

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. Das 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.
    Liste der CSC-Anmeldeinformationen
  2. Auswählen Inhaber-Token von dem Art Menü, fügen Sie Ihren Zugriffstoken in das Token Klicken Sie auf das Feld Absenden .
    Token hinzufügen und Anfrage senden
  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.
    ID des Berechtigungsnachweises

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. Das 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.
    Informationen zu CSC-Anmeldeinformationen
  2. Auswählen Inhaber-Token von dem Art Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
    Autorisierungstoken einfügen
  3. Wähle aus Body Fügen Sie dann Ihre Anmeldeinformations-ID als Wert für ein credentialID.
    Geben Sie die ID des Berechtigungsnachweises ein
  4. Klicken Sie auf die Absenden .
    Klicken Sie auf die Schaltfläche Senden
  5. Ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen wird in der angezeigt Antwort Feld.
    ID-Informationen für Anmeldeinformationen

cURL-Befehl

Ersetzen MY-ACCESS-TOKEN und 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. Das 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.
    Anmeldeinformationen autorisieren
  2. Auswählen Inhaber-Token von dem Art Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
    Token einfügen
  3. Wähle aus Body 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 .
    Geben Sie die Anmeldeinformations-ID, den Hash und das OTP ein
  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.
    SAD

cURL-Befehl

Ersetzen MY-ACCESS-TOKENMY-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.
    Zeichen Hash
  2. Auswählen Inhaber-Token von dem Art Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
    Token einfügen
  3. Wähle aus Body 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 .
    SAD und Hash einfügen, Anfrage senden
  4. Ein JSON-Objekt mit Ihrer Signatur wird in der angezeigt Antwort Feld.
    Stempel, Unterschrift

cURL-Befehl

Ersetzen MY-ACCESS-TOKENMY-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.

Beim Signieren mit einem esealing-Dokumentsignaturzertifikat ist keine OTP-Autorisierung erforderlich. Ignorieren Sie alle OTP-Parameter in der folgenden Anleitung, wenn Sie ein E-Signaturzertifikat für Dokumente verwenden. (Kunden mit einer bestehenden Signaturzertifikat für Organisationsvalidierungsdokumente kann kontaktieren support@ssl.com um es in ein eSealing-Zertifikat umwandeln zu lassen.)
Wenn Sie ein PDF signieren, arbeiten Sie mit zwei POST-Anfragen:

  • PDF-Dokument hochladen
  • PDF-Dokument unterschreiben

API-Sammlung zum Signieren von Dokumenten

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.
    PDF-Dokument hochladen
  2. Auswählen Inhaber-Token von dem Art Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
    Token einfügen
  3. Wähle aus Headers Klicken Sie auf die Registerkarte und fügen Sie Ihre Anmeldeinformations-ID in das Feld ein Wert Spalte.
    Fügen Sie dem Header die ID des Berechtigungsnachweises hinzu
  4. Wähle aus Body Registerkarte und klicken Sie auf die × neben hello.pdf um diesen Platzhalter-Dateinamen zu entfernen.
    Platzhalterdatei 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.
    Datei Auswählen
  6. Klicken Sie auf die Absenden .
    Anfrage senden
  7. Wählen und kopieren Sie die id Wert in der Antwort, der in der nächsten Anforderung verwendet werden soll.
    Datei-ID

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):

Anfragekopf

Beschreibung

Credential-ID

Dem Schlüssel zugewiesene eindeutige Anmelde-ID – Obligatorisch

Unterzeichnungsgrund

Fügen Sie einen Unterzeichnungsgrund hinzu, um das Erscheinungsbild der Unterschrift und auch das Unterschriftenwörterbuch hinzuzufügen – Optional, z. B. Ich stimme diesem Dokument zu

Unterzeichnungsort

Signierort im Signaturwörterbuch hinzufügen – Optional, z. B. Houston, Texas

Kontaktinformation

Kontaktinformationen im Signaturwörterbuch hinzufügen – Optional, z. B. Telefonnummer

Signatur-Feld-Position

Signaturfeldposition, an der die visuelle Signatur angezeigt wird. Das Format ist „x,y,Breite,Höhe“ - Optional

Seitennummer

Seitenzahl, wo die Unterschrift gezeichnet werden soll – Optional

Handsignatur

Base64-codiertes PNG-Bild der Handunterschrift – Optional




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. Auswählen Inhaber-Token von dem Art Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
    Token einfügen
  3. Wählen Sie die Registerkarte Body und fügen Sie sie ein id Wert aus dem vorherigen Schritt.
    ID eingeben
  4. Geben Sie ein OTP aus Ihrer Authentifizierungs-App ein und klicken Sie auf Absenden .
    Geben Sie OTP ein und klicken Sie auf Senden
  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.
    In eine Datei speichern
  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.)
    digitale Signatur in Adobe Acrobat

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.

Benutzer können Code mit der Extended Validation Code Signing-Funktion von eSigner signieren. Klicken Sie unten für weitere Informationen.

Weiterlesen

Twitter
Facebook
LinkedIn
Reddit
E-Mail

Bleiben Sie informiert und sicher

SSL.com ist ein weltweit führendes Unternehmen im Bereich Cybersicherheit, PKI und digitale Zertifikate. Melden Sie sich an, um die neuesten Branchennachrichten, Tipps und Produktankündigungen von zu erhalten SSL.com.

Wir würden uns über Ihr Feedback freuen

Nehmen Sie an unserer Umfrage teil und teilen Sie uns Ihre Meinung zu Ihrem letzten Kauf mit.