Desarrolladores

Quickstart: llame al API desde su servidor

Reclame una zona de pruebas, almacene la clave `esk_test_`, confírmela, cree un documento a partir de una plantilla y envíelo. Los tokens de sesión de firma utilizan la misma clave. Los Webhook están registrados en la aplicación de administración.

Antes de empezar

Necesita una terminal con `curl` y `jq`, además de una bandeja de entrada de correo electrónico que usted controle. La clave de la zona de pruebas es `esk_test__…`. Una clave de producción es `esk_live__…`. Envíelo como `Autorización: Portador`. El inquilino proviene de la clave, así que no envíe "x-tenant-id".

Una clave de espacio aislado incluye `integraciones:zapier` y `firma:escribir`. La carga, el asistente de sobres y el registro webhook usan la sesión de administrador después de iniciar sesión. Su servidor usa la clave para las llamadas a continuación.

Cuatro llamadas al servidor, luego un webhook en la aplicación de administración

  1. 1

    Reclama tu zona de pruebas

    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

    Confirma la clave

    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 y envíalo

    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

    Registrar un webhook en Administrador

    Inicie sesión y abra Administrador → Desarrollador → Webhooks. Guarde el secreto de firma. Las entregas utilizan `X-Endorsed-Signature`. Los pasos de verificación se encuentran en la guía del webhook. Inspeccione los intentos en Administrador → Desarrollador → Consola.

Paso 1: reclamar una zona de pruebas

Requisitos previos: una dirección de correo electrónico y una contraseña de más de 8 caracteres. Resultado esperado: HTTP 201 con `data.sandbox.apiKey` iniciando `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)"

Guarde la clave en el administrador secreto de su servidor. La verificación por correo electrónico accede a la consola de administración. La clave funciona para las convocatorias de esta página tan pronto como se emite.

Paso 2: confirma la clave

Requisitos previos: `$ENDORSED_API_KEY` del paso 1. La clave de la zona de pruebas ya tiene `integraciones:zapier`. Resultado esperado: HTTP 200 y el nombre de su inquilino.

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 clave faltante o con formato incorrecto es 401. Una clave válida sin `integrations:zapier` es 403. No envíe `X-Data-Mode`: `esk_test_` ya selecciona datos de prueba.

Paso 3: cree un documento a partir de la plantilla de zona de pruebas y envíelo

Requisitos previos: `$ENDORSED_API_KEY` y un `$ENDORSED_TEMPLATE_ID` no vacío. Si `sampleTemplateId` era nulo, cree una plantilla en la aplicación de administración y pegue su identificación. Resultado esperado: HTTP 201 con `data.documentId`, luego una respuesta de envío 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 }'

El enlace de firma se envía por correo electrónico a `recipientEmail`. La respuesta JSON incluye la identificación del documento, el estado y la caducidad del enlace. Abra el correo electrónico para finalizar la firma, luego mire `document.signed` en un webhook que registró en Admin.

Acuña un token de sesión de firma

Requisitos previos: `$ENDORSED_API_KEY` con `signing:write` (incluido en la clave de la zona de pruebas) y una identificación de sesión de firma de una sesión que ya creó. Resultado esperado: HTTP 201 con un token `st_…` único.

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

Entregue `st_…` a la inserción del navegador. Mantenga `esk_…` en el servidor. Las instrucciones para canjear se encuentran en la página de inserción de Elements.

Cuando algo sale mal

¿Listo para profundizar más?

Una vez que tenga un documento firmado de extremo a extremo, conéctelo a las áreas de superficie a continuación para la siguiente porción de la integración.

REST API referenciaWebhook contrato + firmas