API Firmar PDF (Marcas Visibles)
Coloca un nombre escrito, fecha o imagen de firma dibujada en un PDF usando el ciclo de vida de tarea medida. Esto no verifica identidades ni emite firmas criptográficas respaldadas por certificado.
Semántica de punto final y tarea#
Código de operación: sign
Inicia esta operación con POST /v1/tasks y el código de herramienta que se muestra arriba. Cargue y adjunte archivos PDF de origen (o utilice puntos finales de carga con alcance de tarea), luego llame POST /v1/tasks/{task_id}/process con configuración de operación.
Añade una firma visible revisada, iniciales o fecha a documentos con permiso del firmante.
Entradas: Exactamente un PDF sellado; 1–12 marcas; máximo 100 MiB y 500 páginas (los límites del plan pueden ser menores). Se rechazan los documentos que ya contienen firmas digitales.
Configuración y parámetros adicionales#
| Configuración | Tipo | Comportamiento |
|---|---|---|
| marksobligatorio | object[] | 1–12 marcas; cada una incluye página (basada en 1), x0, y0, x1, y1 en puntos PDF de esquina superior izquierda y tipo: escrito, fecha o dibujado. Las marcas escritas/fecha incluyen texto; las marcas dibujadas incluyen bytes PNG en base64 (sin prefijo de URL de datos). Imágenes máx. 96 KiB, 1600 × 600 píxeles. |
La API valida las opciones. Los parámetros desconocidos y los valores no admitidos devuelven un error en lugar de ignorarse.
Secuencia de solicitud en funcionamiento#
Programming language: cURL
Elige un idioma · desplázate horizontalmente para los 10 idiomas de SDK
# Server-side API calls. Save the returned task_id.
curl -fsS -X POST 'https://api.pdfhq.io/v1/tasks' \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"tool":"sign"}'
# Upload and verify 1 PDF(s), then obtain and approve a credit quote:
curl -fsS 'https://api.pdfhq.io/v1/tasks/TASK_ID/quote' -H 'x-api-key: YOUR_API_KEY'
# ONLY after explicit customer approval:
test "$PDFHQ_APPROVE_QUOTE" = yes || { echo "Approval required" >&2; exit 1; }
curl -fsS -X POST 'https://api.pdfhq.io/v1/tasks/TASK_ID/process' \
-H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
-d '{"options":{"marks":[{"kind":"typed","page":1,"x0":72,"y0":650,"x1":320,"y1":715,"text":"Jane Doe"}]}}'
curl -fsS 'https://api.pdfhq.io/v1/tasks/TASK_ID' -H 'x-api-key: YOUR_API_KEY'After starting a task, upload and verify PDFs, review the credit quote, and get explicit approval before processing. API keys belong on your server, never on signed storage uploads.
Los paquetes descargables generados cubren solo el flujo de tareas. Los SDK de servicio completo requieren una especificación OpenAPI de tiempo de ejecución verificada; los SDK de tareas de Python, JavaScript y TypeScript transmiten cargas de archivos; los otros idiomas requieren cargas multiparte firmadas implementadas por el llamador.
El ID de tarea devuelto se utiliza tanto para sondeo de estado como para recuperación. Después de que la tarea se complete correctamente, solicite una URL de salida firmada en lugar de incrustar un secreto de descarga.
Resultado y detalles importantes#
Nuevo PDF que contiene marcas de firma visibles en los rectángulos solicitados. Las páginas de origen y el texto original permanecen accesibles.
Esta operación NO crea un certificado digital, pista de auditoría del destinatario, atestación de cumplimiento legal o verificación de identidad del firmante. Se rechazan las firmas digitales PDF existentes; las páginas de destino rotadas no son compatibles. Para flujos de trabajo de firma de destinatario de nivel empresarial, integra un proveedor dedicado.
Errores, reintentos y facturación