Prueba la integración entera, con otra llave.

Funciona como el modo de prueba de Transbank. No hay otro servidor ni otra URL: llamas aapi.validafirma.cl con una llave de prueba, y todo lo que hagas con ella es de prueba. El documento se crea, los firmantes avanzan, el PDF sale firmado y sellado, y el webhook llega a tu sistema. Sólo que nadie recibe un mensaje, nadie verifica su identidad y nada se cobra.

El modo lo decide la llave, y nada de la llamada. No existe un campo, un parámetro ni una cabecera que lo pida. Así un olvido en tu código no puede mandar un contrato de verdad como prueba, ni al revés: cuando la integración esté lista, cambias la llave y listo.

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

{
  "mensaje": "Documento creado exitosamente",
  "documento": {
    "id": "9f1c2a7e-4b3d-4e6f-8a21-5c0d7e9b1f44",
    "codigo_verificacion": "mu8k2x4p-9A4C71E8",
    "nombre_original": "contrato.pdf",
    "hash_original": "e3b0c44298fc1c149afbf4c8996fb924…",
    "fecha_creacion": "2026-10-02T14:02:11.000Z",
    "fecha_expiracion": "2026-10-05T14:02:11.000Z",
    "dias_expiracion": 3,
    "estado": "pendiente",
    "metodo_identidad": "pinrut",
    "confidencial": false,
    "es_prueba": true,
    "sandbox": true,
    "fecha_borrado": "2026-10-08T14:02:11.000Z",
    "fecha_borrado_definitiva": false,
    "firmantes": [
      {
        "id": "c81d4e2e-bcf2-4b3a-9d1a-2f6e0c7a5b90",
        "email": null,
        "nombre": null,
        "rut": "49999901-1",
        "canal": "whatsapp",
        "validar_contacto": [],
        "orden_firma": 1,
        "estado": "pendiente",
        "url_firma": "https://app.validafirma.cl/firma/eyJhbGciOi…",
        "es_prueba": true,
        "sandbox": true
      }
    ]
  },
  "creditos": {
    "consumidos": 0,
    "saldo_restante": 999999,
    "transaccion_id": null,
    "costo_por_firmante": 0,
    "es_prueba": true,
    "sandbox": true
  }
}

El documento y el firmante principal de cada respuesta traen es_prueba ysandbox, con el mismo valor. Van siempre, también en real (con false), para que no tengas que distinguir entre un campo ausente y uno falso.

Con qué llave estás operando

La primera llamada de una integración. Responde la cuenta y la credencial, ycredencial.sandbox dice el modo: true con una llave de prueba,false con una real.

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

{
  "cuenta": { "id": "b2c3d4e5-…", "nombre": "Camila Rojas", "modalidad": "personal" },
  "credencial": {
    "tipo": "api_key",
    "nombre": "Mi sistema (prueba)",
    "permisos": ["read", "write"],
    "roles": ["propietario"],
    "sandbox": true
  }
}

Todo el flujo es real, salvo lo que tiene un costo o le llega a una persona. Por eso lo que tu código ve en prueba es lo que verá en producción.

Los dos modos no se mezclan. Una llave de prueba sólo ve documentos de prueba y una real sólo los reales, y un documento nace de prueba o real y lo es para siempre. Lo que mueve dinero de verdad, como una recarga de saldo, responde 400 OPERACION_NO_DISPONIBLE_EN_PRUEBA con una llave de prueba.

Cada modalidad tiene su llave de prueba, y va en la misma cabecera que la real. En las dos, el modo lo decide cómo está registrada la llave, no su texto: si tienes dudas, pregúntale a whoami.

curl -X POST https://api.validafirma.cl/api/fes/documentos \
  -H "Authorization: Bearer $RCAPI_API_KEY" \
  -F "documento=@contrato.pdf" \
  -F 'firmantes=[{"rut":"49999901-1","canal":"email","email":"camila@ejemplo.cl"}]' \
  -F "carpeta_id=3c9e8f20-7a1b-4d55-b6e2-0f4a9d1c7e33" \
  -F "webhook_url=https://tu-sistema.cl/webhooks/validafirma"

En el panel

Las dos cuentas tienen un interruptor «Modo de prueba». Mientras está encendido, una franja en todas las pantallas te lo recuerda («Modo de prueba — lo que ves y lo que creas acá no tiene validez legal»; en el celular, «Modo de prueba — nada de esto tiene validez legal») y ves sólo lo de prueba: los documentos, la bandeja de mensajes simulados y lo que creaste con tus llaves de prueba.

En un documento de prueba, cada uno de estos siete RUT llega solo a su resultado, sin que nadie abra el enlace de firma. Sirven para recorrer cada desenlace, y cada webhook, desde tus pruebas automáticas.

Son RUT válidos y pasan la validación como cualquier otro. Con una llave real no tienen ningún efecto especial: lo que decide es el modo del documento, nunca el número.

Cualquier otro RUT válido se mueve a mano: abres laurl_firma del firmante y, al tocar «Firmar documento», donde un documento real iría a PINRUT, sale la pantalla para simular la verificación, aprobada o rechazada. En un documento confidencial sale antes, en la verificación de acceso. Quien abre el enlace ve la franja «Documento de prueba — no es una firma». Si pediste validar_contacto, el código es siempre123456.

Para mover a un firmante desde tu código, sin abrir su enlace, hay una acción por desenlace. Cada una deja el mismo estado, la misma evidencia y el mismo webhook que el recorrido real, con la marca de prueba. Todas sonPOST sobre /api/fes/documentos/{id}/.

curl -X POST https://api.validafirma.cl/api/fes/documentos/9f1c2a7e-4b3d-4e6f-8a21-5c0d7e9b1f44/firmantes/c81d4e2e-…/simulacion/firmar \
  -H "X-API-Key: $VALIDAFIRMA_API_KEY"

Con una llave real, todas responden 400 OPERACION_SOLO_EN_MODO_DE_PRUEBA, antes de buscar el documento. También responden 400 si el estado del documento o del firmante no permite la acción: vencer, por ejemplo, sólo vale para un documento pendiente al que le falta algún firmante, y si no respondeDOCUMENTO_NO_VENCIBLE. Desbloquear y bloquear tienen los suyos,NO_ESTABA_BLOQUEADO y NO_SE_BLOQUEO.

La bandeja de mensajes simulados

Cada correo, WhatsApp o SMS que un documento de prueba no envió queda aquí, del más reciente al más antiguo: la invitación, el código de firma, el código de contacto, la identidad aprobada, la entrega del firmado, la anulación, el reenvío y los avisos al emisor. Cada mensaje trae el canal, el tipo, el destinatario, el asunto, el texto, el enlace y el código que llevaba. Puedes acotarla condocumento_id, firmante_id o canal, que es email, whatsapp o sms, y paginarla con limit, 50 por defecto y hasta 200, y offset. La respuesta traemensajes y paginacion. La misma bandeja está en el panel, con el interruptor de prueba encendido. Con una llave real responde 404 NO_ENCONTRADO.

curl "https://api.validafirma.cl/api/fes/mensajes-simulados?documento_id=9f1c2a7e-4b3d-4e6f-8a21-5c0d7e9b1f44&canal=whatsapp" \
  -H "X-API-Key: $VALIDAFIRMA_API_KEY"

El PDF de prueba se arma igual que uno real y lleva el sello real, así que puedes comprobar en Acrobat que tu flujo recibe un documento sellado. Dos cosas lo distinguen, y no se pueden quitar:

• Cada página lleva, en rojo y en mosaico, la marca «PRUEBA, sin validez».
• La página de certificado dice «Verificación simulada — modo de prueba» donde un documento real dice cómo se verificó la identidad.

No sale por las descargas públicas: quien tenga el código de verificación no lo puede bajar. Lo descargas con una llave de prueba de tu cuenta, con el mismo GET /api/fes/documentos/{id}/descargar de siempre, y también lo entregan el enlace propio de cada firmante y el panel en modo de prueba. Un documento de prueba no sirve como firma.

200 documentos al día

Por cuenta, contando sólo los de prueba. Se renueva a las 00:00 hora de Chile. El documento 201 del día responde409 MODO_PRUEBA_TOPE_DIARIO.

3 días para firmar

Sin dias_expiracion el plazo es de 3 días, y uno de 3 o menos se respeta. De 4 a 30 se acorta a 3 sin error, para que tu código corra igual que en producción; más de 30 responde 400, igual que en real. La respuesta trae el plazo efectivo en dias_expiracion yfecha_expiracion.

Se borra a los 3 días

Todo se borra 3 días después de que el documento vence o termina (firmado, rechazado, cancelado o no emitido), con sus mensajes simulados. La respuesta trae la fecha en fecha_borrado, y fecha_borrado_definitiva dice si ya es la definitiva: en false mientras el documento está pendiente, porque es «a más tardar», y en true cuando termina, también si venció o quedó no emitido. El borrado lo hace una tarea diaria, así que puede ocurrir hasta un día después de fecha_borrado. Un poder de prueba se borra 3 días después de creado.

Lo que no toca

En prueba la libreta de firmantes está vacía y no se escribe (respondeLIBRETA_NO_SE_USA_EN_MODO_DE_PRUEBA), y no hay carpeta en la nube. La exportación del archivo sí existe: trae sólo los documentos de prueba, y su índice los marca con modo"prueba".

Pasar a real es cambiar la llave. El resto de tu integración, el host, las rutas, el cuerpo de las llamadas y el manejo de los webhooks, queda como lo probaste. Antes del primer documento real, revisa esto:

1. 01

   Cambia la llave

   Una llave real en la misma cabecera: vf_live_… en la cuenta personal, una API key de producción de rCAPI en la corporativa. El host, las rutas y el cuerpo no cambian.

2. 02

   Confírmalo con whoami

   Antes del primer documento real, GET /api/auth/whoami tiene que responder credencial.sandbox: false.

3. 03

   Cambia el secreto de webhooks

   Los avisos reales se firman con el secreto real de tu cuenta (whsec_live_…), no con el de prueba (whsec_test_…). Si tu receptor recibe los dos, elige el secreto según es_prueba de la raíz del aviso.

4. 04

   Saca los RUT de prueba

   Con una llave real los siete RUT de prueba no tienen nada de especial: el documento sale de verdad. Y las rutas de simulación responden 400.

Lo que creaste en prueba no pasa a real: se queda en el modo de prueba hasta que se borra. Cómo comprobar la firma de los avisos está en Webhooks.