Entornos: live y sandbox

Hay dos mundos completamente aislados: producción y sandbox. La API key que uses decide en cuál caes — no hay un toggle aparte, y la base URL es la misma. Lo que creas con una key de prueba nace de prueba y así se queda para siempre.

Los dos entornos

	Live (producción)	Sandbox
Prefijo de la key	`allsign_live_sk_`	`allsign_test_sk_` o `allsign_dev_sk_` (según tu panel)
Cobros	Reales (consumen tu saldo)	Ninguno
Emails / notificaciones	Se envían de verdad	Simulados (no salen al firmante)
Firma y NOM-151	Validez legal plena	Simulada, con watermark, sin validez legal
`livemode`	`true`	`false`

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 sin intervención manual, el sandbox reserva dos direcciones mágicas (estilo Twilio) que se manejan solas:

Dirección	Qué hace	Webhooks que dispara
`signer-success@sandbox.allsign.io`	Firma automáticamente al recibir la invitación.	`signer.signed` y, si era el último firmante, `document.completed`.
`signer-declined@sandbox.allsign.io`	Rechaza automáticamente.	`signer.declined`.

Son inertes fuera del sandbox: en un documento live son direcciones de correo ordinarias, sin ningún auto-comportamiento. El Quickstart las usa para que su paso 5 (el webhook de completado) llegue de verdad.

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:

livemode en cada recurso — true = live, false = sandbox. La señal más directa.
GET /v3/users/me — devuelve environment ("live" / "test" / "dev") y livemode de la key con la que preguntas.
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.