Entornos: live y sandbox

Los dos entornos

El campo environment tiene tres valores posibles: live, test y dev. Los últimos dos son sabores del mismo mundo sandbox — cuál te toca depende de cómo tu panel emitió la key; ambos operan igual (cero cobros, livemode: false). Usa tu key de prueba para desarrollar e integrar sin riesgo; cambia a allsign_live_sk_ cuando estés listo para documentos con efectos reales.

Sandbox (test)

El sandbox reproduce el flujo completo —crear, enviar, firmar, webhooks— pero todo es simulado: no se cobra, los correos no salen al firmante real, y los PDFs firmados llevan un watermark que deja claro que no tienen validez legal. Es el lugar para armar y probar tu integración de punta a punta antes de tocar producción.

Todo recurso creado en sandbox trae livemode: false:

{
  "id": "doc_3f2a...",
  "status": "awaiting_signatures",
  "livemode": false,
  "createdAt": "2026-07-18T15:04:00Z"
}

Firmantes mágicos

Como los correos del sandbox son simulados, un firmante normal nunca va a firmar. Para recorrer el ciclo completo, el sandbox reserva tres direcciones mágicas (estilo Twilio): dos se manejan solas y la tercera espera a que tú la firmes.

Cuál usar:

• signer-success para el camino feliz sin intervenir: envías y el documento se completa solo. Es la que usa el Quickstart para que su paso 5 (el webhook de completado) llegue de verdad.
• signer-declined para probar cómo reacciona tu integración a un rechazo.
• signer-pending cuando necesitas ver el documento esperando firmas (awaiting_signatures) —tu pantalla de pendientes, recordatorios, reasignaciones— y decidir tú en qué momento firma.

Ninguna dirección @sandbox.allsign.io recibe correo, en ningún entorno: AllSign descarta esos envíos. Fuera del sandbox, además, no firman ni rechazan solas, y la firma simulada responde 409 ENVIRONMENT_MISMATCH con una key live. No las uses como firmantes de un documento live: su invitación por correo nunca saldría.

El entorno de la key marca el documento

Al crear un recurso, el entorno de la key se estampa permanente en él. Un documento creado con una key de prueba queda en sandbox para siempre — no se "promueve" ni se convierte.

Los listados nunca se cruzan: GET /v3/documents con una key live solo devuelve documentos live, y viceversa. Para saber de qué entorno es un recurso concreto, lee su campo livemode — viaja en cada respuesta.

Para pasar a producción no conviertes tus documentos de prueba. Simplemente empiezas a crear con la key live; los de prueba se quedan en sandbox y ya. Trátalos como datos desechables.

Cómo saber en qué entorno estás

Tres señales, redundantes a propósito, te dicen el entorno sin adivinar:

1. livemode en cada recurso — true = live, false = sandbox. La señal más directa.
2. GET /v3/users/me — devuelve environment ("live" / "test" / "dev") y livemode de la key con la que preguntas.
3. El header AllSign-Environment — viene en cada respuesta autenticada.

GET /v3/users/me

{
  "id": "usr_9a1c...",
  "email": "tu@empresa.mx",
  "environment": "test",
  "livemode": false
}

HTTP/1.1 200 OK
AllSign-Environment: test
AllSign-Request-Id: req_...

Y en webhooks hay dos señales. El envelope v3 del evento trae livemode en el cuerpo, para que tu handler distinga sin depender de qué endpoint lo disparó:

{
  "eventId": "evt_7f3a...",
  "eventType": "document.completed",
  "apiVersion": "2026-07-11",
  "occurredAt": "2026-07-18T15:04:00.000Z",
  "tenantId": "…",
  "livemode": true,
  "data": { "documentId": "doc_2b9c...", "status": "completed" }
}

Además, cada entrega de webhook —de cualquier cohorte— lleva la cabecera AllSign-Livemode: true|false. Para los endpoints clásicos (formato v2, ver Webhooks) es la única señal de entorno: su cuerpo está congelado byte a byte y no trae el campo livemode.