validafirma — CLI de ValidaFirma

Opera ValidaFirma desde la terminal o desde un agente: inicia sesión, crea tu llave de prueba, llama a cualquier operación del API y prueba webhooks, sin copiar llaves a mano.

Instalación

npm install -g @redcumbrecl/validafirma-cli      # requiere Node 20 o superior
validafirma --version

Después de instalar, corre validafirma login; luego validafirma guia te enseña cómo integrar (la lee sin sesión ni llave).

Inicio de sesión

validafirma login              # con terminal: abre el navegador (PKCE contra ZITADEL) y guarda la sesión
validafirma login --json       # sin terminal (un agente): imprime { "url", "codigo", "vence", "siguiente" } y sale
validafirma login --completar  # espera a que la persona entre con el enlace y el código, y guarda la sesión
validafirma logout           # revoca y borra la sesión

La sesión vive en $XDG_CONFIG_HOME/validafirma/sesion.json (0600), nunca dentro del proyecto. Sin terminal se usa el código de dispositivo (RFC 8628): nadie copia una dirección de vuelta.

La guía del integrador

validafirma guia             # índice de temas y reglas
validafirma guia <tema>      # un tema; con --json, un solo JSON
validafirma guia instrucciones  # las instrucciones vigentes para el agente; el skill instalado manda a leerlas

No necesita sesión ni llave. Si no hay red, lee la última copia que guardó.

Quitar la pieza del integrador

login e init dejan una pieza que orienta a tu asistente. Para quitarla (no vuelve):

validafirma pieza quitar             # la del usuario
validafirma pieza quitar --proyecto  # la del proyecto actual

Preparar un proyecto

validafirma init                           # crea la llave de PRUEBA y deja los archivos del proyecto
validafirma init --cuenta <id>             # cuando tienes varias cuentas
validafirma init --archivo-de-llave <ruta> # cuenta corporativa: usa la llave que ya entregó el CLI de REDCUMBRE

init nunca pregunta el ambiente: siempre es prueba. Deja:

• keys/validafirma-prueba.json: el JSON de la llave { llave, llaveId, nombre, prefijo, modo } (0600).
• .env con sólo VALIDAFIRMA_LLAVE_PRUEBA=keys/validafirma-prueba.json.
• .validafirma/estado.json: cuenta y ambientes, sin ningún secreto.
• .gitignore con keys/, .env y .validafirma/.

En una cuenta corporativa la llave la entrega el CLI de REDCUMBRE (redcumbre llaves validafirma …); si no está instalado, init sale con código 5 y te dice cómo instalarlo.

Pasar a real

validafirma pasar-a-real
validafirma pasar-a-real --instalar "<comando>" [--comprobar "<comando>"]

Lista lo que falta, muestra los avisos y abre la aprobación de la llave real: la decisión es de una persona, en el navegador, con su sesión de ValidaFirma. Con terminal te pide además escribir el nombre de la cuenta y espera a que apruebes. Sin terminal, o con --json, un agente puede iniciarla: la primera corrida abre la aprobación y sale con código 3 y la dirección (error.aprobacion.url); cuando la persona la aprueba, la segunda corrida, con el --aprobacion <id> que trae error.comando, crea la llave. Una aprobación pendiente, rechazada o vencida no crea nada. Deja keys/validafirma-real.json (0600); no toca .env.

Instalar la llave en tu sitio sin copiarla. --instalar "<comando>" es el comando que guarda la llave real y el secreto de webhooks real en la configuración de tu sitio. La página de aprobación lo muestra («La llave real se instalará en tu sitio con este comando»), y el comando que corre el CLI tiene que ser ese mismo. Ya creada la llave, el CLI lo corre con sh -c en la raíz del proyecto, con la llave real en VALIDAFIRMA_LLAVE_REAL y el secreto de webhooks real en VALIDAFIRMA_SECRETO_REAL. Ni la llave ni el secreto se imprimen ni se escriben en tu proyecto (la llave queda, como siempre, en keys/validafirma-real.json): la salida del comando va a stderr con cualquier aparición suya cambiada por [oculto]. Por ejemplo, para WordPress en Docker:

validafirma pasar-a-real --instalar 'docker compose exec -T -e VALIDAFIRMA_LLAVE_REAL -e VALIDAFIRMA_SECRETO_REAL wordpress sh -c "wp option update vf_llave \"\$VALIDAFIRMA_LLAVE_REAL\" && wp option update vf_secreto \"\$VALIDAFIRMA_SECRETO_REAL\""'

--comprobar "<comando>" (recomendado) corre después un comando de tu sitio que llama GET /api/auth/whoami con la llave que el sitio guardó e imprime la respuesta JSON del API. El CLI exige que whoami diga que la credencial no es de prueba y que cuenta.id sea el de la cuenta del proyecto; si pasa, dice «✓ Tu sitio quedó en modo real con la cuenta …». Si el comando de --instalar o el de --comprobar fallan, la llave real ya quedó creada en keys/ y el CLI sale con código 9 (INSTALACION_FALLIDA o COMPROBACION_FALLIDA) sin mostrar ningún valor. --instalar es de una cuenta personal.

Desde la versión 0.2.0 el servidor no crea una llave real sin esa aprobación: el CLI 0.1.0 ya no puede pasar a real en una cuenta personal. En una cuenta corporativa la llave la emite REDCUMBRE; actualiza a 0.2.0 para que el CLI te pida la aprobación antes de pedirla.

Llamar al API

validafirma api                          # lista las operaciones
validafirma api buscar <texto>
validafirma api describir <operación>
validafirma api <operación> --<parámetro> <valor> [--cuerpo @archivo.json] [--documento @ruta.pdf]

El nombre de la operación es su operationId; si no lo tiene, el derivado método.ruta con los segmentos separados por punto, por ejemplo post.fes.documentos o get.fes.documentos.documentoId. Dos operaciones con el mismo derivado hacen salir al CLI con código 7. El contrato se baja de /api-docs/openapi.json con ETag; sin red usa la última copia y lo avisa.

• Lo real se pide con --real en cada llamada. Sin --real siempre se usa la llave de prueba; ninguna variable de entorno cambia eso.

• En real, toda operación que no sea una consulta pide --confirmar <id de la cuenta> cuando no hay terminal; sin eso sale con código 3 y te imprime el comando completo. La decisión sale de x-validafirma-efecto, no del método.

• Lo que crea, modifica, envía o se cobra en real lo aprueba una persona en el navegador. Con --real --confirmar el CLI abre la aprobación y te muestra su URL. La página dice qué se va a hacer, en qué cuenta y cuánto cuesta, y la aprueba sólo la misma persona, con su sesión y permiso en la cuenta:

  • con terminal, el CLI abre el navegador y espera;
  • sin terminal, sale con código 3 y FALTA_LA_APROBACION_DE_LA_PERSONA, con error.aprobacion (id, url, venceEl) y en error.comando el mismo comando con --aprobacion <id>. Lo vuelves a correr cuando la persona apruebe.

  La aprobación vence a los 10 minutos, sirve para esa petición exacta y se usa una sola vez. --ensayo no abre ninguna.

  Los archivos adjuntos (--documento @ruta.pdf) se leen antes de pedir la aprobación, y la aprobación cubre su contenido, no su nombre: la página muestra la huella (sha256) de cada archivo. Si cambias el archivo entre que apruebas y que corres el comando con --aprobacion, la petición ya no es la aprobada, el servidor responde APROBACION_NO_COINCIDE y no se ejecuta nada: tienes que aprobar de nuevo. Un archivo que no existe, o una ruta con .., sale con su error de entrada sin abrir ninguna aprobación.

• --ensayo arma la petición y la muestra sin enviarla.

• Las operaciones que declaran idempotencia imprimen su clave (stderr, y clave en el JSON). Para reintentar tras una caída: --clave <clave>.

• Costo: en una cuenta personal se muestra el precio antes y el cobro después; en una corporativa, «se informa a tu plan de REDCUMBRE».

• La salida es el cuerpo de la respuesta del API tal cual. En modo agente (--json o sin terminal) es un único JSON en stdout, el texto va a stderr y no se lee stdin.

Herramientas de prueba

validafirma prueba estado
validafirma prueba escenarios
validafirma prueba bandeja [--documentoId <id>]
validafirma prueba disparar <evento>
validafirma webhooks escuchar --reenviar-a http://localhost:3000/webhook
validafirma webhooks secretos
validafirma prueba verificar --reenviar-a http://localhost:3000/webhook --crear "./crear-documento-de-prueba.sh"

prueba verificar prueba la firma y el rechazo. Por cada uno abre el relay, corre el comando de --crear con el RUT de prueba de ese desenlace en VALIDAFIRMA_RUT_DE_PRUEBA, sigue los avisos del documento hasta su estado final y los reenvía a tu webhook; después reenvía el de la firma tal cual y con la firma alterada. Sale con 0 si cada documento llegó a su desenlace, cada aviso y el repetido recibieron 2xx y la firma alterada un 4xx; si no, con 9. Deja el resultado en .validafirma/verificacion.json.

webhooks secretos deja el secreto de prueba en keys/ (0600) y apunta VALIDAFIRMA_SECRETO_WEBHOOKS_PRUEBA en .env. Del real te muestra sólo los últimos caracteres y dónde copiarlo en el panel: nunca llega a la terminal.

Usan siempre la llave de prueba. Un evento que no se puede disparar sale con código 8 y explica por qué.

Variables

VALIDAFIRMA_API_URL (por omisión https://api.validafirma.cl), VALIDAFIRMA_ID_URL (https://id.redcumbre.cl), VALIDAFIRMA_LLAVE_PRUEBA (la ruta de la llave de prueba, la escribe init), VALIDAFIRMA_NPM_URL (el registro para el aviso de versión, https://registry.npmjs.org).

Conformidad con las reglas de CLIs para agentes: ver CONFORMIDAD.md.