Gestión de PIN

Los PINs son códigos numéricos usados en POS y para ciertas operaciones sensibles. Migo los almacena de forma irreversible — ni siquiera Migo puede revelar un PIN existente; los PINs solo pueden establecerse/cambiarse, nunca leerse.

Cambiar un PIN

El endpoint de PIN acepta únicamente el nuevo valor del PIN (CardPinDto). Para operaciones sensibles, el titular primero comprueba la titularidad mediante OTP para obtener una sesión elevada y luego establece el PIN:

# 1. Solicitar un OTP
POST /users/auth/otp
{ "email": "user@example.com", "purpose": "pin_change" }

# 2. Verificar el OTP (devuelve una sesión elevada)
PUT /users/auth/otp
{ "email": "user@example.com", "otp": "987654", "purpose": "pin_change" }

# 3. Establecer el nuevo PIN
POST /cards/{cardId}/pin
Authorization: Bearer <elevated-token>
{ "pin": "5678" }

Consulta Autenticación → OTP para el flujo completo de elevación por OTP.

nota

El endpoint POST /cards/{cardId}/pin en sí acepta cualquier sesión válida y solo valida el campo pin. La elevación por OTP de arriba la aplica el flujo de autenticación de la app de wallet, no el endpoint de PIN.

Cambio de PIN por admin (escenarios de tarjeta compartida)

Cuando una tarjeta tiene múltiples usuarios (p. ej. una tarjeta familiar compartida), un admin puede establecer un PIN por usuario. El cuerpo es el mismo { pin }:

POST /cards/{cardId}/users/{authUserId}/pin
Authorization: Bearer <admin-token>
{ "pin": "4321" }

El PIN del admin sobrescribe el PIN previo solo para ese usuario. Otros usuarios de la misma tarjeta conservan su propio PIN.

Restablecimiento de PIN (PIN olvidado)

Trata el PIN olvidado como un flujo de cambio de PIN que comienza con OTP:

1. El titular confirma su identidad mediante OTP (POST y luego PUT /users/auth/otp).
2. POST /cards/{cardId}/pin establece un nuevo PIN con { pin }.

No existe un endpoint para revelar un PIN existente — por diseño.

Errores

Las operaciones de PIN devuelven errores del rango de Tarjetas (7200–7299). Por ejemplo:

Código	Nombre	Significado
7205	INCORRECT_PIN	PIN incorrecto ingresado
7210	CARD_NOT_UPDATED	No se pudo actualizar la tarjeta (incl. PIN)
7213	INVALID_STATUS_CARD	La tarjeta está en un estado que no permite la operación

Consulta el Catálogo de Errores completo para la lista total.