REST API v1 di SignSpry

Autenticazione

Crea una chiave nella console per sviluppatori e inviala a ogni richiesta:

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

Una chiave ha solo gli ambiti spuntati al momento della creazione — envelopes:read (elenco, stato, registro di controllo, PDF sigillato), envelopes:write (creazione, invio, promemoria, annullamento, link di firma e di incorporamento), templates:read, account:read. Una chiamata al di fuori degli ambiti della chiave restituisce 403 indicando l'ambito mancante. Le chiavi scadono (30 giorni, 90 giorni, un anno o mai — ricevi un'email una settimana prima) e poi restituiscono 401; possono inoltre essere vincolate a una lista di IP consentiti (indirizzi o intervalli CIDR), restituendo 403 da qualsiasi altra provenienza. Dai a ogni integrazione la propria chiave con gli ambiti minimi necessari, così revocarne una non ne interrompe mai un'altra.

Crea e invia una busta

Una sola chiamata carica i documenti (PDF in base64), aggiunge destinatari e campi e invia. Le coordinate sono frazioni della pagina (0–1) a partire dall'angolo in alto a sinistra; recipient è un indice nell'array dei destinatari; status: "sent" invia subito gli inviti via email (omettilo per mantenere una bozza).

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}
    ]
  }'

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

Firma incorporata

Al posto degli inviti via email (o in aggiunta), ottieni un URL di firma e aprilo nella tua app — in un iframe o con un reindirizzamento. Quando il firmatario ha finito, viene inviato al tuo 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": {…}}

Gli ID dei destinatari provengono dalle risposte di creazione/dettaglio. Ogni chiamata genera un nuovo link e invalida quelli vecchi per quel destinatario. L'ordine di firma resta valido — un firmatario bloccato vede una pagina “in attesa degli altri”.

Webhook

Aggiungi un endpoint nella console; ogni evento corrispondente invia 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":[…]}}}

Verifica (Python): hmac.new(secret, raw_body, hashlib.sha256).hexdigest() == header.split("sha256=")[1]. Le consegne non riuscite vengono ritentate due volte; i risultati delle consegne recenti sono visibili nella console. Eventi: envelope.sent recipient.viewed recipient.signed recipient.declined recipient.reassigned envelope.completed envelope.voided envelope.expired reminder.sent

Riferimento