API REST v1 de SignSpry

Autenticación

Crea una clave en la consola de desarrolladores y envíala en cada solicitud:

curl https://signspry.com/api/v1/account \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Una clave solo tiene los alcances marcados al crearla — envelopes:read (lista, estado, registro de auditoría, PDF sellado), envelopes:write (crear, enviar, recordar, anular, enlaces de firma y de inserción), templates:read, account:read. Una llamada fuera de los alcances de la clave devuelve 403 e indica el alcance que falta. Las claves caducan (30 días, 90 días, un año o nunca — te avisamos por correo una semana antes) y después devuelven 401; además, pueden restringirse a una lista de IP permitidas (direcciones o rangos CIDR) y devolver 403 desde cualquier otro lugar. Da a cada integración su propia clave con los alcances mínimos que necesite, para que revocar una nunca afecte a otra.

Crear y enviar un sobre

Una sola llamada sube los documentos (PDF en base64), añade destinatarios y campos, y envía. Las coordenadas son fracciones de la página (0–1) desde la esquina superior izquierda; recipient es un índice del array de destinatarios; status: "sent" envía las invitaciones por correo de inmediato (omítelo para guardar un borrador).

curl -X POST https://signspry.com/api/v1/envelopes \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Service Agreement",
    "message": "Please sign by Friday.",
    "expires_days": 15,
    "reminder_days": 2,
    "status": "sent",
    "documents": [{"name": "agreement.pdf", "content_b64": "'"$(base64 -w0 agreement.pdf)"'"}],
    "recipients": [
      {"name": "Asha Vendor", "email": "asha@vendor.in", "routing_order": 1},
      {"name": "Manu Shekhar", "email": "manu@signspry.com", "routing_order": 2},
      {"name": "Accounts",  "email": "accounts@signspry.com", "role": "cc"}
    ],
    "fields": [
      {"recipient": 0, "type": "signature", "page": 0, "x": 0.10, "y": 0.72, "w": 0.25, "h": 0.05},
      {"recipient": 0, "type": "text", "page": 0, "x": 0.10, "y": 0.60, "w": 0.20, "h": 0.04,
       "label": "PAN", "validation": {"type": "pan"}},
      {"recipient": 1, "type": "signature", "page": 1, "x": 0.10, "y": 0.72, "w": 0.25, "h": 0.05}
    ]
  }'

Tipos de campo: signature initials text date checkbox dropdown (con options) radio (con group_name) formula. Validaciones: email numbers letters date phone_in pincode pan gstin {"type":"custom","regex":"…"}.

Firma integrada

En lugar de (o además de) las invitaciones por correo, obtén una URL de firma y ábrela en tu propia app — en un iframe o con una redirección. Cuando el firmante termina, se le envía a tu return_url con ?envelope=…&event=signed (o declined).

curl -X POST https://signspry.com/api/v1/envelopes/ENV_ID/recipients/RECIPIENT_ID/signing-link \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://yourapp.com/signing-done"}'

#  {"url": "https://signspry.com/sign/…", "recipient": {…}}

Los ID de destinatario vienen en las respuestas de creación y de detalle. Cada llamada genera un enlace nuevo e invalida los anteriores de ese destinatario. El orden de firma se sigue aplicando — un firmante bloqueado ve una página de “esperando a los demás”.

Webhooks

Añade un endpoint en la consola; cada evento que coincida le enviará un POST con JSON:

POST https://yourapp.com/webhooks/signet
X-Signet-Event: envelope.completed
X-Signet-Signature: sha256=<hex HMAC-SHA256 of raw body, keyed with your whsec_… secret>

{"id":"…","event":"envelope.completed","created_at":1787480000.1,
 "data":{"envelope":{"id":"…","title":"…","status":"completed","recipients":[…]}}}

Verificación (Python): hmac.new(secret, raw_body, hashlib.sha256).hexdigest() == header.split("sha256=")[1]. Las entregas fallidas se reintentan dos veces; los resultados de las entregas recientes se muestran en la consola. Eventos: envelope.sent recipient.viewed recipient.signed recipient.declined recipient.reassigned envelope.completed envelope.voided envelope.expired reminder.sent

Referencia