PDFHQ-logo

Documenten

DocumentatieOndertekening

eSignature-verzoeken API

Maak en bewerk versioned handtekeningconcepten, plaats en valideer door afzender toegewezen velden, verzend expliciete sandbox-verzoeken en haal ondertekende artefacten op.

Server-side API-sleutels Ondertekende opslagupload

Levenscyclus van handtekeningaanvraag — eerst sandbox#

PDFHQ eSign ondersteunt een provider-neutrale envelopbron: upload en verifieer één PDF met POST /v1/documents/uploads, maak vervolgens een handtekeningaanvraagconcept. Concepten hebben hun eigen identiteit, ondertekenaars en status, gescheiden van PDF-conversiestaken.

Huidige versie: Dropbox Sign testmodus alleen. Testdocumenten zijn voorzien van een watermerk en juridisch niet bindend. De provider verzendt zijn eigen e-mails voor ondertekenaars. Live handtekeningverzoeken, OAuth-verbindingen voor ondernemingen en productietarieven zijn niet ingeschakeld.

Maak een eSignature-concept
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}]}'

Bereid exacte ondertekenarvelden en versiecontroleerde concepten voor#

Sandbox-clients kunnen handtekening-, initialen- en ondertekeningsdatumvelden op een verzegelde, rechtopstaande, niet-bijgesneden US Letter PDF plaatsen. Openbare rechthoekcoördinaten zijn genormaliseerd van 0 tot 1 ten opzichte van de linkerbovenhoek van de pagina; het paginanummer begint bij 1. Elke ondertekenaar moet een verplicht handtekeningsveld ontvangen. Wijs overlappende, ontbrekende of buiten de grenzen liggende plaatsingen af. Voor alle andere paginaformaten, weglaten fields om de bijgevoegde handtekeningspagina van de provider te gebruiken terwijl ondersteuning wordt gevalideerd.

Gepositioneerde, twee-ondertekenaar-concept maken
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}]}'

Creatie is idempotent met een optioneel Idempotency-Key. Dezelfde sleutel en dezelfde verzegelde document-/conceptgegevens retourneren het bestaande concept; een ander payload retourneert 409. Een concept kan alleen vóór verzending worden bewerkt door PATCH /v1/esign/envelopes/ENVELOPE_UUID met een volledige vervangingsveldset en If-Match: 1 van de draft_version. Bewerkingen verhogen de versie en digest. Velden blijven onveranderbaar na verzending.

Preflight exacte bron- en veldindeling
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Deze preflight vergelijkt paginaafmetingen en rotatie met werkelijke verzegelde bytes, niet met browsermetagegevens. Dit is snelheidsbeperkt en alleen-lezen. Een geslaagde lokale preview garandeert geen pixel-perfecte plaatsing in Dropbox Sign; controleer de werkelijke testtekeningsceremonie voordat u productie activeert.

Verzenden met expliciete testaanvaarding#

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'

Provider dispatch wordt beveiligd door een expliciete serverconfiguratie en is uitgeschakeld in productie. Verzoeken die Dropbox mogelijk hebben bereikt maar hun antwoord verloren hebben, voeren in needs_reconciliation en kunnen niet blind opnieuw worden verzonden.

Sandbox-herinneringen en annulering — ondertekende callbacks zijn gezaghebbend#

Nadat een testaanvraag is verzonden, kan de afzender één testemail-herinnering per ontvanger in 24 uur versturen. Annuleringsaanvragen gebruiken de provider-API asynchroon; een HTTP 202 betekent alleen dat annulering is aangevraagd, niet dat ontvangers niet meer kunnen ondertekenen. Geen van beide operaties is een productie elektronische-handtekeningworkflow.

Vraag één herinneringsmail voor ontvanger aan
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'

Herinneringsbevestigingen rapporteren acceptatie/afwijzing/onzekerheid, niet werkelijke e-mailbezorging. Een geprobeerde herinnering wordt duurzaam vastgelegd voordat de provider wordt gecontacteerd; als het netwerkresultaat onzeker is, probeer niet opnieuw. Alleen bellers binnen het oorspronkelijke account/API-project hebben toegang tot bevestigingen; e-mailadressen van ondertekenaars zijn uitgesloten.

Verzoek asynchrone annulering; inspecteer status
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'

Annulering is alleen toegestaan terwijl verzonden, bekeken of in afwachting van bezorging. Gedeeltelijk ondertekende en voltooide verzoeken kunnen niet vanuit PDFHQ worden geannuleerd. Provider HTTP 200 betekent niet dat de envelop is ingetrokken. Wacht op een geverifieerde signature_request_canceled callback of bevestigde providerstatus. Reacties zoals cancel_uncertain vereisen onderzoek door operator; dien nooit blindelings opnieuw in.

Deze API garandeert niet het verwijderen van eerder verzonden uitnodigingen, juridische handhaving, retroactieve annulering van een bestaande handtekening, automatische terugbetalingen of productie-grade provider SLA. Toekomstige live-modus vereist centrale creditgebaseerde facturering, identiteitsverificatie, contractuele beoordeling en volledige acceptatie van staging-provider.

Ondertekende documentopvraging#

Na een geverifieerde signature_request_downloadable callback, gebruik POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ downloadt de voltooide PDF van Dropbox naar de privé-HQ-opslagnamespace. Haal vervolgens op GET /v1/esign/envelopes/ENVELOPE_UUID/download-url voor een kortstondig, accountgerelateerd uitvoer-URL.

De bron-PDF wordt nooit via een door de klant opgegeven URL verzonden. We sturen geverifieerde verzegelde bestandsbytes door naar de vaste Dropbox API-host. Door de provider gehoste ondertekenarpagina's en auditbewijzen van de provider worden beheerd door de geselecteerde service.

Webhookbeveiliging en statusovergangen →
PDFHQ-logo

PDF-tools en documentintelligentie. Bereid, begrijp en werk met uw documenten.

© 2026 PDFHQ. Alle rechten voorbehouden.