API de Signyd
Firmas integradas en tu producto.
Crea un documento, añade destinatarios y envía las invitaciones de firma con una sola llamada REST. Sigue cada firma con webhooks firmados con HMAC.
URL base
https://app.signyd.com/api/v1
Authorization: Bearer sk_live_…
GET /documents
POST /documents
POST /documents/:id/send
GET PATCH /webhooks
De cero a un documento enviado en tres pasos
- 1
Crea una clave
En la app, abre Ajustes → API (propietarios y administradores) y crea una clave live con nombre. Cópiala al momento: Signyd muestra el secreto una sola vez.
- 2
Envía un documento
Haz POST de un PDF (base64) con sus destinatarios a /documents. Signyd envía las invitaciones de firma por ti.
- 3
Escucha los eventos
Define la URL HTTPS de tu webhook y recibe un evento cuando un documento cambie de estado o un destinatario firme.
Casos de uso
Lo que construyen los equipos con ella
Cada flujo usa solo los endpoints que ves en la referencia.
Contratos al pagar o registrarse
Cuando un cliente acepta un plan, genera el acuerdo con tus propios datos y envíalo a firmar sin que nadie salga de tu flujo.
POST /documentsAltas con identidad verificada
Marca a un destinatario con kyc_required para exigir Signyd Verify antes de firmar: ID, prueba de vida y comparación facial.
POST /documentskyc_required: trueMantén tu CRM o ERP sincronizado
Recibe un webhook cuando una solicitud se envía, completa, anula o caduca, y actualiza la operación, el pedido o el expediente en tu sistema.
WebhooksGET /documents/:idUn panel de firmas
Lista tus últimos documentos y su estado (borrador, enviado, parcialmente firmado, completado, anulado, caducado) dentro de tu propio back office.
GET /documentsRecuerda a los firmantes pendientes
Reenvía las invitaciones de los documentos que siguen esperando, desde un botón de tu app o una tarea programada.
POST /documents/:id/sendArchiva con pruebas
Guarda el hash SHA-256 de cada documento junto a tus registros para demostrar más adelante que el archivo no ha cambiado.
GET /documents/:idsha256_hash
Ejemplos de código
Tu lenguaje, a una petición de distancia
Elige un lenguaje y una operación. Los ejemplos leen tu clave de SIGNYD_API_KEY.
# PDF as base64 (macOS: base64 -i agreement.pdf)
PDF_B64=$(base64 -w0 agreement.pdf)
curl -X POST https://app.signyd.com/api/v1/documents \
-H "Authorization: Bearer $SIGNYD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Service agreement",
"filename": "agreement.pdf",
"pdf_base64": "'"$PDF_B64"'",
"recipients": [{
"email": "ada@example.com",
"name": "Ada Lovelace",
"kyc_required": false,
"page_number": 1,
"signature_x": 72,
"signature_y": 72
}]
}'
# → 201 Created: the document and its recipientsLos endpoints de un vistazo
| Método | Ruta | Qué hace |
|---|---|---|
| GET | /documents | Lista hasta 50 documentos de tu espacio de trabajo. |
| GET | /documents/:id | Obtiene un documento, con sus destinatarios. |
| POST | /documents | Crea un PDF, añade destinatarios y envía las invitaciones de firma. |
| POST | /documents/:id/send | Reenvía las invitaciones de un documento. |
| GET | /webhooks | Lee la URL de tu webhook y si hay un secreto definido. |
| PATCH | /webhooks | Define la URL del webhook y, si quieres, rota el secreto. |
Estados de un documento
draftsentpartially_signedcompletedvoidedexpired
Webhooks firmados
Signyd envía un POST con JSON a tu endpoint HTTPS con los eventos de tu organización. Responde rápido con un 2xx; las entregas fallidas se reintentan.
| Evento | Cuándo |
|---|---|
| Cambios de estado del documento | Una solicitud se envía, completa, anula o caduca. |
| Destinatario ha firmado | Un firmante termina. |
| kyc.failed | La verificación de identidad falló o el solicitante la rechazó (reason puede ser requester_denied). |
Verifica cada entrega
- 1Lee el cuerpo sin procesar de la petición, antes de interpretar el JSON.
- 2Calcula el HMAC de ese cuerpo con el secreto de tu webhook.
- 3Compáralo con la cabecera de firma y rechaza la petición si no coincide.
Límites y errores
- Destinatarios por documento
- Starter 10 · Pro y Business 40 · Scale 99
- Tamaño del PDF
- Hasta 15 MiB
- Documentos por llamada de listado
- Hasta 50
- Posición de la firma
- Por defecto 72, 72 en la página 1
- Créditos
- Una solicitud con varias partes consume un sobre mensual cuando termina el proceso de firma
Respuestas de error
| Estado | error |
|---|---|
| 401 | unauthorized |
| 400 | invalid_json · too_many_recipients · invalid_pdf · pdf_open_encryption · mensajes de validación |
| 402 | no_credits · no_kyc_credits |
| 404 | not_found |
| 413 | payload_too_large |
Construye el flujo de firma que tu producto necesita
Crea una cuenta gratuita, genera una clave y envía tu primer documento hoy.