PDFHQ-Logo

Dokumente

DokumentationSignierung

eSignature-Anfragen API

Erstelle und bearbeite versionierte Signaturdrafts, platziere und validiere vom Absender zugewiesene Felder, versende explizite Sandbox-Anfragen und rufe signierte Artefakte ab.

Server-seitige API-Schlüssel Signierte Speicher-Uploads

Lebenszyklus der Signaturanfrage — Sandbox zuerst#

PDFHQ eSign unterstützt eine anbieterunabhängige Umschlag-Ressource: Lade ein PDF hoch und verifiziere es mit POST /v1/documents/uploads, erstelle dann einen Signaturanfrage-Entwurf. Entwürfe haben ihre eigene Identität, Unterzeichner und Status getrennt von PDF-Konvertierungsaufgaben.

Aktuelle Version: Nur Dropbox Sign Testmodus. Testdokumente sind mit Wasserzeichen versehen und nicht rechtlich bindend. Der Anbieter versendet seine eigenen Unterzeichner-E-Mails. Live-Signaturanfragen, Enterprise-OAuth-Verbindungen und Produktionstarife sind nicht aktiviert.

Erstelle einen eSignatur-Entwurf
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"Mutual NDA","subject":"Please review and sign","message":"Please sign this agreement.","signers":[{"name":"Alice Example","email":"alice@example.com","order":0},{"name":"Bob Example","email":"bob@example.com","order":1}]}'

Bereite exakte Unterzeichnerfelder und versionierte Entwürfe vor#

Sandbox-Clients können Signatur-, Initialen- und Signaturdatumsfelder auf einem versiegelten, aufrechten, ungeschnittenen US-Letter-PDF platzieren. Öffentliche Rechteckkoordinaten sind von 0 bis 1 relativ zur oberen linken Ecke der Seite normalisiert; die Seitennummer beginnt bei 1. Jeder Unterzeichner muss ein erforderliches Signaturfeld erhalten. Lehne überlappende, fehlende oder außerhalb der Grenzen liegende Platzierungen ab. Für alle anderen Seitengrößen weglassen fields um die angehängte Signaturseite des Anbieters zu nutzen, während die Unterstützung validiert wird.

Positionierten Entwurf mit zwei Unterzeichnern erstellen
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Idempotency-Key: sample-signing-draft-001' \
  -H 'Content-Type: application/json' \
  -d '{"upload_id":"VERIFIED_UPLOAD_UUID","provider":"managed","title":"NDA", "subject":"Sign NDA","message":"Please review and sign","signers":[{"name":"Example One","email":"first@example.test","order":0},{"name":"Example Two","email":"second@example.test","order":1}],"fields":[{"field_id":"first_sig","signer_index":0,"type":"signature","page":1,"rect":{"x":0.10,"y":0.72,"width":0.30,"height":0.08},"required":true},{"field_id":"second_sig","signer_index":1,"type":"signature","page":1,"rect":{"x":0.55,"y":0.72,"width":0.30,"height":0.08},"required":true}]}'

Die Erstellung ist idempotent mit einem optionalen Idempotency-Key. Der gleiche Schlüssel und die gleichen versiegelten Dokumentdaten geben den vorhandenen Entwurf zurück; eine andere Nutzlast gibt 409 zurück. Ein Entwurf kann nur vor dem Versand bearbeitet werden von PATCH /v1/esign/envelopes/ENVELOPE_UUID mit einem vollständigen Ersatz-Feldset und If-Match: 1 von seinem draft_version. Bearbeitungen erhöhen die Version und den Digest. Felder bleiben nach dem Versand unveränderlich.

Verifiziere exakte Quelle und Feldlayout
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Dieser Preflight vergleicht Seitendimensionen und Rotation gegen tatsächliche versiegelte Bytes, nicht Browser-Metadaten. Er ist ratenbegrenzt und schreibgeschützt. Eine bestandene lokale Vorschau bescheinigt keine pixelgenaue Dropbox Sign-Platzierung; überprüfe die tatsächliche Test-Unterzeichnungszeremonie vor der Produktionsaktivierung.

Mit expliziter Test-Bestätigung versenden#

cURL
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/send' \
  -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"confirm_test_mode":true,"draft_version":1}'

# Poll the envelope for status; never auto-retry an uncertain send.
curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID' -H 'x-api-key: YOUR_API_KEY'

Der Provider-Versand wird durch eine explizite serverseitige Konfiguration geschützt und in der Produktion deaktiviert. Anfragen, die Dropbox möglicherweise erreicht haben, aber ihre Antwort verloren haben, geben ein needs_reconciliation und können nicht blind erneut gesendet werden.

Sandbox-Erinnerungen und Stornierung — signierte Callbacks sind maßgeblich#

Nachdem eine Testanfrage gesendet wurde, kann der Absender pro Empfänger innerhalb von 24 Stunden eine Test-E-Mail-Erinnerung ausstellen. Stornierungsanfragen verwenden die Provider-API asynchron; ein HTTP 202 bedeutet nur, dass die Stornierung angefordert wurde, nicht dass Empfänger nicht mehr signieren können. Keine dieser Operationen ist ein produktiver elektronischer Signatur-Workflow.

Fordere eine Erinnerung für einen Empfänger an
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/remind'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"recipient_index":0,"confirm_test_mode":true}'

curl 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/reminders'   -H 'x-api-key: YOUR_API_KEY'

Erinnerungsbestätigungen melden Akzeptanz/Ablehnung/Unsicherheit, nicht tatsächliche E-Mail-Zustellung. Ein versuchter Erinnerungsversuch wird dauerhaft aufgezeichnet, bevor der Anbieter kontaktiert wird; wenn das Netzwerkergebnis unsicher ist, versuche nicht erneut. Nur Aufrufer innerhalb des ursprünglichen Kontos/API-Projekts können Bestätigungen abrufen; Signer-E-Mails sind ausgeschlossen.

Asynchrone Stornierung anfordern; Status überprüfen
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/void'   -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{"reason":"agreement_withdrawn","confirm_test_mode":true}'

curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/sync'   -H 'x-api-key: YOUR_API_KEY'

Stornierung ist nur möglich, während versendet, angesehen oder ausstehend. Teilweise signierte und abgeschlossene Anfragen können nicht von PDFHQ storniert werden. Provider HTTP 200 bedeutet nicht, dass die Umschlag ungültig gemacht wurde. Warte auf eine authentifizierte signature_request_canceled Callback oder bestätigter Anbieterstatus. Antworten wie cancel_uncertain erfordern eine Untersuchung durch den Operator; sende niemals blind erneut ein.

Diese API garantiert nicht die Löschung zuvor gesendeter Einladungen, rechtliche Durchsetzbarkeit, rückwirkende Stornierung einer bestehenden Signatur, automatische Rückerstattungen oder produktionsreife Provider-SLA. Der zukünftige Live-Modus erfordert zentrale kreditbasierte Abrechnung, Identitätsverifizierung, vertragliche Überprüfung und vollständige Staging-Provider-Akzeptanz.

Abruf signierter Dokumente#

Nach einer verifizierten signature_request_downloadable Callback, verwende POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ lädt die fertige PDF von Dropbox in den privaten HQ-Speicher-Namespace herunter. Dann abrufen GET /v1/esign/envelopes/ENVELOPE_UUID/download-url für eine kurzlebige, kontogebundene Ausgabe-URL.

Die Quell-PDF wird niemals über eine kundenspezifische URL gesendet. Wir leiten verifizierte versiegelte Dateibytes an den festen Dropbox-API-Host weiter. Von Anbietern gehostete Unterzeichnerseiten und Anbieter-Audit-Nachweise werden vom ausgewählten Service verwaltet.

Webhook-Sicherheit und Statusübergänge →
PDFHQ-Logo

PDF-Werkzeuge und Dokumentenanalyse. Dokumente vorbereiten, verstehen und bearbeiten.

© 2026 PDFHQ. Alle Rechte vorbehalten.