Saltar al contenido
ValidaFirma

Documentación

Envías el documento. Vuelve firmado a tu sistema.

Un llamado a la API con el PDF y el RUT de cada firmante. ValidaFirma invita a cada uno, verifica su identidad con su cédula y su rostro, y avisa a tu webhook, la URL que indicas al crear el documento, cuando está firmado, para que lo descargues.

Crear cuentaReferencia OpenAPI
Host
api.validafirma.cl
Cuenta personal
X-API-Key
Cuenta corporativa
Authorization: Bearer
01

Un llamado para enviarlo

Un POST en multipart/form-data con el PDF y los firmantes. De cada firmante basta el RUT y el dato del canal por el que le escribimos; el nombre es opcional, y en la evidencia se usa el de la cédula. Este ejemplo corre tal cual con una llave de prueba: el firmante 49999901-1firma solo y tu webhook recibe el aviso, sin que salga un mensaje a nadie.

POST /api/fes/documentosmultipart/form-data
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"
respuesta201 Created
{
  "mensaje": "Documento creado exitosamente",
  "documento": {
    "id": "9f1c2a7e-4b3d-4e6f-8a21-5c0d7e9b1f44",
    "codigo_verificacion": "mu8k2x4p-9A4C71E8",
    "estado": "pendiente",
    "es_prueba": true,
    "sandbox": true,
    "firmantes": [{
      "id": "c81d4e2e-bcf2-4b3a-9d1a-2f6e0c7a5b90",
      "rut": "49999901-1",
      "canal": "whatsapp",
      "estado": "pendiente",
      "es_prueba": true,
      "sandbox": true,
      "url_firma": "https://app.validafirma.cl/firma/eyJ…"
    }]
  },
  "creditos": {
    "consumidos": 0,
    "saldo_restante": 999999,
    "transaccion_id": null,
    "costo_por_firmante": 0,
    "es_prueba": true,
    "sandbox": true
  }
}

Pruebas con la llave de prueba. Pasar a producción es cambiar la llave: el host, el llamado y las respuestas son los mismos. Cómo funciona el modo de prueba.

02

Lo que pasa después, sin que hagas nada

Tu sistema termina su trabajo con el llamado. Desde ahí, el documento avanza solo hasta volver firmado.

  1. 01

    Invita a cada firmante

    Por el canal que elegiste para cada uno: WhatsApp con respaldo por SMS, correo, o nada, si prefieres entregar tú el enlace de firma.

  2. 02

    El firmante lee y acepta

    Abre el documento en su celular y lo lee hasta el final antes de firmar. Si lo pediste, al firmar confirma su correo o su celular con un código, antes de verificar su identidad.

  3. 03

    Verifica su identidad y firma

    Con PINRUT: la primera vez acredita su identidad con su cédula y su rostro; después, prueba de vida y comparación con ese rostro. La firma queda registrada aunque cierre el navegador.

  4. 04

    Sella el documento

    Cuando firma el último, el servidor compone el PDF, lo sella y le pone la fecha y la hora de un servicio externo. Si algo falla, reintenta. Un documento que no pudo sellarse nunca se entrega como firmado: queda como no emitido y te avisamos.

  5. 05

    Lo entrega

    Cada firmante recibe por su canal un enlace propio para descargar el PDF firmado, y por correo, si tiene uno, el PDF adjunto; quien lo envió, un correo con enlace al panel. El webhook no trae el archivo.

  6. 06

    Te avisa

    Tu sistema recibe el aviso firmado en la webhook_url. Si el plazo vence sin que firmen todos, también te avisa.

03

Y un webhook que te avisa cuando vuelve firmado

Cuando el documento queda sellado, tu sistema recibe documento.completado en lawebhook_url que enviaste, con la verificación de cada firmante. Son 12 eventos: 5 cierran el documento —completado, rechazado, cancelado, expirado y no emitido— y 7 son de un firmante, como una invitación que no llegó o una identidad que no coincide.

Cada aviso va firmado con el secreto de tu cuenta, para que compruebes que viene de ValidaFirma, y se reintenta si tu sistema no responde. El PDF no viaja en el aviso: lo descargas con tu llave, conGET /api/fes/documentos/{id}/descargar.

Los eventos y cómo comprobar la firma
  • documento.completadoQuedó sellado
  • documento.rechazadoUn firmante rechazó
  • documento.canceladoSe canceló
  • documento.expiradoVenció el plazo
  • documento.no_emitidoNo se pudo emitir
04

Vías de vuelta

Una vía de vuelta es la forma en que tu sistema se entera de que un documento terminó. Se elige según lo que tu sistema puede hacer, no según lo que prefieras.

Cuál elegir

Tu sistema Vía Respaldo
Recibe llamadas desde internet por HTTPS El webhook (ver webhooks) Una consulta diaria de lo pendiente
No recibe llamadas, pero lee Google Drive, Dropbox u OneDrive La nube (ver nube) para lo firmado Una consulta de lo pendiente
No recibe llamadas ni lee una nube La consulta de lo pendiente cada 15 minutos (ver consulta) La pasada diaria
Una persona con una carpeta que no programa Solo la carpeta en la nube Ninguno

El webhook es la vía principal. La consulta y la nube son alternativas para cuando tu sistema no puede recibir llamadas.

Qué llega a la nube

Con tu llave, la nube entrega el PDF firmado en la carpeta «Firmados», siempre que el archivo de lo firmado esté activo en la conexión de quien conectó la cuenta. Sin el archivo de lo firmado activo no llega nada. Tu sistema reconoce cada archivo por el identificador del documento en el nombre, y con él lo empareja con su registro (ver nube).

En una cuenta corporativa, lo creado en una carpeta llega también a la nube de quienes tienen esa carpeta conectada y la ven en el panel (ver cuenta corporativa).

Por qué la nube necesita un respaldo

Lo rechazado, cancelado, vencido o no emitido nunca llega a la nube, porque no hay nada firmado que archivar. Para enterarte de esos desenlaces, tu sistema consulta lo pendiente.

Lo que no es una vía

El correo que ValidaFirma envía a quien creó el documento acompaña cada evento, pero no es una vía de integración: tu sistema no lo lee ni lo procesa.

Para tu agente

Pregunta a la persona solo si su sitio está publicado en internet. Con esa respuesta eliges la vía; no le preguntes por HTTPS, puertos ni servidores.

05

Las llaves

El llamado es el mismo en las 2 cuentas. Cambia la llave, y la llave decide si lo que haces es de prueba o real. Va siempre en tu servidor, nunca en una aplicación ni en el navegador.

Cuenta personal

X-API-Key: vf_test_… · vf_live_…

Las creas en el panel, en Integraciones, con el botón «Nueva llave», y eliges si es de prueba o de producción. Hasta 10 activas, cada una con su registro de uso y, si quieres, su propia plantilla de correo para las invitaciones.

Cuenta corporativa

Authorization: Bearer …

Las credenciales de máquina de tu empresa en la plataforma de REDCUMBRE: una por sistema, de prueba o de producción, con la carpeta donde quedan sus documentos.

Llaves y carpetas
06

Con tu agente de código

Si integras con un agente de código, como Claude Code, Codex o Cursor, dale la guía de ValidaFirma. El CLI, la herramienta de ValidaFirma para la terminal, se la entrega en vivo: es la misma que muestran estas páginas, y está siempre al día. Todo lo que hace tu agente está enIntegrar con IA.

terminal
npm install -g @redcumbrecl/validafirma-cli
validafirma login
validafirma guia

Necesita Node.js. validafirma login abre tu sesión y deja el skill de ValidaFirma, las instrucciones que tu agente lee al empezar, en ~/.claude/skills y~/.agents/skills. Desde ahí tu agente sabe pedir la guía, y el CLI mantiene el skill al día.

Solo el skill

El skill también se instala por su cuenta, desde github.com/redcumbre/skills. Le dice a tu agente que instale el CLI y lea las instrucciones vigentes, así que no tienes que actualizarlo cuando cambia ValidaFirma.

con npx skills
npx skills add redcumbre/skills
dentro de Claude Code
/plugin marketplace add redcumbre/skills
/plugin install validafirma@redcumbre

Con npx skills queda en el proyecto en que estás; agrega -g para dejarlo en todos tus proyectos. También puedes copiar a mano la carpeta skills/validafirmadel repositorio a ~/.claude/skills/ o a ~/.agents/skills/.

07

Lo que decides tú

Todo es opcional. Sin ninguno de estos campos, la invitación sale por correo —así que cada firmante igual necesita su email—, el documento vence en 7 días (3 con una llave de prueba) y lleva carátula.

canal
WhatsApp, correo o enlace, por firmante. Ver
validar_contacto
El firmante confirma su correo o su celular con un código antes de firmar. Ver
cargo
El cargo del firmante, hasta 80 caracteres. Lo declaras tú y sale en el PDF y en la validación pública. Ver
confidencial
El firmante ve el contenido recién después de verificar su identidad. Ver
cumplimiento_laboral
Para contratos, anexos y otros documentos laborales: cada firmante lleva su correo personal, y ahí recibe el PDF firmado. Ver
dias_expiracion
Cuántos días hay para firmar: de 1 a 30, 7 por defecto. Con una llave de prueba, 3 como máximo. Ver
sin_caratula
El PDF firmado parte directo en tu documento. Ver
politica_de_cierre
Sellar solo cuando firman todos, o también con quienes hayan firmado. Ver
politica_de_rechazo
Si un rechazo anula el documento o si sigue para los demás. Si sigue, publica nombre, RUT, cargo y fecha del rechazo de quien rechazó, y si tiene su identidad verificada. Ver
nombrar_a_quienes_no_firmen
Publica nombre, RUT y cargo de quienes no respondieron, en vez de solo cuántos fueron. Ver
firmante_desatendido_id
Una firma por poder, sin que la persona intervenga. Ver
carpeta_id
En la cuenta corporativa, en qué carpeta nace el documento. Ver

Si firman varias personas y no necesitas la firma de todas, mira lafirma colectivay cómo cerrar un documento y agregar firmantes.

Todos los firmantes reciben la invitación a la vez. Puedes reenviar la invitación a un firmante desde el panel o por la API. Entre dos envíos al mismo firmante, por el mismo canal, pasan 5 minutos. Cada firmante admite 1 reenvío por WhatsApp y 5 por correo; un envío que no llegó no cuenta. A un mismo destinatario se le intenta como máximo 3 veces sin éxito: después, corrige su dato de contacto. En la API, el tope y los intentos rigen desde el 2026-10-29.

08

Referencia

Toda la API de firma cabe en esta tabla. Los esquemas, los códigos de respuesta y los errores están en la referencia OpenAPI, generada desde la misma especificación que sirve la API.

MétodoRutaQué hace
POST/api/fes/documentosCrear un documento para firma
GET/api/fes/documentosListar documentos
GET/api/fes/documentos/{documentoId}Consultar el estado
POST/api/fes/documentos/{documentoId}/reenviar-notificacionesReenviar la invitación a quien falta
PATCH/api/fes/documentos/{documentoId}/cancelarCancelar un documento en curso
GET/api/fes/documentos/{documentoId}/descargarDescargar el PDF firmado y sellado
GET/api/auth/whoamiCon qué llave operas y en qué modo
GET/api/fes/carpetasCarpetas de la cuenta corporativa
GET/api/fes/mensajes-simuladosMensajes que no se enviaron (modo de prueba)
Abrir la referencia OpenAPI
09

Lo que no tienes que construir

Todo lo que pasa entre el llamado y el aviso ocurre fuera de tu app. Tu integración conecta el envío del contrato con la recepción del resultado, y ValidaFirma gestiona lo que ocurre entre ambos. Si tienes que presentárselo a quien decide, la validez legal, el precio y las preguntas de siempre están en la página de la API de firma electrónica.

  • Las pantallas de firma

    El firmante abre su enlace en el celular, sin instalar nada. La lectura, el consentimiento y la firma ya están hechos.

    Cómo funciona

  • La verificación de identidad

    PINRUT verifica la cédula y el rostro. De cada firmante, tu sistema recibe el método, el nombre verificado, el identificador y la fecha del comprobante, y el comprobante firmado. Nunca un dato biométrico.

    Identidad verificada

  • Los mensajes

    La cuenta de WhatsApp, sus plantillas, el respaldo por SMS y los correos. Tú no contratas ni configuras ninguno.

    Los canales

  • El sello y la custodia

    El PDF lleva su sello y su sello de tiempo adentro, y se guarda 6 años. Cualquiera lo valida, sin pedirte nada a ti.

    El documento firmado

Pruébalo con una llave de prueba

Crea tu cuenta, genera una llave de prueba en Integraciones y corre el ejemplo de esta página. Nada se envía ni se cobra. Cuando esté listo, cambias la llave.

Sin costo mensual. Solo pagas lo que usas: $690 más IVA por firma.

Crear cuentaModo de prueba