Modo Sandbox

Prueba tu integración de extremo a extremo sin necesitar un inbox real, sin enviar emails a firmantes reales y sin crear documentos con validez legal.

Qué es el modo sandbox

El modo sandbox es cualquier operación realizada con una API key dev o test. El comportamiento es idéntico al de producción excepto por tres diferencias clave:

Cómo identificar sandbox

Por el prefijo del API key

allsign_dev_sk_...   → ambiente dev (sandbox)
allsign_test_sk_...  → ambiente test (sandbox)
allsign_live_sk_...  → ambiente live (producción)

Por el campo livemode en cada objeto

Cada Document incluye livemode: false cuando fue creado con una key de sandbox:

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

Verifica livemode en tus webhook handlers para evitar procesar documentos de prueba con lógica de producción:

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

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

  // ... real processing
})

guestLink — URL de firma directa

En sandbox, cada invitación exitosa retorna guestLink en el campo details[n].guestLink. Este es el link que normalmente recibiría el firmante en su email.

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

Abre ese URL directamente en el browser (o en un contexto aislado en tus tests) para completar el flujo de firma sin inbox.

Magic OTP

Cuando el firmante abre su guestLink, el sistema le pide un OTP de 6 dígitos que normalmente llega por email. En sandbox puedes usar el código especial 000000 para saltar esta verificación sin necesitar el email:

Campo sandbox_magic_code

Cuando llamas al endpoint de solicitud de OTP con una sesión sandbox, la respuesta incluye el campo adicional sandbox_magic_code:

{
  "success": true,
  "message": "OTP sent to firmante@empresa.com",
  "sandbox_magic_code": "472819"
}

Puedes usar sandbox_magic_code en tus tests automatizados si prefieres el OTP real sobre el bypass 000000.

Flujo de prueba completo

Sigue estos pasos para probar el ciclo completo de firma sin inbox real:

Paso 1 — Crea una API key de sandbox

Ve al portal en Desarrolladores → API Keys → Nueva key y selecciona ambiente dev. Guarda el key — empieza con allsign_dev_sk_.

Paso 2 — Crea un documento e invita firmantes

# Crear documento con participante
curl -X POST "https://api.allsign.io/v2/documents" \
  -H "Authorization: Bearer allsign_dev_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "contrato-prueba.pdf",
    "document": { "base64Content": "..." },
    "participants": [{ "email": "test@ejemplo.com", "name": "Firmante Test" }]
  }'

Después llama a POST /v2/documents/{id}/invite para obtener el guestLink del firmante.

Paso 3 — Obtén el guestLink

Del response anterior, guarda details[0].guestLink. Si usas el flujo paso a paso, llama a invite o invite-bulk y obtén el guestLink de la respuesta.

Paso 4 — Abre el guestLink en un contexto de browser aislado

El link incluye el parámetro ?otp=XXXXXX que autentica automáticamente al firmante. Ábrelo directamente:

https://allsign.io/sign/abc123...?otp=789456

Si el sistema pide OTP adicional (sesión expirada o flujo de reenvío), ingresa 000000.

Paso 5 — Completa la firma

El firmante verá el documento y podrá firmar normalmente. Una vez firmado, el documento avanza a TODOS_FIRMARON y se genera el PDF de evidencia (con marca de agua en sandbox).

Limitaciones del sandbox

Cuándo hacer el switch a live

Haz el switch a una key live cuando:

• Tus documentos necesiten validez legal.
• Quieras enviar invitaciones por email y/o WhatsApp a firmantes reales.
• Vayas a integrar en un entorno de producción real.
• Vayas a firmar documentos con validez legal.

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.