Ir al contenido

Verificación de identidad con PINRUT

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_methodLa persona autoriza conCuándo usarla
pinSu 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ónOperaciones frecuentes en que el PIN basta
faceUna prueba de vida contra el reconocimiento facial de su identidad acreditada. El PIN no intervieneOperaciones 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.

  • 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-rut muestra 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 panel abre 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 llevar callback_url, o responde 422.
  • 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.
  1. 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 --json

    Resultado 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 400 con code: "OPERACION_NO_DISPONIBLE_EN_PRUEBA". Eso es lo esperado, no un error tuyo. Los eventos pin.transaction.* tampoco se pueden disparar con redcumbre eventos disparar.

  2. 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: rut es el de la persona que va a autorizar (nunca el de una empresa; con o sin puntos). authentication_method es obligatorio y no tiene valor por defecto. operation_type va en snake_case (hasta 50 caracteres) y operation_label es 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. state vuelve idéntico en la redirección y en el webhook, y sirve para correlacionar con tu sesión. Si omites redirect_uri y la integración no tiene una por defecto, responde 422. operation_reference, opcional, es una referencia tuya con el formato sha256:<64 caracteres hexadecimales en minúscula> que no se muestra a la persona y se incluye en el comprobante.

  3. 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 --json

    Resultado esperado: 201 con data.transaction_id, data.authorize_url (dirección absoluta en el dominio de PINRUT), data.expires_at y data.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.

  4. 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 responde 503 y no entrega ninguna dirección: reintenta más tarde, no hay dirección de respaldo. Guarda el transaction_id.

  5. Recibe el resultado. Los eventos de PINRUT llegan al callback_url de 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 (con failure_reason), pin.transaction.expired (con expiration_reason, not_started si la persona no empezó y not_completed si empezó y no terminó) y pin.transaction.cancelled. El comprobante receipt viaja sólo en authorized.

  6. No confíes sólo en la redirección ni en el webhook: verifica el estado. La persona vuelve a tu redirect_uri con transaction_id, status y state en la dirección, y eso lo controla su navegador. Antes de actuar, consulta:

    Ventana de terminal
    redcumbre api obtenerResultadoTransaccionPinrut --produccion --param txId=<transaction_id> --json

    Resultado esperado: 200 con data.status en pending, authorized, failed, expired o cancelled. Sólo authorized autoriza tu operación. Con failed o expired lee failure_reason y expiration_reason; con authorized, guarda receipt junto a tu operación: es un comprobante firmado (JWS) que se verifica sin depender de REDCUMBRE con las claves públicas de https://api.redcumbre.cl/.well-known/kyc-jwks.json (el kid del encabezado del JWS dice cuál usar).

  7. 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> --json

    Resultado esperado: 201 con data.success: true. Sólo se cancelan las transacciones pending; otra responde 409. Hay un tope de 3 transacciones pendientes por RUT e integración: quien regenera enlaces sin cancelar queda bloqueado por días.

  • 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 obtenerResultadoTransaccionPinrut responde status: "authorized", trae receipt y tu receptor recibió pin.transaction.authorized con firma válida y el mismo transaction_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.
Si vesSignificaQué haces
400 con OPERACION_NO_DISPONIBLE_EN_PRUEBAUsaste una llave de prueba: PINRUT no se simulaUsa la llave de producción con la persona que se verifica
400 con rut_de_persona_juridicaEl 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_urlFalta el método o no es pin ni face, o la URL no está en la lista de la integraciónCorrige el cuerpo o pídele a la persona administradora que agregue la URL
400 con too_many_pendingYa hay 3 transacciones pendientes para ese RUT e integraciónCancela las anteriores con cancelarTransaccionPinrut
402 con METRIC_NOT_IN_PLANEl plan de la empresa no incluye la métrica de PINRUTEs del plan: lo cambia quien administra la empresa. No reintentes
403 por servicio no habilitadoLa empresa no tiene PINRUT activo, o el rol no alcanzaAvisa a la persona a cargo; no hay nada que hacer en el código
404 al crearLa integración no existe o está inactivaRevisa el slug en el panel
404 al consultarLa 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 cancelarLa transacción ya no está pendingConsulta su estado final
422 con no_redirect_uri o callback_url_requiredNo hay redirect_uri ni una por defecto, o la integración recibe el nombre y no enviaste callback_urlEnvía el campo que falta
423 con pin_blockedSólo con pin: el titular o REDCUMBRE bloqueó el PIN de ese RUTOfrece face, que no usa el PIN. El desbloqueo lo hace un administrador de REDCUMBRE
503 al crearEl dominio de PINRUT no está disponible: no se creó nada ni hay direcciónReintenta 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_mismatchLa cédula que presentó la persona es de otro RUTNo hay reintento en esa transacción: abre una nueva, con el RUT corregido si lo habías declarado mal
failed con face_not_verifiedLa prueba de vida agotó sus intentosNueva transacción
Transacción con motivo max_attempts_reached o rate_limit_exceededYa 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
expiredLa 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

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.

  1. Llave de producción. redcumbre pasar-a-produccion --servicios pin-rut revisa 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 en keys/redcumbre-produccion.json.
  2. 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.
  3. 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.
  4. Webhooks de producción. Endpoint y secreto de firma de producción; tu receptor tiene que deduplicar.
  5. Cierre. Termina con la primera transacción de producción hecha por la persona dueña del proyecto y confírmala con obtenerResultadoTransaccionPinrut antes de abrirla a tus usuarios.

Más sobre qué cambia entre modos: Modo de prueba y producción.