Saltar al contenido principal
Migo Docs

Onboarding self-serve con verificación de identidad

Permite que una persona se dé de alta como comercio sin código de invitación: verifica su identidad —documento, prueba de vida y comparación de rostro— y, con la identidad verificada, se crea su lead.

Hay dos maneras de verificar a la persona, y las dos terminan en el mismo alta:

ModoQuién captura las fotosCuándo usarlo
SDK de verificación de Migo (recomendado)El SDK, con su propia experiencia guiada de capturaApps móviles y web. Mejor tasa de aprobación y no tenés que construir la captura
Verificación por imágenesTu app, que sube las fotos del documento y la selfieCuando necesitás controlar toda la interfaz de captura

El lead se crea con el mismo endpoint y el mismo cuerpo que el alta clásica, POST /leads. La diferencia es un header: si la petición trae verificationId, la plataforma la trata como un alta verificada; si no lo trae, el alta clásica funciona exactamente igual que siempre.

Disponibilidad

Este flujo está deshabilitado por defecto y se habilita por comercio. Hablá con tu contacto en Migo para que lo activen y otorguen los permisos al cliente de tu integración. Sin los permisos la respuesta es 403 con el código 7615; con los permisos pero sin el flujo habilitado, 403 con 8110 u 8111.

Verificación con el SDK de Migo​

PasoEndpointQué hace
1POST /onboarding/sessionsAbre la verificación y devuelve el token de sesión para el SDK
2(en tu app)La persona completa la verificación dentro del SDK
3GET /onboarding/verifications/{verificationId}Consultás el resultado hasta que deje de estar PENDING; trae los datos y las fotos
4POST /leads con el header verificationIdCrea el lead y el negocio, y devuelve el código de invitación
5Registro y POST /users/loginEl login avisa si la identidad quedó en revisión
Disponibilidad del SDK

El modo SDK se habilita por comercio, además del flujo en sí. Tu contacto en Migo te comparte el paquete del SDK de verificación para Android, iOS y Flutter, y su versión. Si el comercio no lo tiene habilitado, el paso 1 responde 403 con 8111 y podés seguir usando la verificación por imágenes.

1. Abrir la sesión​

El comercio y el cliente salen del token. El cuerpo es opcional:

curl -X POST https://api.ali.app/rest/onboarding/sessions \
-H "Authorization: Bearer <token>"

Si tu app ya conoce el número de documento de la persona —por ejemplo, el del lead de su código de invitación—, mandalo en expectedDocumentNumber:

curl -X POST https://api.ali.app/rest/onboarding/sessions \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "expectedDocumentNumber": "1234567890101" }'

Cuando el comercio tiene activada la comparación de documento y la persona verifica un documento con otro número, la verificación termina en DECLINED con el motivo DOCUMENT_NUMBER_MISMATCH. La comparación ignora espacios, guiones y mayúsculas. Si el comercio no tiene activada la comparación, el campo se ignora.

{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "PENDING",
"sessionId": "<id-de-sesion>",
"sessionToken": "<token-de-sesion>",
"url": "<url-de-la-sesion>",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"expiresAt": "2026-10-02T18:30:00.000Z"
}
}

Guardá el verificationId: es lo que encadena el resto del alta. El sessionToken es para el SDK nativo; la url sirve para abrir la misma verificación en web.

2. Abrir el SDK​

Pasale el sessionToken al SDK de verificación. La persona fotografía su documento y se toma la selfie dentro del SDK; tu app no maneja imágenes.

Cuando el SDK se cierra, avisa si la persona terminó, canceló o hubo un error. Ese aviso no es el resultado de la verificación: sirve sólo para decidir qué mostrar. El resultado lo decide Migo del lado del servidor y lo leés en el paso 3.

3. Consultar el resultado​

curl https://api.ali.app/rest/onboarding/verifications/2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21 \
-H "Authorization: Bearer <token>"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "APPROVED",
"expiresAt": "2026-10-02T18:30:00.000Z",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true },
{ "key": "firstName", "value": "ANA MARIA", "source": "OCR", "required": true },
{ "key": "expirationDate", "value": "2031-04-12", "source": "OCR", "required": true },
{ "key": "countryOfBirth", "source": "MANUAL", "required": true },
{ "key": "partner", "value": "migo", "source": "DERIVED", "required": true }
],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }]
}
}
statusQué hacer
PENDINGEl resultado todavía no llegó. Volvé a consultar en unos segundos
OCR_APPROVEDEl documento ya se aprobó y falta el resultado del resto de la verificación. Seguí consultando como con PENDING
APPROVEDMostrá los fields para que la persona confirme sus datos y seguí al paso 4
MANUAL_REVIEWLa identidad quedó en revisión de una persona, pero el registro sigue: igual que con APPROVED, mostrá los fields y seguí al paso 4. La decisión llega después
DECLINEDLa verificación no aprobó y no se puede reintentar. Si trae reasonCode, usalo para explicarle a la persona qué pasó, y abrí una sesión nueva con el paso 1
CONSUMINGEl lead se está creando en este momento. Volvé a consultar en unos segundos
CONSUMEDLa verificación ya creó su lead; la respuesta trae el invitationCode

Los fields se leen igual que en la verificación por imágenes (ver la tabla de source más abajo). Con DECLINED, la respuesta trae reasonCode con un código del catálogo de motivos cuando el rechazo tiene uno identificado; puede no venir. Cuando una persona resuelve una revisión, la respuesta suma resolvedAt.

Fotos de la verificación​

Con APPROVED, MANUAL_REVIEW o CONSUMED la respuesta suma images: las fotos que capturó el SDK, como URLs firmadas.

{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "MANUAL_REVIEW",
"expiresAt": "2026-10-05T18:30:00.000Z",
"requiredMethods": ["OCR", "LIVENESS", "FACE_MATCH"],
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true }
],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"images": {
"expiresAt": "2026-10-02T18:40:00.000Z",
"documentFront": "<url-firmada>",
"documentBack": "<url-firmada>",
"documentPortrait": "<url-firmada>",
"selfie": "<url-firmada>"
}
}
}
ClaveQué es
documentFrontFrente del documento
documentBackReverso del documento
documentPortraitLa foto de la persona recortada del documento
selfieLa cara capturada en la prueba de vida
expiresAtVigencia de las URLs (10 minutos), distinta de la de la verificación
  • Son imágenes JPEG o PNG. Se bajan con un GET simple, sin headers.
  • Bajalas apenas llegan: si vencen, volvé a consultar el estado y vienen URLs nuevas.
  • Una foto que no existe no aparece, e images puede no venir: tu app tiene que funcionar sin ellas.
  • No hace falta subirlas al registrar a la persona: quedan cargadas solas como fotos de su documento.
  • Son datos personales: no registres las URLs en tus logs.
La sesión vence

La verificación vence en expiresAt. Pasado ese momento la consulta puede seguir mostrando PENDING, pero ya no va a aprobar y el alta responde 410 con 8116: si llegás a expiresAt sin resultado, abrí una sesión nueva.

4. Crear el lead​

Igual que en la verificación por imágenes: POST /leads con el header verificationId, el header Idempotency-Key y los datos confirmados. Ver Crear el lead.

Con la verificación en MANUAL_REVIEW el alta sale igual, con las mismas validaciones, y la respuesta lo avisa:

{
"success": true,
"data": {
"leadId": "6acd72072f1c8219496270ea",
"businessId": "6acd72072f1c8219496270eb",
"invitationCode": "B9B7D57",
"reused": false,
"identityInReview": true
}
}

5. Registro y login​

El registro con el invitationCode de un alta verificada no cambia: las fotos de la verificación quedan cargadas como fotos del documento del usuario. El login (POST /users/login) suma manualReview, siempre presente:

{
"success": true,
"data": {
"status": "PendingVerify",
"hasUploadedIdDocument": true,
"manualReview": true
}
}
manualReviewCuándo
trueLa persona se registró con la identidad en revisión, y la revisión sigue abierta o terminó rechazada
falseLa revisión terminó aprobada, o la persona se registró con la verificación ya aprobada o por otro camino

Es informativo: no cambia el status de la cuenta ni sus permisos. El refresh del token no lo trae; leelo del login.

Si la persona ya tenía código de invitación​

Si la persona ya tenía un código de invitación y tu app usó el SDK para verificar su identidad:

  1. Abrí la sesión con expectedDocumentNumber igual al documento del lead.
  2. Mandá el verificationId en el registro (POST /users), junto al invitationCode. La verificación puede estar aprobada o en revisión.

Las fotos quedan cargadas como fotos del documento y el login avisa si la identidad quedó en revisión. Si el comercio tiene activada la comparación de documento y la verificación es de otro documento, el registro responde 422 con 8121 y no crea la cuenta.

Si el registro ya se hizo sin el verificationId, vinculá la verificación después, en lugar de subir las fotos:

curl -X POST https://api.ali.app/rest/users/<authUserId>/id-document/from-verification \
-H "Authorization: Bearer <token>" \
-H "x-user-token: <token-del-usuario>" \
-H "Content-Type: application/json" \
-d '{ "verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21", "type": "DPI" }'

Responde 201 con las URLs de las fotos cargadas. Si no se puede vincular:

RespuestaCuándo
400 con 7000El verificationId no es un UUID o falta type
403 con 7144La sesión es de otro usuario
404 con 8115 u 8118La verificación no existe, o es de otro comercio
404 con 7102El usuario no tiene un documento de ese tipo
409 con 8114La verificación no está aprobada, por ejemplo porque sigue en revisión
422 con 8119La verificación es de otro documento

Verificación por imágenes​

PasoEndpointQué hace
1POST /onboarding/ocrExtrae los datos del documento y abre la verificación
2POST /onboarding/livenessPrueba de vida con selfie (y, si el comercio lo pide, comparación contra la foto del documento)
3POST /leads con el header verificationIdCrea el lead y el negocio, y devuelve el código de invitación

Los tres pasos se encadenan con el verificationId que devuelve el paso 1. El control es del lado del servidor: el paso 3 sólo crea el lead si la verificación quedó aprobada. Saltarse los pasos 1 y 2 desde el cliente no sirve de nada.

Autenticación​

Se usa el mismo access token de cualquier llamada, el que devuelve POST /auth/login:

curl -X POST https://api.ali.app/rest/auth/login \
-H "Content-Type: application/json" \
-d '{ "merchant": "<merchant>", "signature": "<firma>" }'

El cliente detrás de ese token necesita estos permisos:

PermisoPara qué
onboarding:ocrAbrir la sesión del SDK, consultar el resultado y, en la verificación por imágenes, el paso del documento
onboarding:livenessLa prueba de vida de la verificación por imágenes
leads:createCrear el lead, igual que en el alta clásica
El comercio sale del token

En el alta verificada, el comercio y el cliente se toman del token. El header x-merchant-id se ignora, y un clientId en el cuerpo se reemplaza por el del token. partner, sdk, country y paymentMethods se toman de la configuración del comercio —los que el paso 1 devuelve como DERIVED— y reemplazan a los del cuerpo. Igual tenés que mandar partner con un valor válido, porque el cuerpo pasa las mismas validaciones que el alta clásica.

Cómo leer las respuestas​

Todas las respuestas usan el mismo sobre. Una respuesta exitosa trae success en true y el resultado en data; un error trae success en false y la lista errors, cada uno con un code estable y un message legible:

{
"success": false,
"errors": [
{ "code": "8116", "message": "Identity verification has expired." }
]
}

Decidí siempre por el code y el status HTTP, no por el texto del mensaje.

1. Verificar el documento​

Multipart con la imagen frontal (obligatoria) y la del reverso (opcional). Sólo JPEG o PNG, hasta 5 MB por imagen. No admite campos de texto: un campo extra responde 422.

curl -X POST https://api.ali.app/rest/onboarding/ocr \
-H "Authorization: Bearer <token>" \
-F "dpiFront=@dpi-front.jpg;type=image/jpeg" \
-F "dpiBack=@dpi-back.jpg;type=image/jpeg"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "OCR_APPROVED",
"fields": [
{ "key": "documentNumber", "value": "1234567890101", "source": "OCR", "required": true },
{ "key": "firstName", "value": "ANA MARIA", "source": "OCR", "required": true },
{ "key": "expirationDate", "value": "2031-04-12", "source": "OCR", "required": true },
{ "key": "countryOfBirth", "source": "MANUAL", "required": true },
{ "key": "partner", "value": "migo", "source": "DERIVED", "required": true }
],
"blockingFields": [],
"requiredMethods": ["OCR", "LIVENESS"],
"paymentMethods": [{ "slug": "card", "acquirerSlug": "neonet" }],
"expiresAt": "2026-09-01T18:30:00.000Z"
}
}

Qué significa status:

statusQué hacer
OCR_APPROVEDSeguir al paso 2 con ese verificationId
DECLINEDEl documento no se pudo aprobar. Pedir una nueva captura y volver a llamar a este paso

Un documento rechazado llega con HTTP 200 y status DECLINED, no como error. Esta respuesta no incluye el motivo del rechazo.

La lista fields trae los datos de identidad con su origen:

sourceSignificado
OCRLo leyó el documento: precargalo en el formulario
MANUALEl documento no lo trae: pedíselo a la persona
DERIVEDValor configurado para el comercio (partner, sdk, country). Es el que va a usar el lead, aunque mandes otro en el paso 3

Entre esos campos viene expirationDate, la fecha de vencimiento del documento, que el alta del paso 3 exige. Si el documento no la trae y el comercio no permite capturarla a mano, aparece en blockingFields y la verificación queda DECLINED en este paso.

Usá esa lista para armar el formulario: no la hardcodees, porque qué campos se pueden capturar a mano depende de la configuración del comercio. blockingFields lista los campos que el documento no resolvió y que el comercio no permite capturar a mano; si trae alguno, la verificación queda DECLINED. El país de nacimiento nunca viene del documento, así que siempre aparece como MANUAL.

2. Prueba de vida​

curl -X POST https://api.ali.app/rest/onboarding/liveness \
-H "Authorization: Bearer <token>" \
-H "verificationId: 2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21" \
-F "selfie=@selfie.jpg;type=image/jpeg"
{
"success": true,
"data": {
"verificationId": "2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21",
"status": "APPROVED",
"liveness": { "status": "APPROVED", "score": 99, "warnings": [] }
}
}
  • score va de 0 a 100.
  • Cuando el comercio pide comparar la selfie con la foto del documento, la respuesta trae además faceMatch, con la misma forma que liveness.
  • Con status APPROVED la verificación habilita el paso 3.
  • Con status MANUAL_REVIEW se agotaron los intentos y la verificación quedó en revisión de una persona: ver Intentos.

Hay dos maneras de que esto no apruebe, y se tratan distinto:

Qué pasóRespuestaQué hacer
La selfie fue evaluada y rechazada200 con status DECLINED y el motivo en liveness.warnings (o faceMatch.warnings)La verificación sigue abierta: pedí otra selfie y reenviala a este paso con el mismo verificationId. Cada rechazo consume un intento; si era el último, esta misma llamada responde 403 con 8120, o 200 con status MANUAL_REVIEW si el comercio deriva a revisión (ver Intentos)
La verificación no se pudo completar422 con 8112 o 503 con 8113La verificación sigue abierta: se puede reenviar la selfie. Un 422 por una imagen o un verificationId mal formados no consume intentos; un fallo del lado de la verificación sí

3. Crear el lead​

Es POST /leads con el mismo cuerpo del alta clásica, más el header verificationId, el header Idempotency-Key y los dos campos del consentimiento:

curl -X POST https://api.ali.app/rest/leads \
-H "Authorization: Bearer <token>" \
-H "verificationId: 2f0a1f3e-6b1c-4a52-9a70-1d3f5c9b8e21" \
-H "Idempotency-Key: onboarding-lead-001" \
-H "Content-Type: application/json" \
-d '{
"cui": "1234567890101",
"firstName": "ANA MARIA",
"lastName": "LOPEZ GARCIA",
"dateOfBirth": "1990-04-12",
"expirationDate": "2031-04-12",
"nationality": "GTM",
"countryOfBirth": "GTM",
"gender": "F",
"maritalStatus": "soltero",
"commercialName": "Tienda Ana",
"businessName": "Tienda Ana",
"nit": "1234567",
"address": "4a calle 5-30 zona 1",
"phone": "50255551234",
"taxRegime": "pequeño contribuyente",
"rtuType": "SERVICIO",
"canInvoice": true,
"partner": "migo",
"sdk": "MIGO_PAY",
"country": "GTM",
"paymentMethods": [{ "slug": "akisiQR", "acquirerSlug": "akisiQR" }],
"consentVersion": "v1",
"consentAcceptedAt": "2026-09-01T18:05:00.000Z"
}'
QuéReglaSi no se cumple
CuerpoLas mismas validaciones que el alta clásica400
verificationIdLa verificación del paso 1, aprobada en el paso 2400 con 7000 si no es un UUID; 404 con 8115 si no existe o con 8118 si es de otro comercio; 410 con 8116 si venció; 403 con 8120 si agotó sus intentos; 409 con 8114 si no está aprobada
Idempotency-KeyObligatoria, hasta 255 caracteres400 con 7000
consentVersion y consentAcceptedAtLa versión del consentimiento que aceptó la persona —tiene que ser la que tiene configurada el comercio; pedísela a tu contacto en Migo— y la fecha ISO 8601 en que lo aceptó400 con 7000
Datos de identidad: cui, firstName, lastName, dateOfBirth, expirationDate, nationality, countryOfBirth, placeOfBirth, gender, maritalStatusTienen que coincidir con el documento verificado, salvo los que el comercio permite editar. Enviálos tal como los devolvió el paso 1422 con 8119
nitObligatorio en el alta verificada422 con 8119
{
"success": true,
"data": {
"leadId": "000000000000000000000001",
"businessId": "000000000000000000000002",
"invitationCode": "A1B2C3",
"reused": false
}
}

La persona sigue el resto del alta con ese invitationCode, sin tener que escribirlo. reused en true indica que ya existía un lead con ese documento para el comercio; si ese lead ya completó su registro, la respuesta es 409 con 7121.

La Idempotency-Key es obligatoria

Reintentar con la misma clave, mientras la verificación no venza, devuelve el resultado original sin crear otro lead, aunque cambien los datos (el cuerpo tiene que seguir siendo válido). Usar otra clave sobre una verificación que ya creó su lead, o mientras otro pedido lo está creando, responde 409 con 8117. Generá una clave por cada alta.

Por qué se rechazó​

Cuando la prueba de vida o la comparación de rostro no aprueban, la respuesta del paso 2 trae warnings, y cada uno tiene un code del catálogo de Migo. Mapeá ese código a tu propio texto: el catálogo es estable aunque cambie la tecnología de verificación por detrás, así que tu integración no se entera.

La respuesta del paso 1 no trae el motivo de un documento rechazado. Si lo necesitás, consultá GET /onboarding/verifications/{verificationId} con el verificationId de esa respuesta: trae reasonCode cuando el rechazo tiene uno identificado.

CódigoQué pasó
DOCUMENT_EXPIREDEl documento venció
DOCUMENT_NOT_RECOGNIZEDNo se pudo validar el documento
DOCUMENT_TYPE_NOT_SUPPORTEDTipo de documento no admitido
DOCUMENT_TAMPEREDSe detectó manipulación
DOCUMENT_PORTRAIT_MISSINGEl documento no trae retrato
DOCUMENT_IN_BLOCKLISTDocumento en lista de bloqueo
PUBLIC_DOCUMENT_IMAGEImagen pública conocida de internet
DOCUMENT_DATA_UNREADABLENo se pudieron leer los datos
DOCUMENT_DATA_MISMATCHLos datos no coinciden entre sí o con lo declarado
DOCUMENT_NUMBER_MISMATCHEl documento no es el esperado. Sólo con expectedDocumentNumber y la comparación de documento activada
IMAGE_TOO_BLURRYImagen borrosa
IMAGE_LOW_QUALITYImagen oscura o quemada
SCREEN_CAPTURE_DETECTEDFoto de una pantalla
PRINTED_COPY_DETECTEDFotocopia
MINIMUM_AGE_NOT_MET, MAXIMUM_AGE_EXCEEDED, AGE_NOT_DETECTEDEdad fuera de rango o no determinable
DUPLICATE_USERPosible usuario duplicado
NO_FACE_DETECTED, MULTIPLE_FACES_DETECTEDNingún rostro, o más de uno
LOW_LIVENESS_SCORE, LIVENESS_ATTACK_DETECTEDLa prueba de vida no aprobó
FACE_QUALITY_TOO_LOWCalidad de la selfie insuficiente
FACE_MISMATCHEl rostro no coincide con el documento
FACE_IN_BLOCKLISTRostro en lista de bloqueo
UNMAPPEDUn motivo que el catálogo todavía no contempla

Intentos​

Cada resultado que no aprueba —una selfie rechazada o una verificación que no se pudo completar— consume un intento de la verificación. El límite lo fija Migo por comercio; el default son 3, y el presupuesto es por verificación.

Cada llamada al paso 1 abre una verificación nueva, y un documento rechazado la cierra. Lo que se reintenta sobre una misma verificación es el paso 2.

Al agotarse los intentos pasa una de dos cosas, según la configuración del comercio:

ConfiguraciónQué pasa
Sin revisiónEl paso 2 responde 403 con 8120, y desde ahí el paso 2 y el alta también responden 8120. Ofrecé soporte en vez de otro reintento
Con revisiónEl paso 2 responde 200 con status MANUAL_REVIEW: la verificación queda esperando la decisión de una persona y su expiresAt se extiende. El alta responde 403 con 8120 hasta que esa revisión la apruebe. Consultá el estado hasta que pase a APPROVED o DECLINED

La consulta de estado no se corta por los intentos: siempre responde con el último estado.

Errores​

CódigoHTTPCuándo
7000400Parámetros inválidos: verificationId mal formado, Idempotency-Key, consentimiento o type al vincular una verificación
7102404Al vincular una verificación, el usuario no tiene un documento de ese tipo
7121409El lead de ese documento ya completó su registro
7144403Al vincular una verificación, la sesión es de otro usuario
7615403El cliente del token no tiene el permiso de la ruta
8110403El comercio no tiene el flujo habilitado
8111403El comercio no tiene una configuración de verificación válida, o no tiene habilitado el modo SDK
8112422Imagen inválida, faltante o mayor a 5 MB, verificationId mal formado en el paso 2, o la verificación no se pudo completar. No es un documento rechazado: eso es 200 con status DECLINED
8113503El servicio de verificación no respondió
8114409La verificación no está en el estado que el paso necesita, por ejemplo una selfie sobre una verificación ya rechazada
8115404El verificationId no existe
8116410La verificación venció; hay que empezar de nuevo
8117409La verificación ya creó su lead con otra Idempotency-Key, o hay otra creación en curso
8118404La verificación es de otro comercio
8119422Falta el nit, o un dato de identidad no coincide con el documento verificado
8120403Se agotaron los intentos de la verificación
8121422Al registrarse con verificationId, la verificación es de otro documento que el del lead

Una verificación de otro comercio responde 404, no 403: la plataforma no confirma la existencia de recursos ajenos.

Relacionado​