Sviluppatori

Quickstart: chiama API dal tuo server

Richiedi un sandbox, memorizza la chiave `esk_test_`, confermala, crea un documento da un modello e invialo. I token della sessione di firma utilizzano la stessa chiave. Webhook sono registrati nell''app di amministrazione.

Prima di iniziare

Hai bisogno di un terminale con `curl` e `jq`, oltre a una casella di posta elettronica che controlli. La chiave sandbox è "esk_test_…". Una chiave di produzione è "esk_live_…". Invialo come "Autorizzazione: Portatore". Il tenant proviene dalla chiave, quindi non inviare `x-tenant-id`.

Una chiave sandbox include `integrations:zapier` e `signing:write`. Il caricamento, la procedura guidata della busta e la registrazione webhook utilizzano la sessione di amministrazione dopo l''accesso. Il tuo server utilizza la chiave per le chiamate riportate di seguito.

Quattro chiamate al server, quindi un webhook nell''app di amministrazione

  1. 1

    Rivendica la tua sandbox

    POST /api/auth/register with `mode: sandbox`. The response includes a full `esk_test_…` key, shown once, plus `demoCustomerId`. When seeding succeeds it also includes `sampleTemplateId`.

  2. 2

    Conferma la chiave

    GET /api/v1/zapier/auth/test with the key. Expected output: HTTP 200 and `{ success: true, data: { tenantId, tenantName, zapierEnabled: true } }`.

  3. 3

    Crea un documento e invialo

    POST /api/v1/zapier/actions/create-from-template with `sampleTemplateId`, then POST /api/v1/zapier/actions/send-for-signing with the returned `documentId`. The signer receives the link by email.

  4. 4

    Registra un webhook in Amministrazione

    Accedi e apri Amministrazione → Sviluppatore → Webhooks. Salva il segreto della firma. Le consegne utilizzano `X-Endorsed-Signature`. I passaggi di verifica si trovano nella guida webhooks. Controlla i tentativi in ​​Amministrazione → Sviluppatore → Console.

Passaggio 1: rivendica un sandbox

Prerequisiti: un indirizzo email e una password di oltre 8 caratteri. Output previsto: HTTP 201 con `data.sandbox.apiKey` che inizia con `esk_test_`.

bash
curl -sS -X POST https://api.endorsedsign.com/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "tenantName": "Acme Dev Sandbox",
    "adminEmail": "you@acme.example",
    "password": "your-strong-password",
    "mode": "sandbox"
  }' | tee sandbox.json | jq '.data.sandbox'

# → {
#     "apiKey": "esk_test_…",
#     "keyPrefix": "esk_test_…",
#     "keyId": "…",
#     "scopes": ["signing:write", "integrations:zapier", …],
#     "demoCustomerId": "sandbox-signer-acme-dev-sandbox",
#     "demoCustomerName": "Sandbox Signer",
#     "sampleTemplateId": "…",
#     "expiresAt": "2026-…"
#   }

export ENDORSED_API_KEY="$(jq -r '.data.sandbox.apiKey' sandbox.json)"
export ENDORSED_TEMPLATE_ID="$(jq -r '.data.sandbox.sampleTemplateId // empty' sandbox.json)"

Conserva la chiave nel gestore segreto del tuo server. La verifica dell''e-mail accede alla console di amministrazione. Il tasto funziona per le chiamate in questa pagina non appena viene rilasciato.

Passaggio 2: conferma la chiave

Prerequisiti: `$ENDORSED_API_KEY` dal passaggio 1. La chiave sandbox contiene già `integrations:zapier`. Output previsto: HTTP 200 e il nome del tenant.

bash
curl -sS https://api.endorsedsign.com/api/v1/zapier/auth/test \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  | jq '{ success, tenantId: .data.tenantId, tenantName: .data.tenantName, zapierEnabled: .data.zapierEnabled }'

Una chiave mancante o non valida è 401. Una chiave valida senza `integrations:zapier` è 403. Non inviare `X-Data-Mode`: `esk_test_` seleziona già i dati del test.

Passaggio 3: crea un documento dal modello sandbox e invialo

Prerequisiti: `$ENDORSED_API_KEY` e un `$ENDORSED_TEMPLATE_ID` non vuoto. Se `sampleTemplateId` era nullo, crea un modello nell''app di amministrazione e incolla il suo ID. Output previsto: HTTP 201 con `data.documentId`, quindi una risposta di invio con `status: "link-sent"`.

bash
curl -sS -X POST https://api.endorsedsign.com/api/v1/zapier/actions/create-from-template \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"templateId\": \"$ENDORSED_TEMPLATE_ID\",
    \"recipientEmail\": \"you@acme.example\",
    \"recipientName\": \"Sandbox Signer\"
  }" | tee created.json | jq '.data | { documentId, customerId, status }'

export ENDORSED_DOCUMENT_ID="$(jq -r '.data.documentId' created.json)"

curl -sS -X POST https://api.endorsedsign.com/api/v1/zapier/actions/send-for-signing \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"documentId\": \"$ENDORSED_DOCUMENT_ID\",
    \"channel\": \"email\",
    \"subject\": \"Please sign\"
  }" | jq '.data | { documentId, status, channel, shareLinkExpiresAt }'

Il collegamento per la firma viene inviato via email a `recipientEmail`. La risposta JSON contiene l''ID del documento, lo stato e la scadenza del collegamento. Apri l''e-mail per completare la firma, quindi guarda `document.signed` su un webhook registrato in Admin.

Conia un token per la sessione di firma

Prerequisiti: `$ENDORSED_API_KEY` con `signing:write` (incluso nella chiave sandbox) e un ID di sessione di firma da una sessione già creata. Output previsto: HTTP 201 con un token `st_…` monouso.

bash
curl -sS -X POST "https://api.endorsedsign.com/api/v1/signing-sessions/$ENDORSED_SESSION_ID/tokens" \
  -H "Authorization: Bearer $ENDORSED_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{ "scope": "embed", "ttl_seconds": 300 }' \
  | jq '{ token, expires_at, scope }'

Passa `st_…` al browser incorporato. Mantieni `esk_…` sul server. Le istruzioni per il riscatto si trovano nella pagina di incorporamento degli Elementi.

Quando qualcosa va storto

Pronto per approfondire?

Una volta firmato il documento end-to-end, collegalo alle aree di superficie sottostanti per la sezione successiva dell''integrazione.

REST API riferimentoWebhook contratto + firme