Gestión del Titular

Un titular es un usuario dueño de una tarjeta de Migo. Esta página es la referencia canónica para registrar y gestionar titulares en el Wallet Gateway. Está organizada en dos partes:

Registrar un titular — crear el usuario (POST /users).
Gestionar un titular — buscar, perfil, roles, estados y verificación de step-up.

Todos los endpoints requieren un JWT válido (Authorization: Bearer <token>).

Registrar un titular

POST /users registra un nuevo titular. Requiere el permiso de aplicación USER_REGISTRATION y admite dos modos, elegidos por el gateway según el cuerpo de la solicitud:

invitationCode presente → se valida como ExternalUserRegistrationDto (registro mediante un código de invitación de sucursal).
en caso contrario → se valida como CreateUserDto (registro directo con información personal).

Solo se requiere el header Authorization; x-user-token no aplica a este endpoint.

Modo 1 — Código de invitación de sucursal

curl -X POST https://api.ali.app/rest/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceId": "device-0000",
    "invitationCode": "INV-0000",
    "username": "user@example.com",
    "password": "<password>",
    "confirmPassword": "<password>",
    "termsAndConditionsAccepted": true
  }'

Campo	Tipo	Requerido	Notas
`deviceId`	string	sí	Identificador único del dispositivo que inició el registro
`invitationCode`	string	sí	Código de invitación de sucursal que habilita el registro
`username`	string (email)	sí	Email usado como nombre de usuario
`password`	string	sí	Contraseña de la cuenta (no vacía)
`confirmPassword`	string	sí	Debe coincidir con `password`
`nit`	string	no	Número de identificación tributaria (NIT)
`termsAndConditionsAccepted`	boolean	no	Si se aceptaron los términos y condiciones

Modo 2 — Registro directo

curl -X POST https://api.ali.app/rest/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Example",
    "lastName": "User",
    "address": "Example address",
    "countryOfBirth": "GTM",
    "placeOfBirth": "Example City",
    "gender": "M",
    "maritalStatus": "soltero",
    "phoneNumber": "+50200000000",
    "username": "user@example.com",
    "dateOfBirth": "1990-01-01",
    "termsAndConditionsAccepted": true,
    "identificationDocuments": [
      { "documentNumber": "XXXXXXXXXXXXX", "documentType": "DPI" }
    ]
  }'

Campo	Tipo	Requerido	Notas
`firstName`	string	sí	Nombre
`lastName`	string	sí	Apellido
`address`	string	sí	Dirección de residencia
`countryOfBirth`	enum `Country`	sí	Código ISO alpha-3 (p. ej. `GTM`). La entrada alpha-2 la normaliza el gateway a alpha-3
`placeOfBirth`	string	sí	Texto libre
`gender`	enum `Gender`	sí	`M`, `F` u `OTHER`
`phoneNumber`	string	sí	Teléfono en formato internacional
`dateOfBirth`	string	sí	`YYYY-MM-DD`
`identificationDocuments`	array	sí	Array de `{ documentNumber, documentType }` (ambos string, p. ej. `documentType: "DPI"`)
`username`	string (email)	no	Email usado como nombre de usuario
`maritalStatus`	enum `MaritalStatus`	no	`soltero`, `casado`, `viudo`, `divorciado` o `separado`
`neighborhood`	string	no	Colonia o distrito
`termsAndConditionsAccepted`	boolean	no	Si se aceptaron los términos y condiciones
`additionalData`	object	no	Metadata adicional del usuario

No existe un email / documentId / birthDate de nivel superior en ningún modo — el email es username y los documentos de identidad viven en identificationDocuments.

Respuesta

Ambos modos devuelven el envelope de respuesta estándar; en éxito, el usuario creado se devuelve bajo data:

{ "success": true, "data": { } }

En error, success es false y errors lleva el detalle. Los campos del envelope son success (boolean), message opcional, data opcional y errors opcional (array de { message, code }).

Generar un código de invitación (para el Modo 1)

El código de invitación de sucursal que consume el Modo 1 se crea con POST /users/invitation-code (InvitationCodeGenerateDto):

curl -X POST https://api.ali.app/rest/users/invitation-code \
  -H "Authorization: Bearer <token>" \
  -H "x-user-token: <user-token>" \
  -H "Content-Type: application/json" \
  -d '{ "branchId": 24, "role": "owner" }'

role es uno de owner, admin, cashier. El flujo completo de onboarding se describe en Tap to Phone → Instalación del SDK y Pagos con Terminal.

Gestionar un titular

Buscar un titular

GET /users recupera un único usuario filtrado por id (numérico) o username (email) — al menos uno es requerido:

curl "https://api.ali.app/rest/users?username=user@example.com" \
  -H "Authorization: Bearer <token>" \
  -H "x-application-id: YOUR_APP_ID"

Estados de la cuenta

Los valores de auth_user.status son:

Estado	Significado
`Pending`	Cuenta creada, aún no activada
`Active`	Onboarding completo
`Inactive`	Desactivada
`Blocked`	Deshabilitada (fraude, problema de KYC, solicitud del cliente)
`PasswordResetRequired`	Debe restablecer la contraseña antes de continuar

No existe un PATCH de actualización de perfil; los cambios de estado de la tarjeta van por los endpoints de bloqueo/desbloqueo (consulta Ciclo de vida de la tarjeta).

Verificar una contraseña

POST /users/{userId}/auth valida una contraseña contra las credenciales del usuario — se usa para confirmación step-up antes de acciones sensibles (VerifyPasswordDto):

curl -X POST "https://api.ali.app/rest/users/{userId}/auth" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "password": "<password>" }'

Imagen de perfil

PUT /users/{userId}/profile-image acepta una carga multipart/form-data con el campo profileImage (máx. 5 MB; png, jpeg, jpg):

curl -X PUT "https://api.ali.app/rest/users/{userId}/profile-image" \
  -H "Authorization: Bearer <token>" \
  -F "profileImage=@avatar.jpg"

Tokens de notificaciones push

Registra y elimina el token FCM (Firebase Cloud Messaging) del titular para que la plataforma pueda entregar notificaciones push:

# Registrar
curl -X POST "https://api.ali.app/rest/users/fcm-tokens" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "token": "fcm-token-abc123xyz" }'

# Eliminar (al cerrar sesión / rotar token) — devuelve 204 No Content
curl -X DELETE "https://api.ali.app/rest/users/fcm-tokens/{token}" \
  -H "Authorization: Bearer <token>"

Roles

Lista los roles disponibles y agrega/quita roles a un usuario:

# Listar roles
curl https://api.ali.app/rest/users/roles \
  -H "Authorization: Bearer <token>"

# Agregar / quitar roles a un usuario
curl -X PATCH https://api.ali.app/rest/users/{id}/roles \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "addRoles": ["SHOP_ADMIN"], "removeRoles": [] }'

Registrar un titular​

Modo 1 — Código de invitación de sucursal​

Modo 2 — Registro directo​

Respuesta​

Generar un código de invitación (para el Modo 1)​

Gestionar un titular​

Buscar un titular​

Estados de la cuenta​

Verificar una contraseña​

Imagen de perfil​

Tokens de notificaciones push​

Roles​

Relacionado​