Logotipo de PDFHQ

Documentos

API de solicitudes de firma electrónica

Cree y edite borradores de firma versionados, coloque y valide campos asignados por el remitente, envíe solicitudes de sandbox explícitas y recupere artefactos firmados.

Claves de API del lado del servidor Cargas de almacenamiento firmadas

Ciclo de vida de solicitud de firma — primero sandbox#

PDFHQ eSign admite un recurso de sobre neutral del proveedor: carga y verifica un PDF con POST /v1/documents/uploads, luego crea un borrador de solicitud de firma. Los borradores tienen su propia identidad, firmantes y estado separados de las tareas de conversión de PDF.

Versión actual: Solo modo de prueba de Dropbox Sign. Los documentos de prueba tienen marca de agua y no son legalmente vinculantes. El proveedor envía sus propios correos de firmante. Las solicitudes de firma en vivo, las conexiones OAuth empresariales y las tarifas de producción no están habilitadas.

Crear un borrador de firma electrónica
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 campos de firmante exactos y borradores versionados#

Los clientes de Sandbox pueden colocar campos de firma, iniciales y fecha de firma en un PDF de Carta US sellado, vertical y sin recortes. Las coordenadas de rectángulo públicas se normalizan de 0 a 1 relativas a la esquina superior izquierda de la página; el número de página comienza en 1. Cada firmante debe recibir un campo de firma requerido. Rechaza colocaciones superpuestas, faltantes o fuera de los límites. Para todos los otros tamaños de página, omite fields para usar la página de firma adjunta del proveedor mientras se valida la asistencia.

Crear borrador posicionado de dos firmantes
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 creación es idempotente con un Idempotency-Key. La misma clave y los mismos datos de documento sellado/borrador devuelven el borrador existente; una carga diferente devuelve 409. Un borrador solo se puede editar antes de PATCH /v1/esign/envelopes/ENVELOPE_UUID con un conjunto de campos de reemplazo completo y If-Match: 1 desde su draft_version. Las ediciones incrementan la versión y el resumen. Los campos permanecen inmutables después del envío.

Verificación previa exacta de origen y diseño de campo
curl -X POST 'https://api.pdfhq.io/v1/esign/envelopes/ENVELOPE_UUID/validate' \
  -H 'x-api-key: YOUR_API_KEY'

Esta verificación previa compara dimensiones de página y rotación contra bytes sellados reales, no metadatos del navegador. Tiene límite de velocidad y es de solo lectura. Una vista previa local exitosa no certifica la colocación pixel-perfect de Dropbox Sign; revise la ceremonia de firma de prueba real antes de la activación en producción.

Enviar con reconocimiento de prueba explícito#

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'

El envío del proveedor está protegido por una configuración explícita del lado del servidor y deshabilitado en producción. Las solicitudes que pueden haber llegado a Dropbox pero perdieron su respuesta entran needs_reconciliation y no pueden reenviarse ciegamente.

Recordatorios de sandbox y cancelación — los callbacks firmados son autoritativos#

Después de enviar una solicitud de prueba, el remitente puede emitir un recordatorio de correo electrónico de prueba por destinatario en 24 horas. Las solicitudes de cancelación usan la API del proveedor de forma asincrónica; un HTTP 202 solo significa que se solicitó la cancelación, no que los destinatarios no puedan firmar. Ninguna operación es un flujo de trabajo de firma electrónica de producción.

Solicita un recordatorio para un destinatario
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'

Los recibos de recordatorio informan aceptación/rechazo/incertidumbre, no la entrega real de correo electrónico. Un recordatorio intentado se registra duraderamente antes de contactar al proveedor; si el resultado de la red es incierto, no reintentar. Solo los llamadores dentro de la cuenta original/proyecto de API pueden acceder a los recibos; los correos electrónicos de firmantes están excluidos.

Solicita cancelación asincrónica; inspecciona el estado
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'

La cancelación solo se permite mientras está enviado, visto o en espera de entrega. Las solicitudes parcialmente firmadas y completadas no se pueden cancelar desde PDFHQ. HTTP 200 del proveedor no significa que el sobre haya sido anulado. Espera un signature_request_canceled devolución de llamada o estado confirmado del proveedor. Respuestas como cancel_uncertain requieren investigación del operador; nunca reenvíes ciegamente de nuevo.

Esta API no garantiza la eliminación de invitaciones enviadas por correo electrónico anteriormente, aplicabilidad legal, cancelación retroactiva de una firma existente, reembolsos automáticos o SLA de proveedor de grado de producción. El modo activo futuro requiere facturación centralizada basada en créditos, verificación de identidad, revisión contractual y aceptación completa del proveedor de prueba.

Recuperación de documento firmado#

Después de un verificado signature_request_downloadable callback, usar POST /v1/esign/envelopes/ENVELOPE_UUID/archive . PDFHQ descarga el PDF completado desde Dropbox al espacio de nombres de almacenamiento privado de HQ. Luego recupera GET /v1/esign/envelopes/ENVELOPE_UUID/download-url para una URL de salida de corta duración y alcance de cuenta.

El PDF de origen nunca se envía a través de una URL especificada por el cliente. Reenviamos bytes de archivo sellado verificados al host de API de Dropbox fijo. Las páginas de firmante alojadas por el proveedor y la evidencia de auditoría del proveedor se administran por el servicio seleccionado.

Seguridad de webhook y transiciones de estado →
Logotipo de PDFHQ

Herramientas PDF y análisis de documentos. Prepara, comprende y trabaja con tus documentos.

© 2026 PDFHQ. Todos los derechos reservados.