SignSpry REST-API v1

Authentifizierung

Erstellen Sie einen Schlüssel in der Entwicklerkonsole und senden Sie ihn bei jeder Anfrage mit:

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

Ein Schlüssel hat nur die Berechtigungen, die bei seiner Erstellung angekreuzt wurden — envelopes:read (Liste, Status, Prüfpfad, versiegeltes PDF), envelopes:write (erstellen, senden, erinnern, stornieren, Unterschrifts- und Einbettungslinks), templates:read, account:read. Ein Aufruf außerhalb der Berechtigungen des Schlüssels liefert 403 mit der fehlenden Berechtigung. Schlüssel laufen ab (30 Tage, 90 Tage, ein Jahr oder nie — Sie erhalten eine Woche vorher eine E-Mail) und liefern danach 401; zudem können sie an eine IP-Zulassungsliste (Adressen oder CIDR-Bereiche) gebunden werden und liefern dann von überall sonst 403. Geben Sie jeder Integration einen eigenen Schlüssel mit den engsten nötigen Berechtigungen, damit der Widerruf eines Schlüssels nie eine andere Integration lahmlegt.

Umschlag erstellen & senden

Ein Aufruf lädt Dokumente hoch (Base64-PDFs), fügt Empfänger und Felder hinzu und sendet. Koordinaten sind Bruchteile der Seite (0–1) ab der oberen linken Ecke; recipient ist ein Index in das Empfänger-Array; status: "sent" versendet die Einladungen sofort per E-Mail (weglassen, um einen Entwurf zu behalten).

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

Feldtypen: signature initials text date checkbox dropdown (mit options) radio (mit group_name) formula. Validierungen: email numbers letters date phone_in pincode pan gstin {"type":"custom","regex":"…"}.

Eingebettete Unterzeichnung

Statt (oder zusätzlich zu) E-Mail-Einladungen können Sie eine Unterschrifts-URL abrufen und in Ihrer eigenen App öffnen — per iframe oder Weiterleitung. Wenn der Unterzeichner fertig ist, wird er zu Ihrer return_url mit ?envelope=…&event=signed (oder declined) geleitet.

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": {…}}

Empfänger-IDs stammen aus den Antworten von Erstellen/Details. Jeder Aufruf erzeugt einen neuen Link und macht ältere Links für diesen Empfänger ungültig. Die Reihenfolge gilt weiterhin — ein blockierter Unterzeichner sieht eine Seite „Warten auf andere“.

Webhooks

Fügen Sie in der Konsole einen Endpunkt hinzu; jedes passende Ereignis sendet JSON per POST dorthin:

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":[…]}}}

Verifizieren (Python): hmac.new(secret, raw_body, hashlib.sha256).hexdigest() == header.split("sha256=")[1]. Fehlgeschlagene Zustellungen werden zweimal wiederholt; aktuelle Zustellergebnisse werden in der Konsole angezeigt. Ereignisse: envelope.sent recipient.viewed recipient.signed recipient.declined recipient.reassigned envelope.completed envelope.voided envelope.expired reminder.sent

Referenz