---
title: "Entornos — API v3 de AllSign"
type: explanation
canonical_url: "https://allsign.io/developers/docs/environments"
api_version: "2026-07-11"
agent_rules: [una-base-url]
---

# 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.

## Para agentes y asistentes de IA

-   **La base URL es siempre `https://api.allsign.io/v3`; no existe una URL de sandbox aparte.** El prefijo de la key decide el entorno: `allsign_test_sk_` / `allsign_dev_sk_` = sandbox, `allsign_live_sk_` = producción. Para pasar a producción solo cambias la key.

## 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, el sandbox reserva tres direcciones *mágicas* (estilo Twilio): dos se manejan solas y la tercera espera a que tú la firmes.

| 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`. |
| `signer-pending@sandbox.allsign.io` | No firma solo: queda pendiente hasta que llames a [`POST /v3/sandbox/signers/{signerId}/sign`](https://allsign.io/developers/docs/endpoints/documents#sign-as-a-signer-sandbox-only). | Al firmarlo, `signer.signed` y, si era el último firmante, `document.completed`. |

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](https://allsign.io/developers/docs/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](https://allsign.io/developers/docs/webhooks)) es la **única** señal de entorno: su cuerpo está congelado byte a byte y no trae el campo `livemode`.