In diesem Handbuch erfahren Sie, wie Sie eine Bestellung für ein Dokumentensignaturzertifikat bei SSL.com registrieren eSignierer Service und verwenden Sie die CSC-API (Cloud Signature Consortium), um einen Dokument-Hash und eine PDF-Datei digital zu signieren. Sie können diese Anleitung mit beiden verwenden cURL or Postman. Wir empfehlen Postman-Benutzern, das zu installieren Desktop-App zum Durcharbeiten der Beispiele.
Die Beispiele in diesem Handbuch verwenden die eSigner- und eSealing-Produktionsumgebung von SSL.com. Wenn Sie mit der CSC-API in der Sandbox-Testumgebung von SSL.com experimentieren möchten, bevor Sie mit echten Zertifikatbestellungen arbeiten, lesen Sie bitte Integrationshandbuch zum Testen der Remote-Signatur mit der eSigner CSC-API. Wenn Sie die eSigner Sandbox mit einem Demokonto und Zertifikat ausprobieren möchten, lesen Sie bitte eSigner-Demo-Anmeldeinformationen und -Zertifikate für Anmeldeinformationen und Konfigurationsinformationen.
Um diese Anweisungen zu befolgen, benötigen Sie:
- Eine validierte Bestellung eines Dokumentensignaturzertifikats. Bitte lesen Sie diese Anleitung Für vollständige Anweisungen zur Bestellung und Validierung.
- A Kunden-ID (auch bekannt als Anwendungs-ID. Bitte beziehen Sie sich auf diese Anleitung Anweisungen zum Generieren dieses Berechtigungsnachweises).
Melden Sie sich bei eSigner an und richten Sie die Zwei-Faktor-Authentifizierung ein
- Bevor Sie die CSC-API verwenden können, müssen Sie sich bei eSigner registrieren. Navigieren Sie zu Bestellungen Tab in Ihrem SSL.com-Konto und suchen Sie Ihre Bestellung.
- Klicken Sie auf die Bestellung Details Link.
- Erstellen Sie eine und bestätigen Sie eine 4-stellige PIN. Klicken Sie dann auf PIN erstellen .Wenn Sie Ihre eSigner-PIN zurücksetzen müssen, lesen Sie bitte diese Anleitung.
- 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.
- Scannen Sie den Code in eine 2-Faktor-Authentifizierungs-App auf Ihrem Mobilgerät, z Google Authenticator or 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.
Tipp: Sie können eSigner verwenden, um organisationsvalidierte (OV) Signaturzertifikate zwischen Teammitgliedern freizugeben. Lesen Sie bitte Teamfreigabe für eSigner-Dokument- und EV-Codesignaturzertifikate für weitere Instruktionen.
Installieren Sie Postman und importieren Sie API-Sammlungen
Die Anweisungen in diesem Abschnitt gelten nur für Postman-Benutzer. Wenn Sie cURL mit der CSC-API verwenden, können Sie mit dem nächsten Abschnitt fortfahren.
- Downloaden und entpacken Sie die CSC API Postman-Sammlung und Document Signing API Postman-Sammlung (sehen https://www.postman.com/sslcom für Online-SSL.com-API-Sammlungen).
- Downloaden und installieren Sie das Postbote REST Client.
- Starten Sie Postman und erstellen Sie ein neues Postman-Konto oder melden Sie sich bei einem vorhandenen an.
- Klicken Sie auf die Import .
- Klicken Sie auf die Daten hochladen Klicken Sie auf die Schaltfläche, um zu den entpackten API-Sammlungsdateien zu navigieren (
csc-api-prod.postman_collection.jsonunddocument-signing-api-prod.postman_collection.json) und öffne sie.
- Klicken Sie auf die Import .
- Die API-Anforderungen, mit denen Sie arbeiten, sind jetzt in der verfügbar Kollektionen Registerkarte auf der linken Seite des Postbotenfensters.
Zugriffstoken abrufen
Der nächste Schritt besteht darin, ein Zugriffstoken von SSL.com abzurufen. Du wirst deine brauchen Kunden-ID verfügbar, sowie den Benutzernamen und das Passwort für Ihr SSL.com-Konto. Zugriffstoken sind eine Stunde nach ihrer Ausstellung gültig.
Verwenden Sie die anklickbaren Registerkarten unten, um Anweisungen für Postman oder cURL auszuwählen:
Postboten AnweisungencURL Anweisungen
- Wählen Sie eine API-Anforderung aus der CSC-API-Sammlung aus.
- Wähle aus Genehmigung Registerkarte, und wählen Sie OAuth 2.0 von dem Typ Menü.
- Geben Sie die folgenden Informationen in das Formular ein:
- Header-Präfix:
Bearer - Token Name:
SSLCOM CSC(oder einen anderen leicht zu merkenden Namen, den Sie bevorzugen) - Zuschusstyp:
Authorization Code - Rückruf-URL:
https://upload.esigner.com - Mit Browser autorisieren: ungeprüft
- Authentifizierungs-URL:
https://login.ssl.com/oauth2/authorize - Zugriffstoken-URL:
https://login.ssl.com/oauth2/token - Kunden ID: [Ihre Kunden-ID]
- Kundengeheimnis: [Ihr Client-Geheimnis]
- Umfang:
service - Bundesland/ Kanton: [freilassen]
- Client-Authentifizierung:
Send as Basic Auth header
Wenn Sie fertig sind, klicken Sie auf Holen Sie sich ein neues Zugangstoken .
- Header-Präfix:
- Ein Anmeldeformular wird angezeigt. Geben Sie Ihren SSL.com-Benutzernamen und Ihr Passwort ein und klicken Sie auf Mitgliederzugang .
- 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 Ihr Token auch zur Wiederverwendung in Postman-Anfragen speichern. Wir haben jedoch festgestellt, dass es am zuverlässigsten ist, das Token direkt in jede Anfrage zu kopieren und einzufügen.
- Verwenden Sie den folgenden Befehl, um ein Zugriffstoken anzufordern. Ersetzen Sie die in ALL-CAPS angezeigten Werte durch Ihre tatsächlichen Werte:
curl --location --request POST "https://login.ssl.com/oauth2/token" \ --header "Content-Type: application/json" \ --data-raw '{
"client_id" : "IHRE-KUNDEN-ID",
"client_secret": "IHR-KUNDEN-GEHEIMNIS",
"grant_type": "Passwort",
"Benutzername" : "IHR-BENUTZERNAME",
"Passwort" : "IHR-PASSWORT"
}' - Sie sollten ein JSON-Objekt erhalten, das ein Zugriffstoken und ein Aktualisierungstoken enthält. Kopieren Sie den Zugriffstokenwert, um ihn in Ihre API-Anforderungen einzufügen. Für diese Beispiele benötigen Sie das Aktualisierungstoken nicht.
Unterschreibe einen Hash
Nachdem Sie über ein Zugriffstoken verfügen, können Sie API-Anforderungen und Signaturen erstellen. Dieser Abschnitt führt Sie durch die fünf verfügbaren Anforderungen in der Postman CSC-Sammlung, die zur Erstellung einer digitalen Signatur aus einem Dokument-Hash führen.
CSC-Informationen abrufen (optional)
Postboten AnweisungencURL Anweisungen
- 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 .
- Informationen zum Cloud-Signaturdienst werden in einem JSON-Objekt in Postman's angezeigt Antwort Feld.
- Verwenden Sie den folgenden Befehl, um Informationen zum CSC-API-Dienst von SSL.com abzurufen:
curl --location --request POST "https://cs.ssl.com/csc/v0/info" \ --header "Inhaltstyp: application / json" \ --data-raw "{}" - Sie erhalten ein JSON-Objekt mit Details zum Service:
Liste der CSC-Anmeldeinformationen
Der Liste der CSC-Anmeldeinformationen Die Anforderung ruft einen Berechtigungsnachweis ab, den Sie in späteren API-Anforderungen verwenden werden.
Postboten AnweisungencURL Anweisungen
- Auswählen Liste der CSC-Anmeldeinformationen Und klicken Sie auf die Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, fügen Sie Ihren Zugriffstoken in das Token Klicken Sie auf das Feld Absenden .
- 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.
- Geben Sie den folgenden Befehl ein. (Ersetzen Sie MY-ACCESS-TOKEN durch Ihr tatsächliches Zugriffstoken):
curl --location --request POST "https://cs.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.ssl.com/csc/v0/credentials/list" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{"clientData": "DS_ESEAL"}' - Sie sollten ein JSON-Objekt mit einer Liste der dem Benutzer zugeordneten Anmeldeinformations-IDs erhalten. 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.
Informationen zu CSC-Anmeldeinformationen (optional)
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.
Postboten AnweisungencURL Anweisungen
- Um diese Anforderung zu verwenden, wählen Sie Informationen zu CSC-Anmeldeinformationen aus der Sammlung und klicken Sie auf Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Körper Fügen Sie dann Ihre Anmeldeinformations-ID als Wert für ein
credentialID.
- Klicken Sie auf die Absenden .
- Ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen wird in der angezeigt Antwort Feld.
- Geben Sie den folgenden Befehl ein. Ersetzen
MY-ACCESS-TOKENundMY-CREDENTIAL-IDmit Ihren tatsächlichen Informationen:
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/info" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "certificates": "chain", "certInfo": true, "authInfo": true }' - Sie sollten ein JSON-Objekt mit Ihrer Signaturzertifikatskette und anderen Informationen erhalten:
Anmeldeinformationen autorisieren
Der Anmeldeinformationen autorisieren Die Anforderung ruft die Berechtigung zum Signieren eines Hash ab.
Postboten AnweisungencURL Anweisungen
- Beginnen Sie mit der Auswahl Anmeldeinformationen autorisieren aus der Sammlung und klicken Sie auf Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Körper Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein
credentialIDWert und ein Hash des Dokuments, das Sie als signieren möchtenhashWert. Rufen Sie ein OTP aus Ihrer Authentifizierungs-App ab, geben Sie es ein und geben Sie es als Wert für einOTP, Dann klicken Sie auf die Absenden Taste. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich.
- 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.
- Verwenden Sie den folgenden Befehl. Ersetzen
MY-ACCESS-TOKEN,MY-CREDENTIAL-IDundMY-HASHmit Ihren tatsächlichen Informationen. Holen Sie sich ein Einmalkennwort von Ihrer 2FA-Anwendung und verwenden Sie es als Wert fürMY-OTP. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich.
curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "numSignatures": 1, "hash": [ "MY-HASH" ], "OTP": "MY-OTP "}' - Sie sollten ein JSON-Objekt mit Ihren Signaturaktivierungsdaten (SAD) erhalten. Kopieren Sie diesen Wert und fügen Sie ihn in einen Texteditor ein, um ihn in der Hash-Signaturanforderung zu verwenden.
Zeichen Hash
Jetzt können Sie den Dokument-Hash signieren.
Postboten AnweisungencURL Anweisungen
- Auswählen Zeichen Hash Wählen Sie dann aus der Sammlung die aus Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Körper Tab. Fügen Sie Ihre Anmeldeinformations-ID als ein
credentialIDWert, Ihre Signaturaktivierungsdaten alsSADWert und ein Hash des Dokuments, das Sie als signieren möchtenhashWert, dann klicken Sie auf die Absenden .
- Ein JSON-Objekt mit Ihrer Signatur wird in der angezeigt Antwort Feld.
- Geben Sie den folgenden Befehl ein. Ersetzen
MY-ACCESS-TOKEN,MY-CREDENTIAL-ID,MY-SADundMY-HASHmit Ihren tatsächlichen Informationen:
curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer MY- ACCESS-TOKEN" \ --data-raw '{ "credentialID": "MY-CREDENTIAL-ID", "SAD": "MY-SAD", "hash": [ "MY-HASH" ], "signAlgo": "1.2.840.113549.1.1.11" }' - Sie sollten ein JSON-Objekt erhalten, das Ihre Signatur enthält.
Unterschreiben Sie ein PDF
Neben dem Signieren von Dokument-Hashes können Sie auch eine PDF-Datei hochladen und signieren.
Wenn Sie ein PDF signieren, arbeiten Sie mit zwei POST-Anfragen:
- 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
Postboten AnweisungencURL Anweisungen
- Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wähle aus Headers Klicken Sie auf die Registerkarte und fügen Sie Ihre Anmeldeinformations-ID in das Feld ein Wert Spalte.
- Wähle aus Körper Registerkarte und klicken Sie auf die × neben
hello.pdfum diesen Platzhalter-Dateinamen zu entfernen.
- Klicken Sie auf die Datei Auswählen Klicken Sie auf die Schaltfläche und navigieren Sie zu der Datei, die Sie hochladen möchten.
- Klicken Sie auf die Absenden .
- Wählen und kopieren Sie die
idWert in der Antwort, der in der nächsten Anforderung verwendet werden soll.
- Verwenden Sie den folgenden Befehl. Ersetzen
MY-CREDENTIAL-ID,MY-ACCESS-TOKENund/PATH/TO/FILE.pdfmit Ihren tatsächlichen Informationen:
curl --location --request POST "https://ds.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 "
- Sie erhalten ein JSON-Objekt mit dem Wert für
id. Kopieren Sie diesen Wert, um ihn in der nächsten Anforderung zu verwenden.
Hinweis: Informationen zu sichtbaren Signaturen finden Sie in den folgenden HTTP-Anforderungsheadern (/v1/pdf/upload):
|
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 |
|
Signing-Location |
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
Jetzt können Sie das PDF signieren.
Eine OTP-Autorisierung ist nicht erforderlich, wenn Sie mit einem Siegeldokument-Signaturzertifikat signieren. Ignorieren Sie alle OTP-Parameter in der folgenden Anleitung, wenn Sie ein Unterzeichnungszertifikat für ein versiegeltes Dokument verwenden.
Postboten AnweisungencURL Anweisungen
- Wähle aus PDF-Dokument hochladen anfordern und klicken Sie auf die Genehmigung Tab.
- Auswählen
Inhaber-Token von dem Typ Menü, dann fügen Sie Ihr Zugriffstoken in das Token Feld.
- Wählen Sie die Registerkarte Body und fügen Sie sie ein
idWert aus dem vorherigen Schritt und ein OTP aus Ihrer Authentifizierungs-App, klicken Sie dann auf Absenden .
- 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.
- Öffnen Sie die Datei in Acrobat, um zu bestätigen, dass die Datei signiert wurde.
- Geben Sie den folgenden Befehl ein. Ersetzen
MY-CREDENTIAL-ID,MY-FILE-IDundOUTPUT-FILENAMEmit Ihren tatsächlichen Informationen. Holen Sie sich ein Einmalkennwort (OTP) von Ihrer 2FA-App und geben Sie es als einMY-OTP. Hinweis: OTP ist zum Versiegeln von Zertifikaten nicht erforderlich:
curl --location --request POST 'https://ds.ssl.com/v1/pdf/sign' \ --header 'Inhaltsübertragungscodierung: application / json' \ --header 'Inhaltstyp: Anwendung / json '\ --header' Autorisierung: Inhaber MY-ACCESS-TOKEN '\ --data-raw' {"id": "MY-FILE-ID", "otp": "MY-OTP"} '\ - -Ausgabe OUTPUT-FILENAME - cURL lädt die signierte Datei herunter und speichert sie unter dem von Ihnen angegebenen Dateinamen:
- Öffnen Sie die PDF-Datei in Acrobat oder Acrobat Reader, um zu überprüfen, ob die Signatur gültig ist.
