API des demandes de signature électronique
Créez et modifiez des brouillons de signature versionnés, placez et validez les champs attribués par l'expéditeur, envoyez des demandes de bac à sable explicites et récupérez les artefacts signés.
Cycle de vie de la demande de signature — sandbox d'abord#
PDFHQ eSign prend en charge une ressource d'enveloppe neutre vis-à-vis du fournisseur : importer et vérifier un PDF avec POST /v1/documents/uploads, puis créez un brouillon de demande de signature. Les brouillons ont leur propre identité, signataires et statut distincts des tâches de conversion PDF.
Version actuelle : Mode test Dropbox Sign uniquement. Les documents de test sont filigranés et ne sont pas juridiquement contraignants. Le prestataire envoie ses propres e-mails de signataire. Les demandes de signature en direct, les connexions OAuth d'entreprise et les tarifs de production ne sont pas activés.
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}]}'Préparez les champs de signataire exacts et les brouillons versionnés#
Les clients Sandbox peuvent placer des champs de signature, d'initiales et de date de signature sur un PDF US Letter scellé, droit et non recadré. Les coordonnées de rectangle public sont normalisées de 0 à 1 par rapport au coin supérieur gauche de la page ; la numérotation des pages commence à 1. Chaque signataire doit recevoir un champ de signature obligatoire. Rejetez les placements qui se chevauchent, manquent ou sortent des limites. Pour tous les autres formats de page, omettez fields pour utiliser la page de signature ajoutée par le fournisseur pendant que le support est en cours de validation.
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 création est idempotente avec un Idempotency-Key. La même clé et les mêmes données de document scellé/brouillon retournent le brouillon existant ; une charge utile différente retourne 409. Un brouillon ne peut être modifié que avant l'envoi par PATCH /v1/esign/envelopes/ENVELOPE_UUID avec un ensemble de champs de remplacement complet et If-Match: 1 de son draft_version. Les modifications incrémentent la version et le digest. Les champs restent immuables après la transmission.
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
-H 'x-api-key: YOUR_API_KEY'Ce contrôle en amont compare les dimensions de page et la rotation par rapport aux octets scellés réels, pas aux métadonnées du navigateur. Il est limité en débit et en lecture seule. Un aperçu local réussi ne certifie pas le placement pixel-parfait de Dropbox Sign ; examinez la cérémonie de signature de test réelle avant l'activation en production.
Envoyer avec reconnaissance de test explicite#
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'La transmission du fournisseur est protégée par une configuration explicite côté serveur et désactivée en production. Les demandes qui ont peut-être atteint Dropbox mais ont perdu leur réponse entrent needs_reconciliation et ne peut pas être renvoyé aveuglément.
Rappels sandbox et annulation — les rappels signés sont autoritaires#
Après l'envoi d'une demande de test, l'expéditeur peut envoyer un rappel par e-mail de test à chaque destinataire dans les 24 heures. Les demandes d'annulation utilisent l'API du fournisseur de manière asynchrone ; un HTTP 202 signifie uniquement que l'annulation a été demandée, non que les destinataires ne peuvent plus signer. Aucune opération n'est un flux de signature électronique de production.
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'Les rapports de rappel de reçus indiquent l'acceptation/rejet/incertitude, non la livraison réelle des e-mails. Une tentative de rappel est enregistrée durablement avant de contacter le fournisseur ; si le résultat réseau est incertain, ne pas réessayer. Seuls les appelants du compte/projet API d'origine peuvent accéder aux reçus ; les e-mails des signataires sont exclus.
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'annulation est autorisée uniquement pendant l'envoi, la consultation ou l'attente de livraison. Les demandes partiellement signées et complétées ne peuvent pas être annulées depuis PDFHQ. HTTP 200 du fournisseur ne signifie pas que l'enveloppe a été annulée. Attendez un signature_request_canceled statut de rappel ou de fournisseur confirmé. Les réponses telles que cancel_uncertain nécessitent une enquête de l'opérateur ; ne jamais soumettre à nouveau aveuglément.
Cette API ne promet pas la suppression des invitations précédemment envoyées par e-mail, l'applicabilité légale, l'annulation rétroactive d'une signature existante, les remboursements automatiques ou le SLA du fournisseur de qualité production. Le mode live futur nécessite une facturation centralisée basée sur les crédits, une vérification d'identité, un examen contractuel et une acceptation complète du fournisseur en staging.
Récupération de documents signés#
Après une vérification signature_request_downloadable callback, utilisez POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ télécharge le PDF complété de Dropbox dans l'espace de noms de stockage HQ privé. Ensuite, récupérez GET /v1/esign/envelopes/ENVELOPE_UUID/download-url pour une URL de sortie de courte durée et limitée au compte.
Le PDF source n'est jamais envoyé via une URL spécifiée par le client. Nous transférons les octets de fichier scellé vérifiés vers l'hôte API Dropbox fixe. Les pages de signataire hébergées par le fournisseur et les preuves d'audit du fournisseur sont gérées par le service sélectionné.
Sécurité des webhooks et transitions d'état →