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
Lo mínimo
El llamado lleva dos campos obligatorios: documento, el PDF de hasta 10 MB, yfirmantes, un arreglo JSON de 1 a 20 personas. De cada firmante son obligatorios surut y el dato de su canal. Como el canal por defecto es email, sin canal hay que mandar email: sólo con canal enlace basta el RUT. Un firmante por poder va con su firmante_desatendido_id, sin RUT.
Una persona natural. Un RUT de persona jurídica (desde 50.000.000) se rechaza con «RUT de persona jurídica no admitido», y el RUT se valida con su dígito verificador.
Sin repetir. El mismo RUT dos veces en un documento se rechaza con «RUT repetido (igual al de firmantes[i])».
El nombre es opcional y sirve de referencia: de 2 a 255 caracteres. Si mandas nombre, se guarda y la invitación lo usa para saludar; si no, el correo saluda «Estimado/a» seguido del RUT y el WhatsApp dice «firmante». En la evidencia —el PDF, la validación y el webhook— manda el nombre de la cédula.
Todos los firmantes reciben la invitación al mismo tiempo y cada uno firma cuando puede. No hay firma en orden: el orden de la lista sólo decide cómo aparecen en las respuestas.
Los ejemplos usan la cabecera de la cuenta personal, X-API-Key. En la cuenta corporativa cambia sólo esa línea, por Authorization: Bearer con la credencial de máquina de la empresa en la plataforma de REDCUMBRE, más X-Cuenta-Id si esa credencial alcanza más de una cuenta. Todo lo demás de esta página vale igual en las dos: llaves y cuenta corporativa.
Cada firmante tiene su canal, y en un mismo documento pueden convivir los tres. El canal decide qué dato es obligatorio y por dónde salen la invitación y, al final, el documento firmado.
Los tres canales de invitación y lo que exige cada uno
Canal
Exige
La invitación
Al terminar
emailpor defecto
email
Un correo con el enlace de firma.
Un correo con su enlace propio de descarga.
whatsapp
telefono: +56 seguido de 8 o 9 dígitos
Un WhatsApp con un botón al enlace de firma. Si no se entrega, sale un SMS con el mismo enlace.
Un WhatsApp con un botón a su enlace propio, con el mismo respaldo, y un correo si informaste uno.
enlace
Sólo el rut
Nada. Tú le entregas su url_firma por donde quieras: tu aplicación, tu correo, tu chat.
Un correo con su enlace de descarga si informaste uno. Si no, ValidaFirma no le manda nada: si faltan firmas, su pantalla final le dice que el documento firmado le llegará por quien se lo envió; si fue el último, que lo descarga desde ese mismo enlace cuando esté listo.
La respuesta trae la url_firma de cada firmante, cualquiera sea su canal.
Para invitar, un dato que el canal no usa no se usa: un firmante de canal email que trae telefono no recibe ningún WhatsApp ni SMS, salvo que pidas validar ese celular. Al cierre, en cambio, todo firmante con correo recibe también por correo su enlace de descarga, sea cual sea su canal.
Si no llegan ni el WhatsApp ni el SMS de la invitación, recibesfirmante.invitacion_no_entregada y el emisor, un correo.
POST /api/fes/documentostres firmantes, tres canales
El mismo ejemplo fija un plazo de 10 días y marca el documento como confidencial. Las dos opciones están más abajo.
03
Validar el contacto
Con validar_contacto le pides al firmante que confirme, con un código, que el correo o el celular que tienes de él son suyos. Es un arreglo con email, telefono o los dos, y pedirlo vuelve obligatorio ese dato. No es una verificación de identidad: ésa la hace PINRUT, siempre.
Qué se puede pedir según el canal
email
["telefono"]
whatsapp
["email"]
enlace
["email"], ["telefono"] o los dos
El medio por el que salió la invitación no se pide: con canal email owhatsapp, y sólo si la invitación salió, ese medio queda informado como validado con origen invitacion. Un firmante por poder no admitevalidar_contacto.
Cómo lo vive el firmante
Al tocar «Firmar documento», antes de PINRUT, lee: «Quien te envió este documento pidió comprobar tu correo o tu teléfono. Te enviaremos un código de 6 dígitos que vale 15 minutos. Esto comprueba que el medio es tuyo y no es una verificación de identidad. Usamos ese dato sólo para esta comprobación y no lo cedemos a terceros.»
El código le llega al celular por WhatsApp, con respaldo por SMS, o a su correo. Vale 15 minutos y admite 5 intentos.
Puede pedir hasta 5 códigos, y al pedir el quinto empieza una espera de 24 horas. Cuando ese quinto código vence o agota sus 5 intentos sin validar, tú recibes, una sola vez,firmante.validacion_contacto_no_lograda.
Es obligatorio para firmar, no para rechazar. Un medio validado queda validado aunque PINRUT falle después.
En documento.completado, cada firmante trae medios_validados: el medio y su origen, invitacion o codigo. En el modo de prueba no sale ningún código y el que vale es siempre 123456.
04
Documento confidencial
Con confidencial=true, nadie ve el contenido sin haber verificado su identidad. La invitación dice exactamente lo mismo que la de un documento normal: el carácter confidencial no se anuncia en el mensaje.
Fuera del recorrido del firmante, la descarga pública por código responde403 REQUIERE_VERIFICACION, salvo que un firmante del documento verifique su identidad al descargar. Antes de que firmen todos no hay nada que descargar: responde400 DOCUMENTO_NO_DISPONIBLE.
01El primer paso le dice «Primero confirmas quién eres, después lees y decides»: el documento es confidencial, verificarse no es firmar, y después podrá leerlo y decidir.
02Verifica su identidad con PINRUT y se abre un acceso de 4 horas: lee el documento, sin poder descargarlo. Vencido, vuelve a verificarse.
03Para firmar hace una segunda verificación, la de firma. Rechazar sólo se puede con el acceso vigente: sin él, responde 400 REQUIERE_VERIFICACION_DE_ACCESO.
04Firmado, su enlace propio de descarga le pide otra vez PINRUT.
05
Plazo y vencimiento
dias_expiracion fija cuántos días tienen los firmantes para firmar: de 1 a 30, y 7 si no lo mandas; más de 30 se rechaza con 400. Con una llave de prueba el plazo se acorta: sindias_expiracion quedan 3 días, con 1 o 2 quedan esos, de 4 a 30 se acortan a 3, y más de 30 se rechaza igual. La respuesta trae la fecha exacta en fecha_expiracion.
Vence solo: la revisión corre al minuto 11 de cada hora, así que un documento pendiente con el plazo cumplido pasa a expirado a más tardar una hora después, sin que nadie lo consulte. Sólo vence los documentos a los que les falta algún firmante. Los firmantes quedan como estaban.
Recibes documento.expirado con la fecha de expiración y los firmantes que faltaban. A diferencia de casi todos los eventos, no le llega también al emisor por correo.
No se reactiva: para volver a intentarlo, creas un documento nuevo. Reenviar o cancelar uno vencido responde400 DOCUMENTO_VENCIDO, y el firmante que abre su enlace ve que venció y que pida uno nuevo a quien se lo envió.
06
Sin carátula
El PDF firmado tiene tres partes: una carátula, tu documento original y la página de certificado, con los datos de cada firmante. Con sin_caratula=true se omite la primera y el PDF empieza directo en tu documento. La página de certificado y el sello van igual: son la prueba.
07
Firma por poder
Cuando una misma persona firma muchos documentos de la cuenta —el empleador en los contratos de cada trabajador, por ejemplo—, puede firmar una vez un poder, verificándose con PINRUT, y autorizar que su firma electrónica simple se aplique a esos documentos sin intervenir cada vez.
En el llamado, ese firmante va con firmante_desatendido_id en lugar de su RUT y su canal. Su firma se registra al crear el documento, sin que la persona intervenga; consulta el estado conGET /api/fes/documentos/{id}. En la página de certificado, su recuadro dice «Firma automática por poder» y, debajo, «Poder firmado con PINRUT: {nombre}» o «Poder firmado con código de verificación (OTP)», en los poderes antiguos, que siguen vigentes. No admitevalidar_contacto.
El poder lo inscribe una persona —el dueño de la cuenta personal o un administrador de la corporativa—, que figura en él como «APODERADO». Lo firma la persona inscrita, como «PODERDANTE (FIRMANTE)», con la invitación que le llega a su correo. El firmante_desatendido_id lo recibe quien inscribe, en la respuesta de la inscripción y con «Copiar ID para API» en el panel; la persona inscrita no lo recibe. Nunca una llave inscribe un poder: las llaves sólo lo usan.
Vence al año, y uno de prueba a los 3 días. El vencimiento se aplica una vez al día, a las 10:00, así que puede seguir firmando hasta cerca de 24 horas después. Se pausa o se revoca cuando se quiera.
Un poder de prueba firma sólo documentos de prueba, y uno real sólo reales. Cruzarlos se rechaza al crear con 409 PODER_DE_OTRO_MODO, diciendo el modo de cada uno.
No sirve para actos que exigen la presencia de la persona o una solemnidad.
Desde que creas el documento, todo esto pasa sin que tu sistema haga nada. Para quien integra es siempre el mismo llamado, sea la primera vez que la persona firma con PINRUT o la décima.
01Recibe la invitación por su canal. Quien envía aparece con un solo nombre: en la cuenta corporativa, la razón social de la empresa, nunca el de la persona que creó el documento.
02Acepta el aviso del primer paso: «Primero lees, después decides». Se guardan la versión del texto aceptado, la hora, la IP y el navegador.
03Lee el documento hasta el final: para firmar es obligatorio, y la lectura se registra al llegar al 95 %. Para rechazar no hace falta.
04Toca «Firmar documento», con el texto «Al presionar «Firmar documento» declaras que lo leíste completo y que quieres firmarlo». Si lo pediste, valida su correo o su celular con un código.
05Verifica su identidad con PINRUT: la primera vez en PINRUT acredita su identidad con su cédula y su rostro; después, prueba de vida y comparación con ese rostro. La firma se registra apenas PINRUT autoriza, y la pantalla se lo dice: «Tu firma queda registrada aunque cierres esta ventana.»
06Cuando firma el último, el PDF se compone, se sella y lleva la fecha y la hora que estampa un servicio externo e independiente, con reintentos. Un documento que no pudo sellarse nunca se entrega como firmado: queda como no emitido y te avisamos.
07Cada firmante recibe por su canal, y por correo si tiene uno, un enlace propio para descargar el PDF; un firmante de canal enlace sin correo no recibe nada. El emisor recibe un correo con enlace al panel, y tu sistema, documento.completado. El PDF no viaja adjunto en ninguno.
Si algo no sale
Cinco verificaciones fallidasEl firmante queda bloqueado 24 horas y recibes firmante.bloqueado con bloqueado_hasta. El bloqueo no anula el documento ni impide firmar a los demás. Un firmante bloqueado puede rechazar, pero no recibe reenvíos.
La cédula es de otra personaRecibes firmante.identidad_no_coincide cada vez que pasa, no sólo al quinto intento. El intento suma al mismo tope de cinco y el documento sigue pendiente. El aviso no trae ningún dato de quien se presentó.
Rechaza el documentoRechazar no exige PINRUT ni leer el documento hasta el final, pide una confirmación explícita y admite un motivo de hasta 255 caracteres. El documento queda rechazado para todos: recibes documento.rechazado con el motivo, si lo dio (si no, llega null), al emisor le llega un correo y a los firmantes que faltaban, un aviso por su canal (nada con enlace). Quien ya firmó no puede rechazar.
Su identidad queda en revisiónUna revisión humana no le gasta intentos. Cuando se aprueba recibes firmante.identidad_aprobada, y el emisor un correo, salvo que el firmante ya haya firmado. Si la revisión era la de una firma, la firma queda registrada sola y al firmante no se le avisa; sólo se le avisa cuando era la del acceso a un documento confidencial. Si su canal es enlace, el aviso trae su url_firma para que se la hagas llegar.
No alcanza a firmarVencido el plazo, el documento pasa a expirado y recibes documento.expirado. No se reactiva.
No se puede sellarEl cierre se reintenta a los 15 s, 30 s, 1 min y 2 min, y después cada 3 min, sin límite. Si aun así no se puede emitir, el documento queda no_emitido, la validación muestra «No se pudo emitir» y recibes documento.no_emitido. Un documento que no pudo sellarse nunca se entrega como firmado.
Cómo se verifica la identidad y qué recibes de esa verificación: identidad verificada.
09
Reenviar, cancelar, consultar y descargar
ValidaFirma no manda recordatorios por su cuenta: la invitación sale una vez, al crear el documento, y volver a mandarla lo pides tú.
En la cuenta corporativa, quién puede reenviar o cancelar depende de su rol y de la carpeta del documento: un administrador, todo; un revisor, nunca; una llave con alcance de cuenta, en cualquier carpeta. En una carpeta personal, sólo quien creó el documento. En una carpeta compartida, con nivel lecturanada, con escritura sólo lo suyo, y con lectura_escritura ogestion, todo. Si no ve el documento, responde 404; si lo ve sin permiso para operarlo, 403.
Reenviar la invitación
Manda la invitación otra vez a cada firmante pendiente, por su canal. A un mismo firmante, como máximo una vez cada 24 horas, contadas desde el último envío, incluida la invitación inicial. En un reenvío general, la respuesta trae enviados, omitidos y, sólo si los hubo, errores. Cada omitido trae su motivo (ventana, bloqueado, enlace o firmado), y sólo los de motivo ventana traen desde cuándo se podrá (disponible_desde). Para reenviar a uno puntual, la misma ruta lleva el cuerpo {"firmante_ids": [id]}. Si ese firmante está en su ventana, responde 400 REENVIO_EN_VENTANA con disponible_desde; si está bloqueado, 400 FIRMANTE_BLOQUEADO con bloqueado_hasta; si ya firmó, 400 YA_FIRMADO, y si no es del documento, 400 FIRMANTE_NO_ENCONTRADO. No se reenvía a los de canal enlace: pedido uno puntual, responde 200 con él en omitidos.
POST …/reenviar-notificaciones
curl -X POST https://api.validafirma.cl/api/fes/documentos/9f1c2a7e-4b3d-4e6f-8a21-5c0d7e9b1f44/reenviar-notificaciones \ -H "X-API-Key: $VALIDAFIRMA_API_KEY"
Cancelar
Sólo un documento pendiente. Los firmantes que faltaban, también los bloqueados, quedan cancelados y reciben el aviso de anulación por su canal, salvo los de enlace. Recibes documento.cancelado. Si ya firmaron todos y el documento se está preparando, responde 400 DOCUMENTO_EN_PREPARACION.
El documento está pendiente, firmado, rechazado, cancelado, expirado o no_emitido. Cada firmante trae el suyo, y bloqueado es un estado del firmante, no del documento: no es definitivo, y un bloqueo vencido con el documento vigente se informa como pendiente.
El documento firmado y sellado, cuando firmaron todos. Es el mismo archivo que descargan los firmantes desde su enlace: el PDF nunca viaja adjunto, ni en los mensajes ni en el webhook.
Un documento que ya terminó no cambia: firmar, rechazar, reenviar o cancelar responde 400 con el motivo,DOCUMENTO_PROCESADO si está firmado, DOCUMENTO_RECHAZADO,DOCUMENTO_CANCELADO, DOCUMENTO_VENCIDO oDOCUMENTO_NO_EMITIDO. Mientras se sella respondeDOCUMENTO_EN_PREPARACION, y a un firmante que ya firmó,YA_FIRMADO.
10
Errores de validación
Toda regla de esta página que falla responde 400 VALIDACION_ERROR, condetalles que nombran al firmante y el dato. El documento no se crea.
Un canal sin su dato obligatorio.
Un RUT inválido, de persona jurídica o repetido.
Un teléfono que no es +56 seguido de 8 o 9 dígitos.
Un validar_contacto que el canal no admite, o en un firmante por poder.
Un dias_expiracion fuera de 1 a 30.
Si ya integraste antes: antes eran obligatorios email, nombre,rut y telefono. Y estas reglas rechazan llamados que antes funcionaban: el RUT de persona jurídica, el RUT repetido, una webhook_url que no cumple (un http:// que antes andaba), 409 PODER_DE_OTRO_MODO, en la cuenta corporativa CARPETA_OBLIGATORIA,CUENTA_SIN_CARPETAS_ACTIVAS y CARPETA_POR_DEFECTO_ARCHIVADA, y en el modo de prueba MODO_PRUEBA_TOPE_DIARIO.
{ "error": "Datos de entrada inválidos", "codigo": "VALIDACION_ERROR", "detalles": [ "firmantes[1].telefono: obligatorio", "firmantes[2].rut: RUT de persona jurídica no admitido" ]}
Los errores al crear
Las respuestas de error de POST /api/fes/documentos
Respuesta
Cuándo
400 VALIDACION_ERROR
Una regla de los campos, con detalles que nombran al firmante y el dato.
400 ARCHIVO_REQUERIDO
Falta el PDF en documento.
400 FORMATO_INVALIDO
firmantes no es un JSON bien formado.
400 WEBHOOK_URL_NO_PERMITIDA
La webhook_url no es https en el puerto 443 hacia una dirección pública. Trae su motivo.
402 INSUFFICIENT_BALANCE
Cuenta personal sin saldo.
409 PODER_DE_OTRO_MODO
Un poder de prueba en un documento real, o uno real en uno de prueba.
409 MODO_PRUEBA_TOPE_DIARIO
Se alcanzó el tope diario del modo de prueba.
409 PROTECCION_DEL_PLAN · 409 TOPE_ALCANZADO
Cuenta corporativa: la protección del plan congeló la creación, o se alcanzó el tope de seguridad.
503 TOPES_NO_DISPONIBLES
Los topes no están disponibles en ese momento.
Errores de carpeta
Cuenta corporativa: CARPETA_NO_ENCONTRADA, CARPETA_ARCHIVADA, 400 CARPETA_OBLIGATORIA, 409 CUENTA_SIN_CARPETAS_ACTIVAS y 409 CARPETA_POR_DEFECTO_ARCHIVADA.
Preguntas sobre firmantes
Lo que se pregunta al integrar
¿Puedo hacer que firmen en un orden?
No. Todos los firmantes reciben la invitación al mismo tiempo y cada uno firma cuando puede. El orden de la lista sólo decide cómo aparecen en las respuestas. Si tu proceso necesita que alguien firme después de otro, crea el segundo documento cuando recibas el aviso del primero.
¿ValidaFirma le recuerda al firmante que le falta firmar?
No. No hay recordatorios automáticos: la invitación sale una vez al crear el documento, y volver a mandarla es un reenvío que pides tú, como máximo una vez cada 24 horas por firmante.
¿Tengo que mandar el nombre del firmante?
No. El nombre es opcional y sirve de referencia: si lo mandas, la invitación lo usa para saludar; si no, el correo saluda «Estimado/a» seguido de su RUT y el WhatsApp le dice «firmante». En la evidencia —el PDF, la validación y el webhook— manda el nombre de la cédula.
¿Puede firmar una empresa?
Firma siempre una persona natural, con su RUT. Un RUT de persona jurídica se rechaza. Si alguien firma por una empresa, va el RUT de esa persona.
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.
