API richieste di firma elettronica
Crea e modifica bozze di firma con versione, posiziona e convalida i campi assegnati dal mittente, invia richieste sandbox esplicite e recupera gli artefatti firmati.
Ciclo di vita della richiesta di firma — prima la sandbox#
PDFHQ eSign supporta una risorsa envelope neutrale dal provider: carica e verifica un PDF con POST /v1/documents/uploads, quindi crea una bozza di richiesta di firma. Le bozze hanno identità propria, firmatari e stato separati dai compiti di conversione PDF.
Versione attuale: Modalità test Dropbox Sign. I documenti di test sono contrassegnati con filigrana e non hanno valore legale. Il provider invia i propri email ai firmatari. Le richieste di firma in diretta, le connessioni OAuth enterprise e le tariffe di produzione non sono abilitate.
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}]}'Prepara campi firmatario esatti e bozze versionate#
I client Sandbox possono posizionare campi firma, iniziali e data di firma su un PDF US Letter sigillato, verticale e non ritagliato. Le coordinate del rettangolo pubblico sono normalizzate da 0 a 1 rispetto all'angolo in alto a sinistra della pagina; il numero di pagina inizia da 1. Ogni firmatario deve ricevere un campo firma obbligatorio. Rifiuta posizionamenti sovrapposti, mancanti o fuori dai limiti. Per tutti gli altri formati di pagina, ometti fields per utilizzare la pagina di firma aggiunta dal provider mentre il supporto è in fase di convalida.
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}]}'La creazione è idempotente con un Idempotency-Key. La stessa chiave e gli stessi dati di documento/bozza sigillati restituiscono la bozza esistente; un payload diverso restituisce 409. Una bozza può essere modificata solo prima dell'invio da PATCH /v1/esign/envelopes/ENVELOPE_UUID con un set di campi di sostituzione completo e If-Match: 1 da draft_version. Le modifiche incrementano la versione e il digest. I campi rimangono immutabili dopo l'invio.
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
-H 'x-api-key: YOUR_API_KEY'Questo preflight confronta le dimensioni della pagina e la rotazione rispetto ai byte sigillati effettivi, non ai metadati del browser. È limitato in frequenza e di sola lettura. Un'anteprima locale superata non certifica il posizionamento pixel-perfect di Dropbox Sign; rivedi la cerimonia di firma di prova effettiva prima dell'attivazione in produzione.
Invia con riconoscimento test esplicito#
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'L'invio del provider è protetto da una configurazione esplicita lato server e disabilitato in produzione. Le richieste che potrebbero aver raggiunto Dropbox ma hanno perso la loro risposta entrano needs_reconciliation e non possono essere reinviati alla cieca.
Promemoria sandbox e annullamento — i callback firmati sono autorevoli#
Dopo l'invio di una richiesta di test, il mittente può inviare un promemoria email di test per destinatario ogni 24 ore. Le richieste di annullamento utilizzano l'API del provider in modo asincrono; un HTTP 202 significa solo che l'annullamento è stato richiesto, non che i destinatari non possono più firmare. Nessuna operazione è un flusso di lavoro di firma elettronica in produzione.
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'I rapporti di ricezione dei promemoria indicano accettazione/rifiuto/incertezza, non l'effettiva consegna dell'email. Un tentativo di promemoria viene registrato durevolmente prima di contattare il provider; se il risultato della rete è incerto, non riprovare. Solo i chiamanti all'interno dell'account originale/progetto API possono accedere alle ricevute; le email dei firmatari sono escluse.
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'L'annullamento è consentito solo mentre inviato, visualizzato o in attesa di consegna. Le richieste parzialmente firmate e completate non possono essere annullate da PDFHQ. HTTP 200 del provider non significa che la busta sia stata annullata. Attendi un signature_request_canceled callback o stato del provider confermato. Risposte come cancel_uncertain richiedono indagine dell'operatore; non inviare mai di nuovo alla cieca.
Questa API non promette l'eliminazione di inviti precedentemente inviati per email, l'applicabilità legale, l'annullamento retroattivo di una firma esistente, rimborsi automatici o SLA provider di livello produttivo. La modalità live futura richiede fatturazione centralizzata basata su crediti, verifica dell'identità, revisione contrattuale e accettazione completa del provider di staging.
Recupero documento firmato#
Dopo un verificato signature_request_downloadable richiamata, uso POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ scarica il PDF completato da Dropbox nello spazio dei nomi di archiviazione HQ privato. Quindi recupera GET /v1/esign/envelopes/ENVELOPE_UUID/download-url per un URL di output con ambito account di breve durata.
Il PDF di origine non viene mai inviato tramite un URL specificato dal cliente. Inoltriamo i byte del file sigillato verificato all'host API Dropbox fisso. Le pagine dei firmatari ospitate dal provider e le prove di audit del provider sono gestite dal servizio selezionato.
Sicurezza webhook e transizioni di stato →