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.
- Registrar un titular — crear el usuario (
POST /users). - Buscar un titular por documento — recuperar su cuenta y su userId a partir del DPI (GET /users/by-document).
- Actualizar los datos de un titular — mantener sincronizados sus datos personales (PATCH /users/{userId}/personal-data).
- 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 con su información personal. Requiere el permiso de aplicación USER_REGISTRATION.
Solo se requiere el header Authorization.
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
Devuelve 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 }).
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"
Buscar un titular por documento
GET /users/by-document devuelve la cuenta que un titular ya tiene registrada en tu aplicación, a partir de su documento de identidad. La respuesta incluye el userId que aceptan las rutas /users/{userId}/... (tarjetas, perfil). Úsalo para asociar de tu lado a un usuario que ya existe —por ejemplo, antes de asignarle una tarjeta— en lugar de registrarlo de nuevo.
Requiere el permiso de aplicación findByDocument (recurso users). Solo se envía el header Authorization; no hace falta token de usuario.
curl "https://api.ali.app/rest/users/by-document?documentNumber=XXXXXXXXXXXXX&documentType=DPI" \
-H "Authorization: Bearer <token>"
| Parámetro (query) | Tipo | Requerido | Notas |
|---|---|---|---|
| documentNumber | string | sí | Número del documento, de 1 a 50 caracteres |
| documentType | enum DocumentType | no | DPI (por defecto), NIT, PASSPORT, LEGAL_ID, PERSONAL_ID o RESIDENCE_ID |
El número de documento viaja en la URL: evita guardar la URL completa en los logs de tu lado.
Respuesta
{
"success": true,
"message": "User found",
"data": {
"userId": 123,
"firstName": "Example",
"lastName": "User",
"address": "Example address",
"countryOfBirth": "GTM",
"placeOfBirth": "Example City",
"gender": "M",
"maritalStatus": "soltero",
"neighborhood": "Example neighborhood",
"phoneNumber": "+50200000000",
"username": "user@example.com",
"dateOfBirth": "1990-01-01",
"identificationDocuments": [
{ "documentNumber": "XXXXXXXXXXXXX", "documentType": "DPI" }
],
"termsAndConditionsAccepted": true
}
}
Los campos son los mismos que envías al registrar un titular, más userId:
- userId es el identificador que reciben las rutas /users/{userId}/....
- countryOfBirth se devuelve en ISO alpha-3 y maritalStatus en español, igual que al registrar.
- Los campos opcionales que el titular no tiene vienen en null.
- No se devuelve additionalData.
Solo titulares de tu aplicación
La búsqueda se limita a la aplicación del token. Un documento registrado solo en otra aplicación responde 404, igual que uno que no existe. Si la query incluye un merchant, se ignora.
Errores
| HTTP | Código | Cuándo | Qué hacer |
|---|---|---|---|
| 400 | 7000 | Falta documentNumber o documentType no es válido | Corrige los parámetros |
| 401 | 7606 | Token ausente o inválido | Obtén un token nuevo |
| 403 | 7615 | La aplicación no tiene el permiso findByDocument | Solicítalo a Migo |
| 404 | 7100 | Ningún titular de tu aplicación tiene ese documento | Registra al titular con POST /users |
| 409 | 7186 | Más de un titular de tu aplicación tiene ese documento | Contacta a soporte; no se elige uno de los dos |
| 500 | 7106 | Error al buscar | Reintenta; si persiste, contacta a soporte |
Actualizar los datos de un titular
PATCH /users/{userId}/personal-data actualiza los datos personales de un titular de tu aplicación. Úsalo para mantener sincronizado a Migo cuando el titular cambia sus datos en tu plataforma. El userId es el que devuelve Buscar un titular por documento.
Requiere el permiso de aplicación updateUserByIntegrator (recurso users). Solo se envía el header Authorization; no hace falta token de usuario.
curl -X PATCH "https://api.ali.app/rest/users/123/personal-data" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "address": "Example address 2", "neighborhood": "Example neighborhood 2" }'
| Campo (body) | Tipo | Notas |
|---|---|---|
| firstName | string | De 1 a 100 caracteres |
| lastName | string | De 1 a 100 caracteres |
| birthdate | string (fecha ISO 8601) | No puede ser una fecha futura |
| maritalStatus | string | single, married, divorced, widowed o separated; también en español (soltero/a, casado/a, divorciado/a, viudo/a, separado/a) |
| gender | enum | F, M u OTHER |
| address | string | De 1 a 255 caracteres |
| neighborhood | string | De 1 a 100 caracteres |
| placeBirth | string | De 1 a 100 caracteres |
| phoneNumber | string | Solo dígitos, de 7 a 15, sin + ni espacios. Requiere phoneVerification. Ver Cambiar el teléfono |
| phoneVerification | objeto | Obligatorio con phoneNumber, y solo se acepta con él: verifiedAt (fecha y hora ISO 8601) y reference (de 1 a 100 caracteres) |
Todos los campos son opcionales, pero hay que enviar al menos uno:
- Solo se evalúan los campos que envías, y solo se guardan los que cambian.
- Un campo se puede reemplazar, pero no vaciar: null o un texto vacío se rechazan.
- Cualquier otro campo en el body rechaza toda la petición con 400, sin guardar nada. El correo y el número de documento no se actualizan por esta ruta.
- Los datos personales son de la persona, no de la aplicación: si el titular también tiene cuenta en otra aplicación de Migo, el cambio se ve ahí.
Cambiar el teléfono
El teléfono es el canal por el que el titular recibe los códigos de verificación (OTP) de Migo, por ejemplo para recuperar su contraseña. Por eso su cambio tiene reglas propias:
- Tú verificas el número nuevo. Antes de llamar a esta ruta, envía tu propio OTP al número nuevo y confirma que el titular lo recibió. El envío y su costo corren por tu cuenta. En phoneVerification indicas cuándo se verificó (verifiedAt) y el identificador de esa verificación en tu sistema (reference); Migo los guarda en su registro de auditoría.
- La verificación tiene que ser reciente: de la última hora y no en el futuro. Si no, la petición se rechaza con 400.
- Cómo reconocer una verificación vencida: el 400 llega con el código 7000 y el mensaje genérico Check the parameters provided., sin el nombre del campo. Lo mismo pasa si el número no es válido para el país del titular. Si el body tiene la forma correcta y aun así recibes ese error, revisa que verifiedAt sea de la última hora e incluya la zona horaria (por ejemplo, terminado en Z para UTC), y que el número tenga el largo correcto para el país.
- El número tiene que ser válido para el país del titular.
- Solo para titulares exclusivos de tu aplicación. Si el titular también tiene cuenta en otra aplicación de Migo, el teléfono no se cambia y la respuesta es 409: el número es de la persona, y cambiarlo afectaría los códigos que recibe en esas otras aplicaciones.
- Migo avisa al titular por correo que su número cambió, con el número nuevo enmascarado.
- El teléfono no se devuelve en la respuesta; updatedFields indica si cambió.
curl -X PATCH "https://api.ali.app/rest/users/123/personal-data" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"phoneNumber": "50212345678",
"phoneVerification": { "verifiedAt": "2026-11-03T15:04:05Z", "reference": "otp-7f3a2c" }
}'
Respuesta
{
"success": true,
"message": "User data updated successfully",
"data": {
"userId": 123,
"updatedFields": ["address", "neighborhood"],
"firstName": "Example",
"lastName": "User",
"birthdate": "1990-01-01T00:00:00.000Z",
"maritalStatus": "single",
"gender": "M",
"address": "Example address 2",
"neighborhood": "Example neighborhood 2",
"placeBirth": "Example City"
}
}
- updatedFields lista los campos que cambiaron. Si todo lo que enviaste ya estaba guardado, viene vacío y el mensaje es User data is already up to date.
- El resto de data son los valores vigentes después de la actualización; maritalStatus se devuelve en inglés (single, married, ...).
Errores
| HTTP | Código | Cuándo | Qué hacer |
|---|---|---|---|
| 400 | 7000 | No se envió ningún campo, un campo no está permitido, está vacío o no es válido, birthdate es futura, o phoneNumber llega sin una verificación reciente o no es válido para el país del titular | Corrige el body; para el teléfono, vuelve a verificar el número |
| 400 | 7127 | El userId es una cuenta administrativa, que no tiene datos personales | Usa el userId del titular |
| 401 | 7602 / 7606 | Token ausente o inválido | Obtén un token nuevo |
| 403 | 7615 | La aplicación no tiene el permiso updateUserByIntegrator | Solicítalo a Migo |
| 404 | 7100 | El userId no existe o no es de un titular de tu aplicación | Verifica el userId con Buscar un titular por documento |
| 409 | 7189 | Se envió phoneNumber y el titular también tiene cuenta en otra aplicación de Migo | El teléfono no se puede cambiar por esta ruta; el titular debe contactar a soporte |
| 500 | 7169 | Error al guardar | Reintenta; si persiste, contacta a soporte |
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:
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": [] }'