Cómo probar tu integración con la API de ValidaFirma en modo de prueba

Antes de mandar documentos reales a tus clientes, puedes recorrer todo el flujo en modo de prueba: creas el documento con la API, el firmante "firma", te llega el webhook y descargas el PDF. Nada de eso cuesta créditos, no tiene validez legal y no le llega ningún mensaje a ninguna persona.

En este tutorial vas a:

1. crear una llave de API de prueba;
2. preparar dónde recibir los webhooks y el secreto con que los firmamos;
3. crear un documento de prueba;
4. hacer que el firmante "firme", sin que nadie haga nada;
5. pasar a producción cambiando sólo la llave y el secreto.

Antes de empezar: no hay un "ambiente sandbox" aparte

El modo de prueba no es otro servidor. Usas la misma dirección de siempre, https://api.validafirma.cl. Lo que decide si una llamada es de prueba o real es la llave con que llamas:

• una llave que empieza con vf_test_ trabaja siempre en modo de prueba;
• una llave que empieza con vf_live_ trabaja siempre en modo real.

Ningún campo, parámetro ni header de la llamada cambia el modo. Así, pasar a producción es cambiar la llave, y un olvido en tu código nunca convierte una prueba en un documento real.

1. Crea una llave de API de prueba

En el panel de ValidaFirma, entra a API Keys y haz clic en Crear API Key. Ponle un nombre que la distinga (por ejemplo mi-sistema-pruebas) y en Entorno elige Desarrollo (test). Marca los permisos de lectura y escritura.

Al crearla, el panel te muestra la llave completa, que empieza con vf_test_. Cópiala y guárdala en un lugar seguro: el panel no te la vuelve a mostrar entera.

Comprueba que la llave funciona y en qué modo está:

curl https://api.validafirma.cl/api/auth/whoami \
  -H "X-API-Key: vf_test_TU_LLAVE"

La respuesta dice quién eres y el modo de la llave. "sandbox": true significa que la llave es de prueba:

{
  "cuenta": { "id": "…", "nombre": "Tu cuenta", "modalidad": "personal" },
  "credencial": {
    "tipo": "api_key",
    "nombre": "mi-sistema-pruebas",
    "permisos": ["read", "write"],
    "roles": ["propietario"],
    "sandbox": true
  }
}

2. Prepara dónde recibir los webhooks

Necesitas una dirección donde recibir los webhooks. Debe cumplir estas condiciones:

• usar https en el puerto 443;
• no llevar usuario ni clave dentro de la URL;
• apuntar a una dirección pública, no a una red privada ni a localhost.

Si no cumple, la creación del documento responde 400 WEBHOOK_URL_NO_PERMITIDA, con un motivo, y no se crea nada. Para una primera prueba sirve un receptor público como webhook.site.

Cada webhook va firmado con un secreto de tu cuenta, y cada cuenta tiene dos: uno para los documentos de prueba y otro para los reales. Los avisos de este tutorial se firman con el de prueba, que empieza con whsec_test_. Para verlo:

1. Abre el menú de usuario (arriba a la derecha) y enciende Modo de prueba.
2. Entra a API Keys y busca la sección Secreto de webhooks. Debe decir Modo de prueba.
3. Haz clic en Revelar y después en Copiar.

El interruptor del menú cambia sólo lo que ves en el panel. No cambia el modo de tus llaves: una llave vf_live_ sigue siendo real aunque el panel esté en modo de prueba.

Con ese secreto tu sistema comprueba que cada aviso viene de ValidaFirma. El cálculo y el código están en la guía de verificación de webhooks.

3. Crea un documento de prueba

Crea el documento con tu llave de prueba y tu URL de webhook:

curl -X POST https://api.validafirma.cl/api/fes/documentos \
  -H "X-API-Key: vf_test_TU_LLAVE" \
  -F "documento=@contrato.pdf" \
  -F 'firmantes=[{"canal":"whatsapp","telefono":"+56911111111","rut":"11111111-1","nombre":"Firmante Prueba"}]' \
  -F "webhook_url=https://tu-sistema.cl/webhooks/validafirma"

La respuesta tiene la misma forma que en producción, con estas diferencias:

• "es_prueba": true y "sandbox": true, en el documento y en cada firmante;
• consumidos: 0 en creditos;
• fecha_borrado, el día en que el documento de prueba se borrará;
• un plazo de firma de 3 días como máximo.

{
  "mensaje": "Documento creado exitosamente",
  "documento": {
    "id": "112f6510-…",
    "codigo_verificacion": "mupozitm-60305B71",
    "estado": "pendiente",
    "dias_expiracion": 3,
    "es_prueba": true,
    "sandbox": true,
    "fecha_borrado": "2026-10-07T15:31:42.730Z",
    "firmantes": [
      {
        "id": "1feb8b95-…",
        "rut": "11111111-1",
        "canal": "whatsapp",
        "estado": "pendiente",
        "url_firma": "https://app.validafirma.cl/firma/…",
        "es_prueba": true,
        "sandbox": true
      }
    ]
  },
  "creditos": { "consumidos": 0, "es_prueba": true, "sandbox": true }
}

Aunque el firmante tenga canal whatsapp o email, no se envía nada. Los mensajes que le habrían llegado (la invitación, el código y el aviso del documento firmado) quedan guardados para que los revises:

curl "https://api.validafirma.cl/api/fes/mensajes-simulados?documento_id=ID_DEL_DOCUMENTO" \
  -H "X-API-Key: vf_test_TU_LLAVE"

Cada mensaje trae el canal, el destinatario, el texto, el enlace de firma y el código que llevaba.

4. Haz que el firmante "firme"

Tienes tres formas de avanzar el documento. Todas producen el mismo estado y el mismo webhook que un firmante real.

a) Abrir el enlace, como lo haría el firmante

Abre la url_firma de la respuesta en el navegador. En vez de la verificación de identidad real aparece una pantalla de simular, con dos opciones: Simular verificación aprobada y Simular verificación rechazada. Si el flujo pide validar un teléfono o un correo, el código es siempre 123456.

b) Llamar a la API, sin navegador

Cada resultado tiene su propia ruta:

curl -X POST \
  https://api.validafirma.cl/api/fes/documentos/ID_DEL_DOCUMENTO/firmantes/ID_DEL_FIRMANTE/simulacion/firmar \
  -H "X-API-Key: vf_test_TU_LLAVE"

Estas rutas sólo existen para llaves de prueba. Con una llave real responden 400 OPERACION_SOLO_EN_MODO_DE_PRUEBA.

c) Usar un RUT de prueba

Un firmante con uno de estos RUT llega solo a su resultado, sin que nadie haga nada:

Estos RUT sólo tienen efecto en documentos de prueba. En un documento real son un RUT más.

Cuando firma el último firmante, te llega el webhook documento.completado. El PDF firmado se descarga igual que en producción, con una marca visible de que es de prueba.

Para saber si un aviso es de prueba, lee es_prueba (o sandbox, que vale lo mismo) en la raíz del JSON:

{
  "evento": "documento.completado",
  "timestamp": "2026-10-01T15:42:12.930Z",
  "es_prueba": true,
  "sandbox": true,
  "documento": { "id": "…", "codigo_verificacion": "…", "estado": "firmado", "url_descarga": "…", "url_validacion": "…" },
  "firmantes": [ … ]
}

5. Pasa a producción

Cuando tu integración funcione en modo de prueba:

1. Crea una llave con Entorno: Producción (live). Empieza con vf_live_.
2. En el menú de usuario, apaga Modo de prueba. En API Keys → Secreto de webhooks ahora dice Modo real. Revela y copia ese secreto, que empieza con whsec_live_.
3. En tu sistema, reemplaza la llave vf_test_ por la vf_live_ y el secreto whsec_test_ por el whsec_live_.

No cambias nada más: ni la dirección de la API, ni tu código de verificación, ni la URL del webhook. Desde ese momento cada documento es real: el firmante recibe su invitación, verifica su identidad de verdad, el documento tiene validez legal y cada firmante se descuenta de tu saldo de créditos.

Si usas el secreto equivocado, la verificación falla: un aviso de un documento real no calza con whsec_test_, y uno de prueba no calza con whsec_live_.

Lo que conviene saber del modo de prueba

• No cuesta nada. No descuenta créditos ni aparece en tu consumo ni en tus estadísticas. Las recargas y los pagos no están disponibles con una llave de prueba (400 OPERACION_NO_DISPONIBLE_EN_PRUEBA).
• No le llega nada a nadie. Ni correos, ni WhatsApp, ni SMS. Lo que se habría enviado queda en GET /api/fes/mensajes-simulados. Los webhooks a tu sistema sí salen: son justamente lo que estás probando.
• No tiene validez legal. El PDF lleva una marca visible de prueba.
• Los dos modos no se mezclan. Una llave de prueba no ve documentos reales ni una real ve los de prueba: para ella no existen (404).
• Hasta 200 documentos de prueba al día por cuenta. El documento 201 se rechaza con 409 MODO_PRUEBA_TOPE_DIARIO. El contador vuelve a cero a las 00:00, hora de Chile continental.
• Plazo de firma de 3 días como máximo. Si pides más, se acorta a 3 sin error, para que tu código corra igual que en producción.
• Se borran solos. Cada documento de prueba informa su fecha_borrado: 3 días después de que termina o vence.

Errores frecuentes