Saltar al contenido principal
Migo Docs

Leads

Un lead es el primer prospecto del onboarding — alguien que quiere empezar a usar los productos de Migo. Crear un lead no otorga ninguna capacidad por sí mismo; captura a la persona y su negocio para que el resto de la cadena de onboarding pueda ejecutarse.

Durante este onboarding, un lead se da de alta en el conjunto de productos de Migo:

  • Tarjetas físicas — el programa de tarjetahabientes asociado al comercio.

  • La app Wallet — la experiencia de wallet para el usuario final.

  • Pagos alternativos dentro de la wallet — rieles de pago adicionales dentro de la wallet, declarados mediante paymentMethods y sdk.

  • URL base: https://api.ali.app/rest

  • Autenticación: Authorization: Bearer <token> (token de comercio)

Crear un lead​

POST /leads

curl -X POST https://api.ali.app/rest/leads \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "gender": "F",
    "cui": "XXXXXXXXX",
    "expirationDate": "2030-12-31",
    "commercialName": "Example Store",
    "partner": "your-partner-slug",
    "phone": "00000000",
    "address": "Example Avenue 12-34, Zone 1",
    "businessName": "Example Store",
    "nationality": "GTM",
    "countryOfBirth": "GTM",
    "country": "GTM",
    "dateOfBirth": "1990-01-15",
    "placeOfBirth": "Example City",
    "neighborhood": "Example District",
    "maritalStatus": "soltero",
    "economicActivity": "Retail sales",
    "canInvoice": true,
    "taxRegime": "general",
    "nit": "XXXXXXXXX",
    "rtuType": "standard",
    "email": "jane@example.com",
    "paymentMethods": [
      { "slug": "akisiQR", "acquirerSlug": "akisi" },
      { "slug": "td/tc", "acquirerSlug": "neonet" }
    ],
    "sdk": "MIGO_LINK_USD"
  }'

Opcionalmente se puede enviar el encabezado x-merchant-id para asociar el lead con un comercio específico.

Cuerpo de la solicitud​

CampoTipoRequeridoNotas
firstNamestring✅
lastNamestring✅
genderenum✅Uno de F, M, OTHER
cuistring✅Número de identificación personal
expirationDatestring✅Vencimiento del documento, YYYY-MM-DD
commercialNamestring✅Nombre comercial
partnerenum✅Partner asociado al lead
phonestring✅Formato internacional
addressstring✅Dirección física
nationalityenum (país)—Acepta alfa-2 o alfa-3, se normaliza a alfa-3. Por defecto GTM
countryOfBirthenum (país)—Acepta alfa-2 o alfa-3, se normaliza a alfa-3
countryenum (país)—Acepta alfa-2 o alfa-3, se normaliza a alfa-3
dateOfBirthstring—YYYY-MM-DD
placeOfBirthstring—
neighborhoodstring—
maritalStatusenum—Uno de soltero, casado, viudo, divorciado, separado
serialNumberstring—
taxRegimeenum—Por defecto NA (ninguno)
nitstring—Número de identificación tributaria
businessNamestring—Razón social; por defecto toma commercialName si se omite
economicActivitystring—
canInvoiceboolean—Por defecto false
rtuTypestring—
lastRtuUpdateDatestringcondicionalYYYY-MM-DD. Requerido solo cuando partner es el partner Tributax
locationobject—{ region?, administrativeAreaLevel1?, administrativeAreaLevel2? }
emailstring—Correo electrónico válido
clientIdstring—
sdkstring—Perfil del SDK de la wallet al que se da de alta el lead (ver abajo)
paymentMethodsarray—Métodos de pago alternativos habilitados en la wallet (ver abajo)
documentsarray—{ url, type?, provider? } documentos de soporte
currenciesnumber[]—

Cualquier campo que no aparezca arriba es rechazado por la validación.

Productos: paymentMethods y sdk​

Estos dos campos declaran a qué productos de Migo se incorpora el lead:

  • paymentMethods habilita los pagos alternativos ofrecidos dentro de la wallet. Cada elemento es un objeto que describe el método y su adquirente:

    { "slug": "akisiQR", "acquirerSlug": "akisi" }
    • slug — el método de pago (por ejemplo un riel QR o un riel de tarjeta).
    • acquirerSlug — el adquirente que procesa ese método.

    Envía un elemento por cada método que quieras habilitar en la wallet.

  • sdk selecciona el perfil del SDK de la app Wallet al que se da de alta el lead (por ejemplo MIGO_LINK_USD). Define qué experiencia de wallet y qué moneda se aprovisionan para el prospecto.

El producto de tarjetas físicas forma parte del mismo onboarding y se aprovisiona para el lead una vez que se promueve a negocio y se registra un tarjetahabiente — consulta Qué sigue.

Normalización de país​

nationality, countryOfBirth y country aceptan ISO 3166 alfa-2 o alfa-3 en la entrada y se normalizan a alfa-3 antes de almacenar el lead (GT → GTM). Todas las respuestas posteriores devuelven alfa-3.

Respuesta​

El lead creado se devuelve con su invitationCode — úsalo directamente para registrar al owner (no hay un paso de generación de código aparte):

{
  "success": true,
  "data": {
    "_id": "...",
    "invitationCode": "25DC4D1"
  }
}

En caso de fallo, success es false y errors lleva entradas { message, code }. También puedes resolver un lead más tarde con la llamada de obtención por código a continuación.

Obtener un lead por código de invitación​

GET /leads/{code}

Resuelve el lead asociado a un código de invitación público. Se usa durante el onboarding para rehidratar todo lo capturado del prospecto.

curl https://api.ali.app/rest/leads/25DC4D1 \
  -H "Authorization: Bearer <token>"

Respuesta​

{
  "success": true,
  "data": {
    "_id": "...",
    "invitationCode": "25DC4D1",
    "firstName": "Jane",
    "lastName": "Doe",
    "nationality": "GTM",
    "gender": "F",
    "dateOfBirth": "1990-01-15",
    "countryOfBirth": "GTM",
    "placeOfBirth": "Example City",
    "neighborhood": "Example District",
    "maritalStatus": "soltero",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "cui": "XXXXXXXXX",
    "expirationDate": "2030-12-31",
    "commercialName": "Example Store",
    "businessName": "Example Store",
    "phone": "00000000",
    "address": "Example Avenue 12-34, Zone 1",
    "taxRegime": "general",
    "canInvoice": true,
    "hasRegime": true,
    "partner": "your-partner-slug",
    "nit": "XXXXXXXXX",
    "clientId": "",
    "country": "GTM",
    "sdk": "MIGO_LINK_USD",
    "paymentMethods": [
      { "slug": "akisiQR", "acquirerSlug": "akisi" },
      { "slug": "td/tc", "acquirerSlug": "neonet" }
    ],
    "payoutAccountNumber": null
  }
}

El objeto data combina los campos personales del lead con los campos de onboarding de su primer negocio (nombre comercial/razón social, teléfono, dirección, datos tributarios, partner, nit, country, sdk y paymentMethods). Cuando ningún lead coincide con el código, data es undefined.

Documentos del lead​

Los archivos capturados para un lead se leen mediante POST /leads/files/upload/{fileName}, donde {fileName} es el nombre del archivo almacenado. Esto forma parte del flujo de documentos del lead/negocio — consulta Archivos de Lead y Negocio para el ciclo completo de archivos.

Qué sigue​

El lead es el punto de entrada de la cadena de onboarding:

  1. Crear el lead (esta página) — captura al prospecto y los productos a los que se da de alta.
  2. Invitación de sucursal — se aprovisiona una sucursal con un código de invitación, resuelto mediante GET /leads/{code}; consulta Terminales para el onboarding de terminal/sucursal.
  3. Registro de usuario — el prospecto se convierte en usuario de la wallet y tarjetahabiente; consulta Gestión de Tarjetahabientes.

Errores​

CódigoNombreSignificado
7105ERROR_CREATE_LEADNo se pudo crear el lead
7121LEAD_ALREADY_REGISTEREDEl lead ya fue registrado
7130LEAD_NOT_FOUNDCódigo de invitación desconocido