Riferimento API

Autenticazione

Autentica ogni richiesta con una API key come Bearer token. Crea le chiavi nel tuo account in Chiavi API — il testo in chiaro è mostrato una sola volta. Tienila segreta: chiunque abbia una chiave può agire sul tuo account.

Crea e invia un documento

POST /api/v1/documents

Una sola chiamata carica il PDF, crea il documento e invia gli inviti. multipart/form-data con un file e un payload JSON. Rispetta la quota mensile (402 se esaurita).

curl -X POST https://bascribe.com/api/v1/documents \
  -H "Authorization: Bearer bsk_live_..." \
  -F file=@contract.pdf \
  -F 'payload={
    "title": "Service agreement",
    "signingMode": "PARALLEL",
    "signers": [
      { "name": "Ada Lovelace", "email": "ada@example.com", "role": "Client" }
    ]
  }'

# 201 Created
{ "id": "clx…", "status": "SENT", "invited": 1,
  "signers": [ { "name": "Ada Lovelace", "email": "ada@example.com", "status": "PENDING" } ] }

Stato del documento

GET /api/v1/documents/:id

Interroga lo stato di un documento e il progresso per firmatario. Dove possibile, preferisci i webhook al polling.

curl https://bascribe.com/api/v1/documents/clx… \
  -H "Authorization: Bearer bsk_live_..."

# 200 OK
{ "id": "clx…", "status": "PARTIALLY_SIGNED",
  "signers": [ { "email": "ada@example.com", "status": "SIGNED", "signedAt": "…" } ],
  "executedAvailable": false }

Scarica il PDF eseguito

GET /api/v1/documents/:id/executed

Quando tutti hanno firmato e il documento è finalizzato, scarica il PDF eseguito (firme + Certificato di Completamento). Ritorna 409 finché non è pronto.

curl -L https://bascribe.com/api/v1/documents/clx…/executed \
  -H "Authorization: Bearer bsk_live_..." \
  -o executed.pdf   # 409 until COMPLETED

Webhook

Registra endpoint HTTPS in Webhook per ricevere eventi in tempo reale. Ogni consegna è una POST con corpo JSON e viene ritentata in caso di errore (1m, 5m, 30m, 2h, 6h, 24h).

Eventi sottoscrivibili:

Verifica delle firme

Ogni consegna porta un header X-BAScribe-Signature: t=<unix>,v1=<hmac>. Ricalcola l'HMAC-SHA256 di "<t>.<rawBody>" con il secret dell'endpoint e confronta. Rifiuta timestamp più vecchi di 5 minuti.

import { createHmac } from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(t + "." + rawBody).digest("hex");
  return expected === v1;
}