Saltar al contenido principal
Migo Docs

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.

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" }
]
}'
CampoTipoRequeridoNotas
firstNamestringsíNombre
lastNamestringsíApellido
addressstringsíDirección de residencia
countryOfBirthenum CountrysíCódigo ISO alpha-3 (p. ej. GTM). La entrada alpha-2 la normaliza el gateway a alpha-3
placeOfBirthstringsíTexto libre
genderenum GendersíM, F u OTHER
phoneNumberstringsíTeléfono en formato internacional
dateOfBirthstringsíYYYY-MM-DD
identificationDocumentsarraysíArray de { documentNumber, documentType } (ambos string, p. ej. documentType: "DPI")
usernamestring (email)noEmail usado como nombre de usuario
maritalStatusenum MaritalStatusnosoltero, casado, viudo, divorciado o separado
neighborhoodstringnoColonia o distrito
termsAndConditionsAcceptedbooleannoSi se aceptaron los términos y condiciones
additionalDataobjectnoMetadata 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)TipoRequeridoNotas
documentNumberstringsíNúmero del documento, de 1 a 50 caracteres
documentTypeenum DocumentTypenoDPI (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​

HTTPCódigoCuándoQué hacer
4007000Falta documentNumber o documentType no es válidoCorrige los parámetros
4017606Token ausente o inválidoObtén un token nuevo
4037615La aplicación no tiene el permiso findByDocumentSolicítalo a Migo
4047100Ningún titular de tu aplicación tiene ese documentoRegistra al titular con POST /users
4097186Más de un titular de tu aplicación tiene ese documentoContacta a soporte; no se elige uno de los dos
5007106Error al buscarReintenta; 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)TipoNotas
firstNamestringDe 1 a 100 caracteres
lastNamestringDe 1 a 100 caracteres
birthdatestring (fecha ISO 8601)No puede ser una fecha futura
maritalStatusstringsingle, married, divorced, widowed o separated; también en español (soltero/a, casado/a, divorciado/a, viudo/a, separado/a)
genderenumF, M u OTHER
addressstringDe 1 a 255 caracteres
neighborhoodstringDe 1 a 100 caracteres
placeBirthstringDe 1 a 100 caracteres
phoneNumberstringSolo dígitos, de 7 a 15, sin + ni espacios. Requiere phoneVerification. Ver Cambiar el teléfono
phoneVerificationobjetoObligatorio 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​

HTTPCódigoCuándoQué hacer
4007000No 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 titularCorrige el body; para el teléfono, vuelve a verificar el número
4007127El userId es una cuenta administrativa, que no tiene datos personalesUsa el userId del titular
4017602 / 7606Token ausente o inválidoObtén un token nuevo
4037615La aplicación no tiene el permiso updateUserByIntegratorSolicítalo a Migo
4047100El userId no existe o no es de un titular de tu aplicaciónVerifica el userId con Buscar un titular por documento
4097189Se envió phoneNumber y el titular también tiene cuenta en otra aplicación de MigoEl teléfono no se puede cambiar por esta ruta; el titular debe contactar a soporte
5007169Error al guardarReintenta; si persiste, contacta a soporte

Estados de la cuenta​

Los valores de auth_user.status son:

EstadoSignificado
PendingCuenta creada, aún no activada
ActiveOnboarding completo
InactiveDesactivada
BlockedDeshabilitada (fraude, problema de KYC, solicitud del cliente)
PasswordResetRequiredDebe 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": [] }'

Relacionado​