Saltar al contenido

Documentación

Prueba la integración entera, con otra llave.

El modo de prueba vive dentro de producción: el mismo host, la misma API y las mismas respuestas. Lo decide la llave con que llamas, y pasar a producción es cambiarla.

01

Modo de prueba

El modo de prueba te deja recorrer todo el flujo sin enviar mensajes a nadie ni cobrar. Se activa con una llave de prueba (empieza con vf_test_), y todo lo que crees con ella queda marcado con es_prueba en verdadero.

Usa datos ficticios en prueba. Los RUT de la tabla de abajo y correos de ejemplo.cl bastan; no uses datos de personas reales.

Los RUT de prueba

Con una llave de prueba, un firmante con uno de estos RUT llega solo a su resultado, sin que nadie abra el enlace de firma:

RUT Resultado
49999901-1 Firma.
49999902-K Verificación rechazada.
49999903-8 Bloqueo.
49999904-6 Rechazo del documento.
49999905-4 En revisión y luego aprobada.
49999906-2 Invitación no entregada.
49999907-0 Nunca actúa: el documento vence en su plazo.

Cualquier otro RUT válido lleva a una pantalla donde el desenlace se elige a mano. Con una llave de producción estos RUT no tienen ningún efecto especial: lo decide el modo del documento, nunca el número.

El código de contacto de prueba es siempre 123456.

Dónde se ven los mensajes

En prueba no sale ningún mensaje. Lo que habría llegado a cada firmante queda en la bandeja: GET /api/fes/mensajes-simulados, o validafirma prueba bandeja. Los mensajes se borran junto con el documento.

Provocar un desenlace a mano

Para llegar a un resultado sin esperar, el modo de prueba tiene acciones de simulación, una por desenlace. Solo funcionan con una llave de prueba y sobre un documento de prueba.

Acción Qué provoca
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/firmar El firmante firma.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/rechazar-verificacion La verificación de identidad se rechaza.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/bloquear El firmante queda bloqueado.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/desbloquear El firmante bloqueado vuelve a poder firmar.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/rechazar-documento El firmante rechaza el documento.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/revision-luego-aprobada La identidad queda en revisión y luego se aprueba.
POST /api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/invitacion-no-entregada La invitación no llega a su destino.
POST /api/fes/documentos/{documentoId}/simulacion/vencer El documento llega, sin esperar su plazo, a lo que le tocaría al vencer: con requiere_todas_firmas=false y alguna firma se sella con quienes firmaron (estado: sellando); si todos los que quedaban rechazaron queda rechazado; si no, expirado.

Desde el CLI, validafirma prueba escenarios lista los RUT de prueba con su resultado, validafirma prueba disparar <evento> crea un documento y corre la acción que produce ese evento, para probar tu webhook de punta a punta, y las acciones de la tabla se corren con validafirma prueba <acción> <documentoId>, como se cuenta en la sección siguiente.

Cuando un documento de prueba espera

Un firmante con un RUT que no es de prueba no llega solo a ningún resultado: el documento queda pendiente y espera que elijas el desenlace. En prueba no sale ningún mensaje, así que nadie va a abrir un enlace por ti. Lo avanzas tú, con una acción de simulación.

Para no armar las rutas a mano, la respuesta ya trae lo que se puede hacer. Cada firmante de un documento de prueba lleva un bloque simulacion, y el documento lleva otro con vencer. Aparece al crear el documento, en su detalle y en la lista de sus firmantes. En un documento real vale null.

{
  "simulacion": {
    "acciones": {
      "firmar": "/api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/firmar",
      "rechazar-documento": "/api/fes/documentos/{documentoId}/firmantes/{firmanteId}/simulacion/rechazar-documento"
    },
    "pantalla": "https://app.ejemplo.cl/public/firma/{token}",
    "cli": "validafirma prueba firmar {documentoId} --firmante {firmanteId}"
  }
}

El ejemplo muestra solo dos de las siete acciones del firmante. acciones son rutas sin servidor, listas para llamar con la llave de prueba. cli es el comando que avanza a ese firmante. pantalla es el enlace donde se elige el desenlace con el navegador, y vale null cuando el firmante ya no puede actuar. Ese enlace sirve para firmar: no lo pongas en un log ni lo compartas.

Desde el CLI:

  • validafirma prueba <acción> <documentoId> [--firmante <id>] corre una acción sobre un firmante. Sin --firmante usa al único firmante que puede actuar, y si hay varios te los lista.
  • validafirma prueba vencer <documentoId> lleva el documento al resultado del vencimiento: se sella con quienes firmaron, queda rechazado o expirado, según su política.
  • validafirma prueba pendientes lista los documentos de prueba que esperan, con el comando de cada firmante.

Aprobar es firmar, rechazar es rechazar-documento: validafirma prueba firmar <documentoId> y validafirma prueba rechazar-documento <documentoId>.

El correo de un documento que espera

Si creas un documento con una llave de prueba y sigue esperando a los 60 segundos, ValidaFirma envía un correo a quien creó la llave. Dice qué firmante espera y trae el enlace de su pantalla, el comando del CLI, la ruta de la API y el enlace al documento en el panel.

  • Es uno por documento, y solo si algún firmante sin RUT de prueba sigue esperando. Si tu sistema lo avanza antes de los 60 segundos, no hay correo.
  • Solo corresponde a una llave de prueba propia de ValidaFirma. La credencial de REDCUMBRE de una cuenta corporativa y los documentos creados desde el panel no lo generan.
  • Se apaga desde la sección de avisos de tu cuenta en el panel, o con validafirma prueba avisos apagar. validafirma prueba avisos muestra si está encendido y validafirma prueba avisos encender lo vuelve a encender. Apagarlo no cambia lo que hace la API: el bloque simulacion sigue en las respuestas.

Límites del modo de prueba

  • Un máximo de 200 documentos de prueba por día, en hora de Chile; después responde MODO_PRUEBA_TOPE_DIARIO.
  • El plazo para firmar es de hasta 3 días.
  • Cada documento de prueba informa su fecha de borrado, y se suprime ese día con todo lo que derive de él. La fecha es el término del documento (firma, rechazo, cancelación, vencimiento o no emisión) más 3 días; mientras está pendiente, es el fin de su plazo para firmar más 3 días, como fecha a más tardar. Después de esa fecha, consultarlo responde 404.
  • Nada se cobra y la nube no existe.

Que un documento de prueba y uno de producción convivan en tu sistema es normal, pero nunca los mezcles: guarda es_prueba y míralo antes de actuar.

Para tu agente

Usa GET /api/auth/whoami para confirmar que la llave es de prueba antes de crear nada. Recorre los siete resultados en prueba, con webhook verificado y deduplicado, antes de proponer pasar a producción.

Si un documento de prueba queda esperando, ofrece avanzarlo con validafirma prueba firmar <documentoId> o validafirma prueba rechazar-documento <documentoId>. Si la persona te pide aprobar o rechazar un documento de prueba, hazlo tú con esos comandos, sin llevarla al panel. Antes de actuar, lee el bloque simulacion de la respuesta o corre validafirma prueba pendientes: ahí está el comando exacto de cada firmante.

02

Pasar a producción

Pasar a producción es empezar a firmar documentos de verdad: llegan mensajes a personas reales y la operación tiene costo. Lo decide la persona que integra, con su sesión.

Antes de pasar a producción

Cada punto de esta lista debe cumplirse. El 404 se explica en consulta.

  • La llave está fuera del código y del repositorio: tu sistema la lee de su configuración.
  • es_prueba se guarda y se mira antes de actuar.
  • Los estados finales están manejados, incluido el 404.
  • Hay una consulta diaria de lo pendiente, programada.
  • Tu sistema guarda su propia copia del PDF en un lugar privado.
  • El código de verificación y url_validacion no aparecen en una página abierta, un índice ni un log, y ni ellos ni el id del documento van en las URL de tu sitio. url_api_descarga y tu credencial no salen de tu servidor.

Además, según la vía:

  • Con webhook: el destino es HTTPS y público, la firma se verifica con el secreto de producción y cada entrega se deduplica.
  • Con consulta: la cadencia respeta el límite de 15 minutos y solo mira lo pendiente.
  • Con la nube: el archivo de lo firmado está activo en la conexión de quien creó la llave, y hay una consulta de pendientes programada.

Cómo se pasa

Si tu sistema corre en el computador donde está el CLI, no copias nada:

  1. Tu sistema tiene dos comandos: uno guarda la llave y el secreto de webhooks de producción en su configuración, recibiéndolos en VALIDAFIRMA_LLAVE_PRODUCCION y VALIDAFIRMA_SECRETO_PRODUCCION sin imprimirlos, y otro comprueba la conexión imprimiendo la respuesta de GET /api/auth/whoami con la llave guardada. La receta de tu tecnología los trae.
  2. Se corre validafirma pasar-a-produccion --instalar "<el primero>" --comprobar "<el segundo>" y apruebas en el navegador, con tu sesión: ahí ves la cuenta, que pasa a producción y el comando que deja la llave.
  3. El CLI crea la llave de producción, la instala con el secreto sin mostrarlos y comprueba que tu sistema quedó en producción con tu cuenta.

Si tu sistema corre en otro lugar, por ejemplo en un hosting:

  1. Corres validafirma pasar-a-produccion y apruebas en el navegador, con tu sesión.
  2. Creas la llave de producción en el panel: /panel/integraciones, botón «Nueva llave», entorno «Producción». La llave se muestra una sola vez.
  3. Copias la llave y el secreto de webhooks de producción a la configuración de tu sistema. No van al código, al repositorio ni a un mensaje.

En una cuenta corporativa la llave la emite REDCUMBRE (ver cuenta corporativa).

Operar en producción

En producción, cada operación que crea, modifica o envía se aprueba en el navegador, con tu sesión: ahí ves qué se hace, en qué cuenta y cuánto cuesta. validafirma api --produccion pide esa aprobación en cada operación.

Costo y saldo

No hay cifras en esta guía. El costo se lee de lo que devuelve la API en el bloque cobro y de la pantalla de aprobación.

El saldo de la cuenta se lee con GET /api/creditos/saldo. En una cuenta corporativa no hay prepago ni saldo: el bloque cobro lo dice, el consumo se informa a tu plan de REDCUMBRE y esa consulta responde MODALIDAD_SIN_CREDITOS.

Para tu agente

Pasar a producción lo decide la persona. Revisa con ella la lista de arriba, explícale qué va a ocurrir y espera su decisión. Inicia validafirma pasar-a-produccion solo cuando ella lo pida, con --instalar y --comprobar si su sistema corre en este computador, y dile que apruebe en el navegador. Nunca pidas la llave ni el secreto de producción por el chat, ni los busques en keys/ ni en las variables.

En producción opera solo con validafirma api. Cada operación que crea, modifica o envía lleva dos confirmaciones: la tuya y la aprobación de la persona en el navegador. Nunca llames la API a mano en producción ni corras el código del sistema con la llave de producción. Muestra a la persona el costo tal como llega.

Esta página muestra la guía del integrador de ValidaFirma, la misma que lee tu agente convalidafirma guia. Versión 4bdd67c3cb79, escrita para la versión 1.0.0 del contrato y publicada el .

Crea tu cuenta y empieza con una llave de prueba

En la cuenta personal la creas en el panel, en Integraciones, con «Nueva llave». Si tu empresa trabaja con la cuenta corporativa, la llave de prueba sale de rCAPI.