Logo PDFHQ

Dokumen

DokumentasiPenandatanganan

API permintaan eSignature

Buat dan edit draf tanda tangan berversi, tempatkan dan validasi bidang yang ditugaskan pengirim, kirim permintaan sandbox eksplisit, dan ambil artefak yang ditandatangani.

Kunci API sisi server Unggahan penyimpanan yang ditandatangani

Siklus hidup permintaan tanda tangan — sandbox terlebih dahulu#

PDFHQ eSign mendukung sumber daya amplop netral penyedia: unggah dan verifikasi satu PDF dengan POST /v1/documents/uploads, kemudian buat draf permintaan tanda tangan. Draf memiliki identitas, penandatangan, dan status terpisah dari tugas konversi PDF.

Rilis saat ini: Mode uji Dropbox Sign saja. Dokumen uji memiliki watermark dan tidak mengikat secara hukum. Penyedia mengirim email penandatangan sendiri. Permintaan tanda tangan langsung, koneksi OAuth perusahaan, dan tarif produksi tidak diaktifkan.

Buat draf eSignature
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}]}'

Siapkan bidang penandatangan yang tepat dan draf versi#

Klien Sandbox dapat menempatkan tanda tangan, inisial, dan bidang tanggal penandatanganan pada PDF US Letter yang tersegel, tegak, dan tidak dipotong. Koordinat persegi panjang publik dinormalisasi dari 0 hingga 1 relatif terhadap sudut kiri atas halaman; nomor halaman dimulai dari 1. Setiap penandatangan harus menerima bidang tanda tangan yang diperlukan. Tolak penempatan yang tumpang tindih, hilang, atau di luar batas. Untuk semua ukuran halaman lainnya, abaikan fields untuk menggunakan halaman tanda tangan tambahan penyedia saat dukungan sedang divalidasi.

Buat draf dengan posisi, dua penandatangan
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}]}'

Pembuatan bersifat idempoten dengan opsional Idempotency-Key. Kunci yang sama dan data dokumen/draf yang disegel yang sama mengembalikan draf yang ada; muatan berbeda mengembalikan 409. Draf hanya dapat diedit sebelum pengiriman oleh PATCH /v1/esign/envelopes/ENVELOPE_UUID dengan set bidang pengganti lengkap dan If-Match: 1 dari draft_version. Edit menambah versi dan ringkasan. Bidang tetap tidak berubah setelah pengiriman.

Preflight tata letak sumber dan bidang yang tepat
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Preflight ini membandingkan dimensi halaman dan rotasi terhadap byte tersegel aktual, bukan metadata browser. Ini dibatasi laju dan hanya-baca. Pratinjau lokal yang berhasil tidak memastikan penempatan piksel-sempurna Dropbox Sign; tinjau upacara penandatanganan uji aktual sebelum aktivasi produksi.

Kirim dengan pengakuan tes eksplisit#

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'

Pengiriman penyedia dijaga oleh konfigurasi server-side eksplisit dan dinonaktifkan dalam produksi. Permintaan yang mungkin telah mencapai Dropbox tetapi kehilangan respons mereka masuk needs_reconciliation dan tidak dapat dikirim ulang secara membabi buta.

Pengingat sandbox dan pembatalan — callback yang ditandatangani bersifat otoritatif#

Setelah permintaan uji dikirim, pengirim dapat mengeluarkan satu pengingat email uji per penerima dalam 24 jam. Permintaan pembatalan menggunakan API penyedia secara asinkron; HTTP 202 hanya berarti pembatalan diminta, bukan bahwa penerima tidak dapat lagi menandatangani. Tidak ada operasi yang merupakan alur kerja tanda tangan elektronik produksi.

Minta pengingat penerima satu kali
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'

Laporan pengingat melaporkan penerimaan/penolakan/ketidakpastian, bukan pengiriman email aktual. Pengingat yang dicoba dicatat secara tahan lama sebelum menghubungi penyedia; jika hasil jaringan tidak pasti, jangan coba lagi. Hanya pemanggil dalam akun/proyek API asli yang dapat mengakses tanda terima; email penandatangan dikecualikan.

Minta pembatalan asinkron; periksa 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'

Pembatalan hanya diizinkan saat dikirim, dilihat, atau menunggu pengiriman. Permintaan yang ditandatangani sebagian dan selesai tidak dapat dibatalkan dari PDFHQ. HTTP 200 penyedia tidak berarti amplop telah dibatalkan. Tunggu untuk signature_request_canceled status callback atau penyedia yang dikonfirmasi. Respons seperti cancel_uncertain memerlukan investigasi operator; jangan pernah kirim ulang secara membabi buta.

API ini tidak menjanjikan penghapusan undangan yang sebelumnya dikirim email, penegakan hukum, pembatalan retroaktif tanda tangan yang ada, pengembalian dana otomatis, atau SLA penyedia tingkat produksi. Mode langsung di masa depan memerlukan penagihan berbasis kredit pusat, verifikasi identitas, tinjauan kontrak, dan penerimaan penyedia staging yang lengkap.

Pengambilan dokumen yang ditandatangani#

Setelah diverifikasi signature_request_downloadable callback, gunakan POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ mengunduh PDF yang selesai dari Dropbox ke namespace penyimpanan HQ pribadi. Kemudian ambil GET /v1/esign/envelopes/ENVELOPE_UUID/download-url untuk URL output yang berumur pendek dan bersifat akun.

PDF sumber tidak pernah dikirim melalui URL yang ditentukan pelanggan. Kami meneruskan byte file tersegel yang diverifikasi ke host API Dropbox tetap. Halaman penandatangan yang dihosting penyedia dan bukti audit penyedia dikelola oleh layanan yang dipilih.

Keamanan webhook dan transisi status →
Logo PDFHQ

Alat PDF dan intelijen dokumen. Siapkan, pahami, dan bekerja dengan dokumen Anda.

© 2026 PDFHQ. Semua hak dilindungi.