Saltar al contenido

Documentación

Lo que pasa con el documento, avisado y firmado.

Un llamado para enviarlo y un webhook que te avisa cuando está firmado. Aquí están los eventos, cómo comprobar que el aviso viene de ValidaFirma y, si tu sistema no puede recibir llamadas, cómo consultar.

01

Webhooks

Un webhook es una URL de tu sistema a la que ValidaFirma avisa cada vez que ocurre algo con un documento. Es la vía principal para enterarte del resultado.

Cómo se configura

Al crear el documento, indicas webhook_url. Debe ser https, en el puerto 443, sin usuario ni clave y hacia una dirección pública; si no, la creación responde WEBHOOK_URL_NO_PERMITIDA. ValidaFirma no sigue redirecciones.

El secreto con el que se firman los avisos está en /panel/integraciones, sección «Webhooks», con los botones «Revelar» y «Copiar». El de prueba empieza con whsec_test_ y el de producción con whsec_live_. El secreto de producción se copia desde el panel a la configuración de tu sistema, y de ahí no sale: ni al código, ni al repositorio, ni a un mensaje.

Los eventos

Evento Cuándo ocurre
documento.completado El documento quedó sellado: firmaron todos los firmantes o se cerró con quienes firmaron, al vencer el plazo o porque lo cerraste tú. cierre.marca dice cuál (firmado_por_todos, cerrado_al_vencer o cerrado_por_el_emisor).
documento.no_emitido El documento no llegó a emitirse.
documento.rechazado Un firmante rechazó el documento.
documento.cancelado Se canceló el documento.
documento.expirado Se cumplió el plazo sin que firmaran todos. Llega solo por webhook.
firmante.rechazado Un firmante rechazó y el documento sigue para los demás.
firmante.firma_tras_rechazo Quien había rechazado firmó el documento.
firmante.bloqueado Un firmante quedó bloqueado.
firmante.identidad_no_coincide La identidad verificada no coincide con la esperada.
firmante.identidad_aprobada Una revisión aprobó la identidad.
firmante.invitacion_no_entregada La invitación no llegó a su destino.
firmante.validacion_contacto_no_lograda El firmante no logró validar su contacto.

Qué trae cada entrega

Cada aviso llega por POST con estas cabeceras:

Cabecera Contenido
X-ValidaFirma-Event El nombre del evento.
X-ValidaFirma-Delivery El identificador de esta entrega.
X-ValidaFirma-Version La versión del formato del aviso.
X-Webhook-Signature La firma, con la forma t=<unix>,v1=<hex>.

El cuerpo es un JSON con evento, timestamp y es_prueba en la raíz; el resto depende del evento.

El PDF firmado no viene en el aviso

El aviso documento.completado no trae el PDF: documento_base64 llega en null. Hay dos caminos para tenerlo, y solo esos:

  1. Descárgalo desde tu servidor con tu llave. El aviso trae url_api_descarga, que es la ruta GET /api/fes/documentos/{id}/descargar: llámala desde tu servidor con la cabecera Authorization: Bearer y tu llave (en una cuenta corporativa, la credencial de máquina), y guarda tu copia en un lugar privado, como lo hacen las recetas. Quien ya integró con X-API-Key puede seguir con ella: sigue vigente.
  2. Envía a tu usuario url_validacion, la dirección del portal de ValidaFirma donde ve su documento. El código de verificación puede acompañarla.

url_validacion puede ir a tu usuario, por correo o dentro de su sesión. url_api_descarga, tu llave y tu credencial nunca van a tu usuario ni a un correo, una página, una URL o un log (ver datos).

El aviso trae además url_descarga, que está deprecada: no la uses ni se la des a nadie. Deja de venir 30 días corridos después del aviso por correo. La fecha exacta está en ese aviso y en la documentación del API.

Un cuerpo de documento.completado, abreviado y con valores ficticios:

{
  "evento": "documento.completado",
  "timestamp": "2026-10-17T14:05:09.000Z",
  "webhook_version": "1.0",
  "es_prueba": true,
  "documento": {
    "id": "<identificador del documento>",
    "es_prueba": true,
    "codigo_verificacion": "<código de verificación>",
    "nombre_original": "contrato.pdf",
    "estado": "firmado",
    "completed_at": "2026-10-17T14:05:08.000Z",
    "url_validacion": "<dirección del portal para tu usuario>",
    "url_api_descarga": "<dirección de descarga del API, para tu servidor>",
    "url_descarga": "<deprecada: no la uses>",
    "documento_base64": null,
    "incluye_documento": false
  },
  "firmantes": [
    { "rut": "49999901-1", "estado": "firmado" }
  ]
}

Cómo se verifica

  1. Lee el cuerpo crudo, tal como llegó, antes de interpretarlo.
  2. Arma el texto <t>.<cuerpo crudo>, con el t de la cabecera.
  3. Calcula el HMAC-SHA256 de ese texto con el secreto del modo del documento.
  4. Compara el resultado con v1, en tiempo constante.
  5. Rechaza el aviso si t se aleja del reloj de tu sistema por más de 300 segundos.

Cuando el secreto se rota, la cabecera trae dos valores v1 y el anterior sigue firmando durante 24 horas: acepta el aviso si cualquiera de los dos coincide.

firma_esperada = hmac_sha256(secreto, t + "." + cuerpo_crudo)
valido = alguna_v1 coincide con firma_esperada (comparación en tiempo constante)

Deduplicación y reintentos

ValidaFirma reintenta un aviso fallido, así que el mismo aviso puede llegar más de una vez. Guarda el valor de X-ValidaFirma-Delivery de cada entrega que procesas y descarta las repetidas. No deduplicas por documento: un mismo documento tiene varios eventos legítimos.

Qué responder

Responde con un código 2xx apenas recibas la entrega, sin hacer trabajo largo antes.

Si tardas más de 30 segundos o respondes otro código, la entrega queda fallida. Se reintenta solo cuando la falla puede ser pasajera:

  • un error de red o el plazo de 30 segundos vencido;
  • un 5xx;
  • un 408, un 425 o un 429.

Cualquier otro 4xx no se reintenta: ValidaFirma lo toma como una respuesta definitiva de tu sistema. Un destino bloqueado o una redirección tampoco se reintentan. Cada aviso se intenta 5 veces en total, con esperas crecientes que parten en 1 segundo.

Probar con el sitio en tu computador

Si el sitio no está publicado en internet, ValidaFirma no puede llamarlo. En modo de prueba, el CLI trae los avisos hasta tu computador y comprueba tu webhook de punta a punta con un solo comando:

validafirma prueba verificar --reenviar-a <dirección local de tu webhook> --crear "<comando que crea un documento de prueba desde tu sistema>"

El comando prueba dos desenlaces, la firma y el rechazo. Por cada uno abre el relay, corre el de --crear con el RUT de prueba de ese desenlace en la variable VALIDAFIRMA_RUT_DE_PRUEBA, sigue los avisos de ese documento hasta su estado final y los reenvía a tu dirección local con los mismos encabezados y la misma firma que la entrega real. Después reenvía el aviso de la firma tal cual, como haría un reintento, y una vez más con la firma alterada. Sale con 0 si cada documento llegó a su desenlace, cada aviso y el repetido recibieron 2xx y el de la firma alterada un 4xx. Si no, sale con 9 y dice qué falló. El resultado queda en .validafirma/verificacion.json.

  • El documento lo crea el código de tu sistema con la llave del proyecto. No hace falta que traiga webhook_url.
  • El RUT del firmante lo toma de VALIDAFIRMA_RUT_DE_PRUEBA: así cada documento llega solo a su desenlace (ver prueba). Sin --crear, el comando sigue un solo documento, el que crees tú.
  • En un WordPress sin enlaces permanentes, la dirección local de una ruta REST es http://localhost:8080/?rest_route=/<espacio>/<ruta>.
  • Tu sistema verifica la firma con el secreto de webhooks de prueba que validafirma webhooks secretos deja en keys/.

Para mirar los avisos sin verificar nada, validafirma webhooks escuchar --reenviar-a <dirección local> los reenvía mientras está abierto. Lo que ocurre con el relay cerrado se pierde. El relay solo trae documentos de prueba creados con la llave del proyecto; nunca uno de producción. validafirma webhooks secretos muestra los secretos de la cuenta, el de prueba entero y el de producción solo por su sufijo.

Para tu agente

Verifica la firma con el secreto de prueba mientras pruebas. En producción, el secreto lo pone la persona en la configuración de su sistema; tú nunca lo lees ni lo pegas.

02

Consulta

Consultar es preguntar a ValidaFirma cómo va un documento. Es la vía de vuelta para un sistema que no puede recibir llamadas, y el respaldo del webhook y de la nube.

Cómo se consulta

Para un documento: GET /api/fes/documentos/{documentoId}. Para varios a la vez: GET /api/fes/documentos con el filtro estado=pendiente, que devuelve solo lo que sigue abierto. Nunca recorras todo el historial en cada pasada.

Cadencia

  • Cada 15 minutos como máximo por documento, y solo lo pendiente.
  • Una pasada diaria de reconciliación sobre lo que tu sistema aún tiene abierto, aunque tengas webhook.
  • Un documento terminado se deja de consultar.

Una consulta más frecuente no te entera antes: solo gasta el límite de uso de tu llave.

Cuándo termina un documento

Los finales son firmado, rechazado, cancelado, expirado y no_emitido. Apenas veas uno, márcalo en tu sistema y deja de consultarlo.

El 404

Un 404 sobre un documento de prueba cuya fecha de borrado ya pasó es final: el documento se borró como estaba previsto. Cualquier otro 404 es un error de configuración, por ejemplo:

  • usas la llave del otro modo (prueba con un documento de producción, o al revés);
  • usas la llave de otra cuenta;
  • en una cuenta corporativa, la llave no tiene acceso a la carpeta del documento.

Con un 404 que no sea el final de un documento de prueba, deja de consultar y avisa a la persona. No lo trates como documento borrado.

Para tu agente

Para saber con qué cuenta y modo estás consultando, usa GET /api/auth/whoami. Si el 404 persiste, no insistas: dile a la persona que no encuentras ese documento y pregúntale de qué empresa es. La llave y el modo los revisas tú.

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 .

Recibe tu primer aviso en modo de prueba

Crea un documento con una llave de prueba y el RUT 49999901-1: firma solo, y documento.completado llega a tu URL, firmado con tu secreto de prueba.