Saltar al contenido

Documentación

Firmantes y opciones: lo que decides tú y lo que pasa solo.

De cada firmante, su RUT y el dato del canal por el que le llega la invitación. Por dónde le llega la invitación, si confirma su correo o su celular y cuánto plazo tiene lo decides en el mismo llamado. Lo demás lo hace ValidaFirma.

01

Firmantes

Un firmante es una persona que debe firmar el documento. Los firmantes se envían al crear el documento, en el campo firmantes, como un arreglo JSON.

Qué se pide de cada uno

  • rut: el RUT de una persona natural, con o sin puntos y guion. Se guarda y se devuelve sin puntos, con guion y con el dígito verificador en minúscula. Se rechaza el RUT de una persona jurídica (desde 50.000.000) y un RUT repetido en el mismo documento.
  • nombre: opcional. La identidad la verifica PINRUT y el documento lleva el nombre verificado.
  • cargo: opcional. El cargo del firmante en este documento, declarado por quien envía, de hasta 80 caracteres. ValidaFirma no lo verifica; se imprime en la página de firmas y se muestra en la validación pública (ver cierre).
  • canal: cómo le llega la invitación.

Cada documento admite de 1 a 100 firmantes. Para sumar firmantes a un documento pendiente, ver cierre. No hay orden de firma: cada persona firma cuando quiera.

Con cumplimiento_laboral (ver documento), cada firmante lleva email con su correo personal, también por WhatsApp o enlace. Si falta, la creación responde VALIDACION_ERROR con firmantes[i].email: obligatorio con cumplimiento laboral, sin crear ni cobrar.

Los tres canales

Canal Qué exige Cómo llega la invitación
email (por defecto) El campo email. Por correo.
whatsapp El campo telefono, en formato internacional de Chile (+56 y nueve dígitos). Por WhatsApp, con respaldo por SMS.
enlace Nada más. ValidaFirma no envía nada: tú entregas la url_firma que devuelve la creación.

El canal depende de cómo prefieren recibir la invitación quienes firman. Con enlace la url_firma es de ese firmante: trátala como una llave y entrégala solo a esa persona.

Validar el contacto

El campo opcional validar_contacto pide que el firmante confirme con un código su correo, su teléfono o los dos antes de firmar. Pedirlo vuelve obligatorio el dato. Con email solo admite telefono; con whatsapp, solo email; con enlace, uno o los dos.

Firmantes desatendidos

Un firmante desatendido ya creado se nombra con firmante_desatendido_id (un UUID) en vez de rut. No admite validar_contacto.

Reenviar una invitación

POST /api/fes/documentos/{documentoId}/reenviar-notificaciones reenvía la invitación a mano. Entre dos envíos al mismo firmante, por el mismo canal y al mismo destinatario, pasan 5 minutos. Cada firmante admite un reenvío por WhatsApp y cinco por correo (un envío que no llegó no cuenta), y a un mismo destinatario se le intenta como máximo tres veces sin éxito. En la API el tope y los intentos rigen desde la fecha de corte que se anuncia el día del despliegue; antes de esa fecha solo rige la espera. El reenvío es parcial: responde enviados y omitidos, y cada omitido trae su motivo (ventana, tope, intentos_fallidos, bloqueado, enlace, firmado; el documento de un poder se omite). Cuando pides un único firmante, el rechazo llega como error: si es muy pronto responde REENVIO_EN_VENTANA (con disponible_desde); si llegó al tope, REENVIO_TOPE_ALCANZADO; si agotó los intentos, REENVIO_INTENTOS_AGOTADOS; si el firmante está bloqueado, FIRMANTE_BLOQUEADO; si ya firmó, YA_FIRMADO.

Ejemplo con datos ficticios

[
  { "rut": "49999901-1", "canal": "email", "email": "firmante@ejemplo.cl" }
]

Para tu agente

Para saber qué canal usar, pregunta a la persona cómo prefiere que le lleguen las invitaciones a quienes firman. En prueba usa solo RUT de prueba y correos de ejemplo.cl. Un error en los datos responde VALIDACION_ERROR con detalles que nombran al firmante y el dato; léelos antes de reintentar.

02

Documento

El documento es el PDF que se envía a firma. Se crea con POST /api/fes/documentos, un formulario multipart.

Qué se envía

Campo Qué es
documento El PDF, de hasta 10 MB.
firmantes El arreglo de firmantes (ver firmantes).
webhook_url Opcional. La URL de tu webhook (ver webhooks).
dias_expiracion Opcional. El plazo para firmar, de 1 a 30 días; en prueba, hasta 3 días.
confidencial Opcional. Que el firmante vea el contenido solo después de verificar su identidad.
cumplimiento_laboral Opcional. Para contratos, anexos y otros documentos laborales: exige email en cada firmante. Se explica más abajo.
sin_caratula Opcional. Omite la carátula inicial de ValidaFirma en el documento firmado. La página de firmas del final va siempre.
requiere_todas_firmas Opcional. true (por defecto): se sella solo cuando firman todos. false: se sella con quienes firmaron, al vencer el plazo o cuando lo cierres antes. Desde este cambio false tiene ese efecto; antes se aceptaba y no tenía ninguno.
politica_de_rechazo, nombrar_a_quienes_no_firmen Opcionales. Qué pasa si alguien rechaza y si se nombra a quienes no firmen. Publican datos de terceros: léelos en cierre antes de usarlos.
idempotencyKey Opcional. Una clave tuya para repetir la llamada sin duplicar.

El plazo lo fija quien envía el documento, según el tiempo que necesita su firmante.

Un documento confidencial

Con confidencial, el firmante ve el contenido solo después de verificar su identidad con PINRUT, y la dirección pública del documento no entrega su PDF (responde DOCUMENTO_CONFIDENCIAL). Úsalo cuando el contenido no deba circular.

Un documento laboral

Con cumplimiento_laboral, ValidaFirma envía automáticamente el documento firmado al correo personal de cada firmante. Pide el correo personal del trabajador: ahí le llega el PDF firmado. Lo declaras tú y ValidaFirma no lo comprueba. También si el documento es confidencial: el PDF va adjunto al correo que informas, sin que el firmante lo confirme.

Cada firmante lleva email, también si le llega por WhatsApp o por enlace (ver firmantes). El firmante desatendido queda exento: se usa el correo de su poder. La opción se elige al crear y no se puede cambiar después; la respuesta la confirma con cumplimiento_laboral: true, y los firmantes que agregues después cumplen la misma regla.

Repetir una llamada sin duplicar

Si tu sistema puede repetir la creación (por un corte de red, por ejemplo), envía siempre la misma idempotencyKey de 1 a 128 caracteres. Con la misma clave y el mismo formulario, la respuesta es el documento ya creado y trae la cabecera Idempotent-Replayed: true y, en el cuerpo, idempotencia: { clave, repetida: true }: no invita ni cobra de nuevo. La primera respuesta trae repetida: false, y sin clave el campo no aparece. La clave recuerda el formulario: si la repites con otro PDF u otros firmantes, la respuesta es 422 IDEMPOTENCIA_EN_CONFLICTO y no se crea ni se cobra nada. Si la primera llamada sigue en curso responde IDEMPOTENCIA_EN_CURSO; si quedó inconclusa, IDEMPOTENCIA_INCONCLUSA. La clave debe ser única por documento en toda tu cuenta: genérala una vez, por ejemplo con un UUID, guárdala con el documento y reúsala en cada reintento. El número interno del contrato solo no basta, porque se repite si reinstalas tu sistema o si otro sistema usa la misma cuenta.

Qué devuelve la creación

Devuelve el documento (con su id, su codigo_verificacion y sus firmantes) y el bloque cobro, que dice el modo (prueba o produccion) y lo que se cobra o consume, tal como corresponde a tu cuenta. En una cuenta corporativa ValidaFirma no cobra: se informa a su plan de REDCUMBRE.

Cancelar

PATCH /api/fes/documentos/{documentoId}/cancelar cancela un documento que sigue pendiente. Es una operación que modifica: en producción lleva la doble confirmación de producción.

Errores de la creación

Código Qué hacer
VALIDACION_ERROR Lee detalles y corrige el dato que nombran.
WEBHOOK_URL_NO_PERMITIDA Usa una URL https pública, en el puerto 443, sin usuario ni clave.
MODO_PRUEBA_TOPE_DIARIO Se alcanzó el tope diario de documentos de prueba; espera al día siguiente.
IDEMPOTENCIA_EN_CONFLICTO Usaste una idempotencyKey que ya creó otro documento. Genera una clave nueva para este documento.
DOCUMENTO_NO_ENCONTRADO El documento no existe para esta llave (ver consulta).

Para tu agente

Pregunta a la persona cuántos días tiene su firmante para firmar. En producción usa ese plazo; en prueba usa 3 días, el máximo del modo, aunque ella haya pedido más, y díselo. Muestra a la persona el bloque cobro tal como llega.

Los datos de la persona (el PDF y los RUT) no van a la conversación ni a un log: trabaja con el archivo en disco. El id y el código de verificación tampoco van a la conversación ni a un log.

03

Cierre y firmantes agregados

Por defecto un documento se sella solo cuando firman todos, y un rechazo lo anula para todos. Este tema cuenta cómo cambiar esas dos reglas al crear el documento, qué se publica cuando lo haces, cómo agregar firmantes a un documento pendiente y cómo cerrarlo antes del plazo.

El cargo de cada firmante

cargo es un campo opcional de cada firmante, en la creación y al agregar. Es el cargo del firmante en este documento, declarado por quien envía: texto libre de hasta 80 caracteres, por ejemplo "Prevencionista de riesgos". ValidaFirma no lo verifica. Se imprime en la página de firmas del PDF y se muestra en la validación pública, marcado como declarado por el emisor. Escribe solo el cargo, sin otros datos de la persona.

Sellar con quienes firmaron

requiere_todas_firmas decide qué pasa si al vencer el plazo falta alguna firma:

  • true, el valor por defecto: el documento se sella solo cuando firman todos. Si al vencer falta una firma, pasa a expirado.
  • false: se sella apenas firmen todos o, si no, con quienes hayan firmado, al vencer el plazo o cuando lo cierres antes (ver más abajo). Sin ninguna firma, vence a expirado igual.

Desde este cambio, false significa «se sella con quienes firmaron»; antes se aceptaba y no tenía efecto. politica_de_cierre es el mismo dato con nombre: firman_todos equivale a true y sella_con_quienes_firmaron a false. Si indicas los dos y se contradicen, la creación responde POLITICA_DE_CIERRE_CONTRADICTORIA y no crea ni cobra nada.

Seguir aunque alguien rechace

politica_de_rechazo vale anula (por defecto: el rechazo anula el documento para todos) o no_anula. Con no_anula, el documento sigue para los demás y quien rechazó puede firmarlo después, mientras el documento no se cierre. Por eso, con un rechazo, el documento no se sella antes del vencimiento, con dos excepciones: que lo cierres antes (solo con requiere_todas_firmas=false) o que quien rechazó lo firme y con eso hayan firmado todos; en ese caso se sella en ese momento y llega documento.completado antes del vencimiento. Si al vencer nadie firmó y todos rechazaron, el documento queda rechazado. Un valor distinto de anula y no_anula responde POLITICA_DE_RECHAZO_INVALIDA.

Qué se publica. Al indicar no_anula, el nombre, el RUT, el cargo y la fecha del rechazo de quien lo tenga rechazado al sellarse, y si tiene su identidad verificada, quedan en la página de firmas del PDF y en la validación pública del documento. El motivo del rechazo no se publica.

Nombrar a quienes no firmen

nombrar_a_quienes_no_firmen solo tiene efecto con requiere_todas_firmas=false. Por defecto está apagado: la página de firmas y la validación pública dicen cuántas personas no firmaron, sin nombrarlas.

Qué se publica. Encendido, el nombre, el RUT y el cargo de quienes no hayan firmado ni rechazado al cerrarse quedan en la página de firmas del PDF y en la validación pública. Enciéndelo solo si la persona que te encargó la integración lo pidió.

Agregar firmantes a un documento pendiente

POST /api/fes/documentos/{documentoId}/firmantes suma firmantes a un documento que sigue pendiente, con la misma estructura de cada firmante que al crear (ver firmantes).

  • Confirmación: envía invitaciones y cobra, así que en producción lleva la doble confirmación de producción.
  • Cobro: se cobra por cada firmante agregado, al responder, con el mismo bloque cobro de la creación. En prueba no se cobra; en una cuenta corporativa ValidaFirma no cobra y se informa a su plan de REDCUMBRE.
  • Plazo: el firmante agregado tiene el plazo que le queda al documento; su enlace de firma vence con el documento.
  • Tope: un documento admite hasta 100 firmantes, contando los que ya tiene y los que agregas. El RUT de un agregado no puede repetirse con el de un firmante que ya está en el documento.
  • Estados: no se agrega a un documento cancelado, rechazado, vencido ni ya firmado por todos. Un firmante agregado no se quita ni se reemplaza.
  • Si la llamada se rechaza, nada se cobra ni se convoca.

Errores de agregar:

Código Qué hacer
VALIDACION_ERROR Lee detalles: nombran al firmante y el dato (incluye pasar de 100 firmantes en el documento).
DOCUMENTO_EN_PREPARACION El documento ya está firmado por todos y se está preparando. No se agrega nada.
DOCUMENTO_EN_OPERACION Otra operación está cambiando el documento. Reintenta después de los segundos que dice Retry-After.

Cerrar antes del plazo

POST /api/fes/documentos/{documentoId}/cerrar cierra el documento antes de que venza su plazo y lo sella con las firmas que ya tiene. Es una operación que actúa sobre un documento ya enviado a firma: en producción lleva la doble confirmación de producción.

  • Solo funciona en un documento pendiente creado con requiere_todas_firmas=false, y con al menos una firma.
  • No cobra, no devuelve créditos y no avisa a quienes no firmaron. Si alguien abre su enlace, verá que el documento ya se cerró.
  • La respuesta es 202: el documento sigue pendiente mientras se prepara y pasa a firmado con la marca cierre.marca igual a cerrado_por_el_emisor. Al terminar llega documento.completado, con el bloque cierre del documento, que dice cuántos se convocaron y cuántos firmaron.

Errores de cerrar:

Código Qué hacer
CIERRE_ANTICIPADO_NO_DISPONIBLE El documento exige que firmen todos. La salida que queda es cancelarlo.
SIN_FIRMAS Nadie ha firmado todavía, así que no hay nada que cerrar. Espera una firma o cancélalo.
DOCUMENTO_EN_PREPARACION El cierre ya está en curso.
DOCUMENTO_EN_OPERACION Otra operación tiene el documento. No se cerró nada; reintenta.

Los eventos del rechazo que no anula

Con no_anula, el rechazo de un firmante llega como firmante.rechazado, con datos: { motivo } (o null), en vez de documento.rechazado, y el documento sigue. Si quien rechazó firma después, llega firmante.firma_tras_rechazo, con datos: {} y el estado firmado del firmante. La forma de cada aviso y su verificación están en webhooks.

Para tu agente

No enciendas requiere_todas_firmas=false, politica_de_rechazo=no_anula ni nombrar_a_quienes_no_firmen por tu cuenta: pregunta a la persona qué quiere que pase si alguien no firma o rechaza, y dile con las palabras de este tema qué se publica y dónde antes de crear el documento. Antes de cerrar un documento, dile cuántas firmas tiene y cuántas personas quedan fuera. Los datos de las personas no van a la conversación ni a un log.

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 .

Recorre cada desenlace antes de salir a producción

Con una llave de prueba, cada RUT de prueba llega solo a su resultado: firma, bloqueo, verificación rechazada o vencimiento. No sale ningún mensaje y no se cobra.