Quickstart: de cero a firma en 5 pasos

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.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):

Desde plantilla (rellenas templateValues):

curl https://api.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.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.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": "signer-success@sandbox.allsign.io" }
    ]
  }'

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

¿Por qué ese correo? En sandbox los correos no salen al mundo real, así que un firmante normal nunca firma — y el paso 5 no llegaría jamás. El sandbox tiene firmantes mágicos (estilo Twilio) que se manejan solos:

Solo funcionan en sandbox: en un documento live son direcciones ordinarias, sin ningún comportamiento automático.

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. Como en el paso 4 usaste el firmante mágico signer-success@sandbox.allsign.io, la firma ocurre sola y este webhook llega sin que toques nada. 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.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. La base URL es la misma (https://api.allsign.io/v3): la key decide el entorno. El contrato no cambia.