Verificación de identidad con PINRUT
Qué resuelve
Sección titulada «Qué resuelve»Comprobar que una persona natural autorizó una operación concreta de tu sistema (firmar un contrato, aprobar un pago, confirmar un trámite): tu sistema crea una transacción, lleva a la persona a una pantalla de PINRUT donde se autentica, y recibes el resultado con un comprobante firmado que puedes guardar como prueba.
La persona se autentica de una de dos formas, que eliges tú al crear la transacción:
authentication_method | La persona autoriza con | Cuándo usarla |
|---|---|---|
pin | Su PIN de 6 dígitos. Si aún no tiene PIN, lo crea después de autenticarse con su cara, y crearlo autoriza la operación | Operaciones frecuentes en que el PIN basta |
face | Una prueba de vida contra el reconocimiento facial de su identidad acreditada. El PIN no interviene | Operaciones en que necesitas la presencia de la persona, no sólo un secreto |
En las dos, si la persona no tiene su identidad acreditada, la plataforma la guía primero a acreditarla (cédula por ambos lados y prueba de vida) y después sigue con lo que pediste. Tú no haces nada distinto: es la misma dirección.
Lo que esta ficha no promete. PINRUT es un servicio de REDCUMBRE que se activa por empresa: esta ficha vale sólo si la empresa ya lo tiene activo, y no hay forma de activarlo desde el CLI ni desde el API. Tampoco se incrusta en tu sitio: el flujo es siempre una redirección a la dirección que entrega la plataforma. Y es sólo para personas naturales: con el RUT de una empresa la creación responde 400.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- Que la empresa tenga PINRUT activo. Sin eso, crear una transacción responde
403. Si falta, es una gestión de la empresa con REDCUMBRE: avísale a la persona a cargo y espera; no hay nada que hacer en el código.redcumbre pasar-a-produccion --servicios pin-rutmuestra si falta y dónde configurarlo. - Una integración PINRUT configurada en el panel de la empresa (Configuración, PINRUT, Integraciones). Eso no se puede hacer por API ni por CLI y lo hace una persona administradora:
redcumbre panelabre el panel. Pídele estos datos y no sigas sin ellos:- el slug de la integración (identificador que no cambia; va en cada transacción como
integration_slug); - al menos una URL HTTPS de redirección (adonde vuelve el navegador de la persona) y una URL HTTPS de callback (adonde llegan los webhooks). Todas tienen que ser HTTPS y estar en la lista de la integración; una URL que no esté, la creación la rechaza con
400; - si la integración debe recibir el nombre completo leído de la cédula (
sharedPersonalData: ["full_name"], apagado por defecto), ten en cuenta que entonces cada transacción debe llevarcallback_url, o responde422.
- el slug de la integración (identificador que no cambia; va en cada transacción como
- Una llave de producción, porque en el modo de prueba este flujo no existe (ver el primer paso). Qué cambia entre los modos: Modo de prueba y producción.
- Un receptor de webhooks que valide la firma: Webhooks. Forma de los errores y límites: Reglas comunes.
- Una persona con su celular para completar la primera transacción. Ningún agente puede autorizar por ella.
-
Confirma que el modo de prueba no ejercita este flujo. PINRUT alcanza la verificación de identidad de una persona y su PIN, así que no se simula: con una llave de prueba, crear una transacción se rechaza y no crea nada. Para dejar el cuerpo armado, muéstralo sin enviarlo:
Ventana de terminal redcumbre api crearTransaccionPinrut --ensayo --cuerpo @pin.json --jsonResultado esperado: el CLI imprime la petición que haría y sale con 0 sin llamar al API. Si la enviaras con la llave de prueba, la respuesta sería
400concode: "OPERACION_NO_DISPONIBLE_EN_PRUEBA". Eso es lo esperado, no un error tuyo. Los eventospin.transaction.*tampoco se pueden disparar conredcumbre eventos disparar. -
Arma el cuerpo de la transacción. Guárdalo como
pin.json(cambia el slug de la integración, las URL y el RUT):{"integration_slug": "mi_app_prod","rut": "12345678-5","authentication_method": "face","operation_type": "firma_contrato","operation_label": "Firmar Contrato N° 2026-042","operation_detail": "Contrato por 12 meses","redirect_uri": "https://miapp.cl/pin-callback","callback_url": "https://miapp.cl/webhooks/pin","state": "sesion-abc-123"}Qué es cada campo:
rutes el de la persona que va a autorizar (nunca el de una empresa; con o sin puntos).authentication_methodes obligatorio y no tiene valor por defecto.operation_typeva ensnake_case(hasta 50 caracteres) yoperation_labeles lo que la persona lee en pantalla (hasta 200).operation_detail(hasta 500) queda como evidencia: no pongas datos de otras personas ni datos sensibles.statevuelve idéntico en la redirección y en el webhook, y sirve para correlacionar con tu sesión. Si omitesredirect_uriy la integración no tiene una por defecto, responde422.operation_reference, opcional, es una referencia tuya con el formatosha256:<64 caracteres hexadecimales en minúscula>que no se muestra a la persona y se incluye en el comprobante. -
Crea la transacción (producción, con una persona esperando). Comando:
Ventana de terminal redcumbre api crearTransaccionPinrut --produccion --confirmar <identificador-de-la-empresa> --cuerpo @pin.json --jsonResultado esperado:
201condata.transaction_id,data.authorize_url(dirección absoluta en el dominio de PINRUT),data.expires_atydata.operation_hash. La respuesta es la misma para toda persona: no dice si tiene PIN ni si está acreditada. En producción, el cargo se registra al completarse la verificación, no al crear; su precio depende de tu plan:redcumbre tarifas crearTransaccionPinrut --produccion. -
Lleva a la persona a
authorize_url. Redirige su navegador a esa dirección tal como vino: no le agregues nada delante, no extraigas el identificador del enlace y no armes tú otra dirección. Si PINRUT no tiene su dominio disponible, la creación responde503y no entrega ninguna dirección: reintenta más tarde, no hay dirección de respaldo. Guarda eltransaction_id. -
Recibe el resultado. Los eventos de PINRUT llegan al
callback_urlde la transacción (si no lo enviaste, a la URL por defecto de la empresa). Cada uno trae la firma de Webhooks. El de éxito se ve así (resumido):{"event": "pin.transaction.authorized","timestamp": "2026-05-09T23:38:01.577Z","data": {"transaction_id": "cedd740a-e5a3-43a2-9896-5ac45dfdb4dc","status": "authorized","authentication_method": "face","operation_type": "firma_contrato","authorized_at": "2026-05-09T23:38:01.538Z","state": "sesion-abc-123","receipt": "eyJhbGciOi..."}}Los otros tres eventos son
pin.transaction.failed(confailure_reason),pin.transaction.expired(conexpiration_reason,not_startedsi la persona no empezó ynot_completedsi empezó y no terminó) ypin.transaction.cancelled. El comprobantereceiptviaja sólo enauthorized. -
No confíes sólo en la redirección ni en el webhook: verifica el estado. La persona vuelve a tu
redirect_uricontransaction_id,statusystateen la dirección, y eso lo controla su navegador. Antes de actuar, consulta:Ventana de terminal redcumbre api obtenerResultadoTransaccionPinrut --produccion --param txId=<transaction_id> --jsonResultado esperado:
200condata.statusenpending,authorized,failed,expiredocancelled. Sóloauthorizedautoriza tu operación. Confailedoexpiredleefailure_reasonyexpiration_reason; conauthorized, guardareceiptjunto a tu operación: es un comprobante firmado (JWS) que se verifica sin depender de REDCUMBRE con las claves públicas dehttps://api.redcumbre.cl/.well-known/kyc-jwks.json(elkiddel encabezado del JWS dice cuál usar). -
Cancela una transacción pendiente si ya no corresponde. Antes de regenerar un enlace, cancela el anterior:
Ventana de terminal redcumbre api cancelarTransaccionPinrut --produccion --confirmar <identificador-de-la-empresa> --param txId=<transaction_id> --jsonResultado esperado:
201condata.success: true. Sólo se cancelan las transaccionespending; otra responde409. Hay un tope de 3 transacciones pendientes por RUT e integración: quien regenera enlaces sin cancelar queda bloqueado por días.
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- No hay verificación en el modo de prueba, así que «funcionó» sólo se puede afirmar con una transacción de producción. No lo des por hecho con el cuerpo armado ni con el
--ensayo. - Una transacción funcionó cuando
obtenerResultadoTransaccionPinrutrespondestatus: "authorized", traereceipty tu receptor recibiópin.transaction.authorizedcon firma válida y el mismotransaction_id. - Prueba tu receptor con un webhook firmado por ti mismo (la firma se explica en Webhooks) para comprobar que valida firma, ignora repetidos y no actúa dos veces; eso no reemplaza una transacción de producción.
- Pide que la primera transacción la haga la persona dueña del proyecto con su propio RUT, y que te confirme que llegó el webhook.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
400 con OPERACION_NO_DISPONIBLE_EN_PRUEBA | Usaste una llave de prueba: PINRUT no se simula | Usa la llave de producción con la persona que se verifica |
400 con rut_de_persona_juridica | El RUT es de una empresa (cuerpo desde 50.000.000) | Usa el RUT personal del titular. No se creó nada |
400 por authentication_method, redirect_uri o callback_url | Falta el método o no es pin ni face, o la URL no está en la lista de la integración | Corrige el cuerpo o pídele a la persona administradora que agregue la URL |
400 con too_many_pending | Ya hay 3 transacciones pendientes para ese RUT e integración | Cancela las anteriores con cancelarTransaccionPinrut |
402 con METRIC_NOT_IN_PLAN | El plan de la empresa no incluye la métrica de PINRUT | Es del plan: lo cambia quien administra la empresa. No reintentes |
403 por servicio no habilitado | La empresa no tiene PINRUT activo, o el rol no alcanza | Avisa a la persona a cargo; no hay nada que hacer en el código |
404 al crear | La integración no existe o está inactiva | Revisa el slug en el panel |
404 al consultar | La transacción no existe, es de otra empresa o la consultas con otra llave: una transacción que entrega datos personales sólo la ve la llave que la creó | Consulta con la misma llave |
409 al cancelar | La transacción ya no está pending | Consulta su estado final |
422 con no_redirect_uri o callback_url_required | No hay redirect_uri ni una por defecto, o la integración recibe el nombre y no enviaste callback_url | Envía el campo que falta |
423 con pin_blocked | Sólo con pin: el titular o REDCUMBRE bloqueó el PIN de ese RUT | Ofrece face, que no usa el PIN. El desbloqueo lo hace un administrador de REDCUMBRE |
503 al crear | El dominio de PINRUT no está disponible: no se creó nada ni hay dirección | Reintenta más tarde. Si el cuerpo trae API_KEY_VERIFICATION_UNAVAILABLE, la llave no fue rechazada: reintenta tras Retry-After y no la rotes |
failed con rut_mismatch | La cédula que presentó la persona es de otro RUT | No hay reintento en esa transacción: abre una nueva, con el RUT corregido si lo habías declarado mal |
failed con face_not_verified | La prueba de vida agotó sus intentos | Nueva transacción |
Transacción con motivo max_attempts_reached o rate_limit_exceeded | Ya no se producen: sólo aparecen en transacciones antiguas. Un PIN incorrecto deja la transacción pending y, tras 3 fallos, se pide un código (codigo_requerido) (registro de cambios) | No esperes pin.transaction.failed por PIN incorrecto: espera expired o cancela |
expired | La persona no abrió el enlace en 7 días (not_started) o empezó y no terminó a tiempo (not_completed) | Crea una transacción nueva si la operación sigue vigente. Los plazos cortos corren desde que se abre el enlace: 5 minutos para el PIN y 30 para la prueba de vida |
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»En PINRUT no hay un paso intermedio: la primera transacción ya es producción, con una persona de verdad y su propio RUT. Lo que cuesta depende de tu plan y se registra al completarse la verificación (redcumbre tarifas crearTransaccionPinrut --produccion; el resultado informa también el cargo de acreditación de identidad y el de autenticación facial). Por eso conviene dejar listo todo lo demás antes de crearla.
- Llave de producción.
redcumbre pasar-a-produccion --servicios pin-rutrevisa que todo esté en orden, dice qué falta y dónde configurarlo, y recién entonces crea la llave de producción, que confirma una persona escribiendo el identificador de la empresa. Esa llave nunca se muestra ni se pega en el chat o el repositorio: queda enkeys/redcumbre-produccion.json. - Integración y URL de producción. El slug, la URL de redirección y la de callback tienen que ser las de tu sitio en producción, todas HTTPS, y estar en la integración.
- Datos personales. El RUT, el nombre (si la integración lo recibe) y el comprobante son datos personales: guárdalos solo si los necesitas y con la misma reserva que el resto de tus datos de clientes. El nombre completo sólo lo recibe tu integración si la persona fue informada en la pantalla de autorización, y sólo la llave que creó la transacción puede consultarlo.
- Webhooks de producción. Endpoint y secreto de firma de producción; tu receptor tiene que deduplicar.
- Cierre. Termina con la primera transacción de producción hecha por la persona dueña del proyecto y confírmala con
obtenerResultadoTransaccionPinrutantes de abrirla a tus usuarios.
Más sobre qué cambia entre modos: Modo de prueba y producción.