Ambientes dev / test / live

Cada API key de AllSign lleva un ambiente incorporado: dev, test o live. El ambiente determina el rate limit, qué notificaciones se envían, si los PDFs llevan marca de agua y cómo se filtran tus documentos.

Los tres ambientes

El ambiente de un API key se elige al crearlo desde el portal en Desarrolladores → API Keys.

Ambiente	Prefijo del key	Para qué sirve
`dev`	`allsign_dev_sk_...`	Integración y pruebas locales. Rate limit reducido, PDFs con marca de agua, WhatsApp desactivado.
`test`	`allsign_test_sk_...`	QA y staging. Mismo comportamiento que `dev`.
`live`	`allsign_live_sk_...`	Producción. Sin restricciones, documentos con validez legal.

El ambiente está codificado en el prefijo del key. No puedes cambiar el ambiente de un key existente — crea uno nuevo si necesitas cambiar.

Qué cambia por ambiente

Rate limit

El rate limit es el mismo para todos los ambientes — viene de tu plan de suscripción activo (default: 100 req/min). No hay penalización por usar keys dev o test.

Si alcanzas el límite, recibirás un 429 con el header Retry-After:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Limit: 100 req/min.",
    "limit": 100,
    "remaining": 0,
    "reset": 1745018460,
    "retry_after": 23,
    "environment": "dev",
    "documentation_url": "https://developers.allsign.io/rate-limits"
  }
}

Emails de invitación

Los emails de invitación a firmar no se envían en ambientes dev y test. En su lugar, la respuesta de invite / invite-bulk incluye el guestLink con la URL de firma directa en details[n].guestLink, para que puedas probar el flujo completo sin necesitar un buzón real:

{
  "success": true,
  "sentCount": 1,
  "failedCount": 0,
  "details": [
    {
      "participant": "firmante@empresa.com",
      "success": true,
      "guestLink": "https://allsign.io/sign/abc123...?otp=789456"
    }
  ]
}

La señal de que la notificación fue omitida (mock) es que details[n].guestLink viene poblado en sandbox. La API no devuelve ningún campo notification_results en la respuesta HTTP — ese dato vive solo dentro del workflow interno de Temporal y nunca se expone en el contrato de la API.

Con keys live, los emails sí se envían y guestLink siempre es null en la respuesta — el firmante recibe el link solo en su buzón. Ver Modo Sandbox para más detalles sobre el flujo de pruebas.

WhatsApp solo se envía con keys live. En dev y test el mensaje se omite (mock) igual que el email — y al igual que con el email, la señal en la API es el guestLink poblado en details[n].guestLink. La respuesta HTTP no incluye ningún campo notification_results; ese detalle vive únicamente dentro del workflow interno de Temporal.

PDFs de evidencia

Los documentos creados con keys dev o test generan PDFs con:

Marca de agua diagonal en todas las páginas.
Página de portada roja con la leyenda "SIN VALIDEZ LEGAL — Documento de prueba".

Estos PDFs no tienen validez legal ni regulatoria.

Documentos y environmentSummary

Filtro automático

Cuando llamas GET /v2/documents con un key dev o test, la API filtra automáticamente y solo devuelve los documentos de ese ambiente. No necesitas pasar ?environment=dev explícitamente.

Si necesitas ver documentos de todos los ambientes desde un mismo request, usa:

GET /v2/documents?environment=all

Campo environmentSummary

Con keys dev o test, la respuesta de listado incluye un campo extra environmentSummary que te muestra cuántos documentos hay en tu ambiente activo vs. el total del tenant:

{
  "data": [...],
  "meta": { ... },
  "environmentSummary": {
    "active_environment": "dev",
    "showing": 3,
    "tenant_total": 11,
    "note": "Showing DEV documents only. Your tenant has 11 document(s) across all environments. Use ?environment=all to see everything."
  }
}

showing es el conteo de la página actual, no el total de documentos en el ambiente. Si hay más páginas, el siguiente cursor traerá más documentos.

Con keys live el campo environmentSummary no aparece en la respuesta.

Campo livemode

Cada objeto Document en la API incluye el campo livemode:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "environment": "dev",
  "livemode": false,
  ...
}

`livemode`	Significa
`true`	Documento creado con key `live`. Tiene validez legal.
`false`	Documento creado con key `dev` o `test`. Solo para pruebas.

Esto es especialmente útil en webhook handlers: verifica livemode antes de procesar cualquier evento para evitar ejecutar lógica de producción (cobros, firmado legal, notificaciones reales) con documentos de prueba. En el payload del webhook, livemode se inyecta en el nivel superior del evento (el recurso vive en event.data):

app.post('/webhook/allsign', (req, res) => {
  const event = req.body

  if (!event.livemode) {
    // test document — skip production logic
    return res.sendStatus(200)
  }

  // ... real processing — el recurso está en event.data
})

Cuándo hacer el switch a live

Haz el switch a una key live cuando:

Tus documentos necesiten validez legal.
Quieras enviar invitaciones por WhatsApp.
Vayas a integrar en un entorno de producción real.

Para crear una key live, ve al portal en Desarrolladores → API Keys → Nueva key y selecciona el ambiente live. Cambia solo el valor de Authorization en tus requests — el resto del código es idéntico.