Quickstart: de cero a firma en 5 pasos

Vas a crear y enviar tu primer documento a firma en el sandbox, sin cobros ni correos reales. Todo corre contra https://api.dev.allsign.io/v3 con una key de prueba (prefijo allsign_test_sk_ o allsign_dev_sk_, según tu panel): los documentos se crean, los firmantes existen y los webhooks se disparan, pero nada sale al mundo real. Cuando tu integración funcione aquí, cambias la key y la base URL por las de producción — el contrato es idéntico.

Paso 1 · Obtén tu API key de prueba

Entra a tu panel de AllSign, ve a Developers → API Keys y genera una key de entorno de prueba. Reconócela porque el prefijo no es live: allsign_test_sk_ o allsign_dev_sk_ (según tu panel) — ambas operan en sandbox. Guárdala como secreto (nunca la subas a tu repo ni la pegues en el front); se envía en cada petición como Authorization: Bearer.

# Guárdala en una variable de entorno, no en el código
export ALLSIGN_KEY="allsign_test_sk_tu_key_de_prueba"

La key de sandbox y la de producción son distintas y no son intercambiables: una key de prueba jamás toca datos reales.

Paso 2 · Verifica tu conexión

Antes de crear nada, confirma que tu key es válida con una llamada barata: GET /v3/users/me. Devuelve tu usuario y tu tenant. Este endpoint es tu ping de autenticación:

200 — la key sirve; ya estás dentro.
401 AUTHENTICATION_REQUIRED — falta la key o está mal escrita.

/v3/users/me nunca responde 403: cualquier key autenticada puede leer su propio usuario, sin importar sus scopes. Si ves 403 aquí, es un bug, no un problema de permisos.

curl https://api.dev.allsign.io/v3/users/me \
  -H "Authorization: Bearer $ALLSIGN_KEY"

{
  "id": "usr_...",
  "email": "tu@empresa.com",
  "tenantId": "ten_...",
  "environment": "test"
}

Paso 3 · Crea un documento

Un documento nace en estado draft: existe, pero todavía no se envía a nadie. Lo creas con POST /v3/documents desde una de dos fuentes (source):

`source`	Qué mandas	Notas
`template`	`templateId` + `templateValues` (los valores de las variables)	El más rápido: reusas una plantilla ya diseñada con sus campos de firma.
`file`	El PDF en `base64` (`content` + `name`)	El archivo pesa ≤ 10 MB; si lo excedes → `413 DOCUMENT_TOO_LARGE`.

Desde plantilla (rellenas templateValues):

curl https://api.dev.allsign.io/v3/documents \
  -H "Authorization: Bearer $ALLSIGN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1a9c7e-2b6d-4a51-9f0c-8d2e1b4a6c90" \
  -d '{
    "source": "template",
    "templateId": "tmpl_...",
    "name": "Contrato de arrendamiento",
    "templateValues": { "arrendatario": "Ana López", "monto": "12000" }
  }'

Desde archivo (PDF en base64):

curl https://api.dev.allsign.io/v3/documents \
  -H "Authorization: Bearer $ALLSIGN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c2e1b4a-6c90-4a51-9f0c-3f1a9c7e2b6d" \
  -d '{
    "source": "file",
    "name": "Contrato de arrendamiento",
    "file": { "name": "contrato.pdf", "content": "JVBERi0xLjQK..." }
  }'

La respuesta trae el documento en borrador:

{
  "id": "doc_...",
  "object": "document",
  "status": "draft",
  "livemode": false,
  "name": "Contrato de arrendamiento"
}

Mandar Idempotency-Key (un UUID v4) hace este POST seguro de reintentar sin crear duplicados. Es requerido en POST /v3/documents. Ver Idempotencia.

Paso 4 · Envíalo a firma

Con el documento en draft, lo envías con POST /v3/documents/{id}/send. Le pasas recipients[]: cada firmante lleva un canal de contacto — email o phone (para invitación por WhatsApp); name es opcional pero recomendado. El documento pasa a awaiting_signatures y los firmantes reciben su invitación.

curl https://api.dev.allsign.io/v3/documents/doc_.../send \
  -H "Authorization: Bearer $ALLSIGN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9f0c8d2e-1b4a-6c90-4a51-3f1a9c7e2b6d" \
  -d '{
    "recipients": [
      { "name": "Ana López", "email": "ana@ejemplo.com" },
      { "name": "Beto Ruiz", "phone": "+525512345678" }
    ]
  }'

{
  "id": "doc_...",
  "status": "awaiting_signatures"
}

Ojo con los documentos source: "file": como el PDF no traía campos de firma, necesitas colocar al menos un campo (una firma) antes de enviar. Si intentas enviar un documento subido sin ningún campo, la API responde 409 DOCUMENT_NOT_SENDABLE. Los documentos creados desde template ya heredan los campos de la plantilla, así que se pueden enviar directo.

Paso 5 · Recibe el webhook de completado

No hagas polling. Cuando todos los firmantes terminan, AllSign te envía un webhook document.completed. El cuerpo es un sobre (envelope) v3: el tipo de evento viaja en eventType (no event), y el PDF de evidencia (NOM-151) llega por URL, nunca embebido inline en el JSON.

{
  "eventId": "evt_...",
  "eventType": "document.completed",
  "apiVersion": "2026-07-11",
  "occurredAt": "2026-07-18T18:04:11.000Z",
  "tenantId": "…",
  "livemode": false,
  "data": {
    "documentId": "doc_...",
    "status": "completed",
    "evidencePdf": { "url": "https://api.dev.allsign.io/v3/documents/doc_...?expand=evidencePdf" }
  }
}

Tu endpoint debe responder 2xx rápido y descargar el PDF de evidencia desde data.evidencePdf.url en segundo plano. Verifica la firma del webhook (Standard Webhooks) antes de confiar en el cuerpo.

Qué sigue

Autenticación — prefijos de key, scopes por recurso y el contrato de errores 401/403.
Paginación — cómo recorrer listas con cursores opacos.
Idempotencia — qué POST la requieren y cómo reintentar sin duplicar.
Errores — el contrato problem+json y el catálogo de códigos.
Endpoints de Documents — la referencia completa de cada operación.

Cuando tu flujo pase en sandbox, cambia tu key de prueba por la de producción y api.dev.allsign.io por la base URL de producción. El contrato no cambia.