Autenticar con PIN en el TPV
Identifica al empleado que va a operar el TPV del terminal actual mediante un PIN de cuatro dígitos. La acción selecciona al staff en la pantalla TPV, por ejemplo Marta Ruiz, sin crear una sesión persistente de empleado, abrir servicio ni modificar tickets.
En este artículo
Usa esta guía cuando el TPV de Marea Gran Via esté configurado para pedir PIN antes de operar. La pantalla muestra un modal con teclado numérico, PIN enmascarado y contador de dígitos; no lista empleados ni expone el código real.
La validación se hace contra una credencial TPV activa de tipo `pin` de la misma ubicación. Cuando la ruta incluye `terminalId=${TPV_TERMINAL_ID}`, la app envía `terminal_id` para respetar credenciales limitadas a terminales concretos.
Antes de empezar
- Sesión iniciada con Grupo Marea Demo y la ubicación Marea Gran Via seleccionadas.
- TPV abierto con `antylogic://${ORG_ID}/${LOCATION_ID}/tpv?tab=floor&terminalId=${TPV_TERMINAL_ID}` para resolver el terminal actual.
- El modo efectivo de acceso del terminal es `pin`, ya venga de `tpv_settings.employee_access_mode` o del override del terminal.
- Hay una `service_session` activa; si no la hay, la pantalla prioriza abrir servicio y no mantiene el modal de PIN.
- Existe una `staff_tpv_credential` activa de tipo `pin` para Marta Ruiz u otro empleado de Marea Gran Via, válida para el terminal actual o sin restricción de terminal.
- El usuario puede validar credenciales TPV con `tpv:card-auth` o `tpv:use`; para operar el TPV completo se requiere `tpv:use`.
Instrucciones
- 1.
Abrir el TPV del terminal
Entra en el TPV de Marea Gran Via usando la ruta con `terminalId=${TPV_TERMINAL_ID}`. Así el frontend puede enviar el `terminal_id` al validar el PIN y aplicar las restricciones del terminal actual.
- 2.
Esperar el modal de PIN
Con servicio activo, modo `pin` y sin empleado seleccionado, la pantalla abre `Introducir PIN`. El modal muestra el PIN enmascarado, el contador `0 / 4 digitos`, teclado numérico y las acciones `Limpiar`, `Borrar` y `Confirmar`.
- 3.
Introducir los cuatro dígitos
El empleado pulsa los dígitos en el teclado visual. La UI solo añade números, no supera cuatro dígitos y mantiene el PIN real oculto; `Confirmar` no se activa hasta completar los cuatro dígitos y tener permiso para validar.
- 4.
Confirmar la identificación
Al pulsar `Confirmar`, la app llama a `POST /api/app/{orgId}/{locationId}/tpv-auth/pin` con `{ "credential_code": string, "terminal_id"?: string }`. El backend busca una credencial `pin` activa de la ubicación y, si tiene terminales permitidos, solo la acepta para el terminal enviado.
- 5.
Comprobar el operador activo
Si el PIN es correcto, el modal se cierra y la cabecera del TPV muestra el empleado resuelto, por ejemplo Marta Ruiz. La selección queda en el estado local de `LocationTPV` para las acciones posteriores que necesiten operador.
- 6.
Resolver incidencias habituales
Si el modal no aparece o el PIN falla, revisa que haya servicio activo, que el terminal esté en modo `pin`, que la credencial esté activa para Marea Gran Via y que no esté limitada a otro terminal. Un PIN incorrecto o no autorizado se muestra como `PIN incorrecto`.
Validaciones y límites
- El flujo solo corresponde al modo efectivo `pin`; si el modo es `selector`, `card` o `disabled`, esta acción no se muestra.
- `Confirmar` permanece deshabilitado hasta que `pinCode.trim().length === 4` y el usuario pueda validar credenciales TPV.
- Mientras la mutación está pendiente, los dígitos, `Limpiar`, `Borrar` y `Confirmar` quedan bloqueados o ignoran pulsaciones.
- No existe `POST /api/app/{orgId}/{locationId}/tpv-auth/selector`; el selector de empleado es local de la pantalla.
- El backend acepta `pin` o `card` bajo `tpv-auth`, exige método `POST`, JSON válido y `credential_code`; `terminal_id` es opcional.
- El endpoint recorta el código, exige ubicación en contexto y credencial activa de tipo `pin`; los fallos se resuelven como no encontrado y la UI cae a `PIN incorrecto`.
- Las credenciales secretas se verifican contra hashes PBKDF2 o filas legacy mediante comparación constante; el PIN no se compara directamente en SQL ni se serializa en la respuesta.
- Si el cliente omite `terminal_id`, el backend no aplica restricción por terminal a la búsqueda de credenciales; por eso la documentación y capturas deben usar la ruta con `terminalId=${TPV_TERMINAL_ID}`.
- No se encontró límite de intentos fallidos, bloqueo temporal ni auditoría específica de PIN incorrecto en la evidencia revisada.
Resultado esperado
El TPV queda con Marta Ruiz u otro staff válido como operador activo en la pantalla. La acción solo identifica al empleado: no inicia sesión persistente, no abre caja, no abre servicio y no crea ni modifica tickets por sí misma.