GIG Ingest API

Ingesta masiva de aplicaciones del canal GIG (plataformas de socios y/o usuarios masivos) con evaluación automática de scoring crediticio. Hasta 100 aplicaciones por request.

Autenticación

Cada request debe incluir tu API Key en el header:

X-API-Key: <tu-api-key>

Las credenciales las entrega tu contacto en Looviin. Trátalas como secretas; si se compromete una, solicita su revocación.

Endpoint

POST https://api.looviin.com/PRO

Content-Type: application/json.

Request — body

{
  "aplicaciones": [
    {
      "nombre":          "Juan Pérez",
      "cedula":          "1234567890",
      "ciudad":          "Bogotá",
      "telefono":        "+573001234567",
      "plataforma":      "rappi",
      "moneda":          "COP",
      "ingreso":         2500000,
      "monto_deuda":     800000,
      "num_deudas":      "1",
      "antiguedad_mora": "lt6",
      "historial_previo":"no",
      "optin_whatsapp":  true
    }
  ]
}

Campos

Campo	Tipo	Req.	Descripción
nombre	string	Sí	Nombre completo del solicitante
cedula	string	Sí	Cédula de ciudadanía
ciudad	string	Sí	Ciudad de residencia
telefono	string	No	Número con código de país
plataforma	string	No	rappi | inDrive | uber | texto libre (nombre de la plataforma)
moneda	string	No	Código de 3 letras de la moneda de los montos: COP | USD | MXN | PEN | ARS | CLP | BRL … Si se omite, se infiere por el código de país del teléfono.
ingreso	number	Sí	Ingresos mensuales generados en tu plataforma, en la moneda declarada (> 0). Alias heredado: ingreso_cop
monto_deuda	number	Sí	Monto de la deuda a consolidar, en la moneda declarada (> 0). Alias heredado: monto_deuda_cop
num_deudas	string	Sí	"1" | "2" | "3"
antiguedad_mora	string	Sí	Ver tabla abajo
historial_previo	string	Sí	"si" | "no"
optin_whatsapp	boolean	Sí	Consentimiento del usuario para ser contactado por Looviin vía WhatsApp. Debe ser true para que el cliente reciba el flujo de WhatsApp y firma del contrato. Sin consentimiento la solicitud se registra y evalúa igual, pero no se le contactará por WhatsApp.

Consentimiento WhatsApp (opt-in): antes de enviar la solicitud, el socio debe haber obtenido el consentimiento explícito del usuario para que Looviin lo contacte por WhatsApp, y enviarlo en optin_whatsapp. Es un requisito de la plataforma de WhatsApp/Meta para mensajes iniciados por la empresa: solo se contactará a los usuarios que dieron optin_whatsapp: true.

Valores de antiguedad_mora

Valor	Significado
lt6	Menos de 6 meses en mora
6a12	Entre 6 y 12 meses en mora
1a2	Entre 1 y 2 años en mora
gt2	Más de 2 años en mora

Response

Éxito 200

{
  "procesados": 1,
  "errores": 0,
  "resultados": [
    {
      "cedula":   "1234567890",
      "nombre":   "Juan Pérez",
      "id":       42,
      "score":    75,
      "decision": "approved",
      "estado":   "firma_pendiente"
    }
  ]
}

Si alguna aplicación falla validación, se incluye errores_detalle (el resto del lote se procesa igual):

{
  "procesados": 1,
  "errores": 1,
  "resultados": [ ... ],
  "errores_detalle": [
    { "cedula": "0000000000", "error": "ingreso (ingreso_cop) requerido y > 0 (numérico)" }
  ]
}

¿Quedó registrada o no?

Cómo interpretar la respuesta por cada aplicación del lote:

Unicidad por WhatsApp: el requisito que evita duplicados es el número de telefono (WhatsApp), no la cedula. Si ya existe una aplicación abierta (no rechazada ni desembolsada) con ese número, la nueva se rechaza con el motivo “No se puede generar esta solicitud porque ya existe una asociada a este número de whatsapp”. La cedula es obligatoria y se usa solo como identificador en la respuesta.

El resto del lote se procesa igual aunque algunas fallen: revisa resultados[] vs errores_detalle[] aplicación por aplicación, no solo el código HTTP.

Qué recibe el cliente por WhatsApp

Cuando una aplicación entra con optin_whatsapp: true y queda registrada, Looviin dispara un outbound de WhatsApp al número de telefono: una oferta co-branded (tu marca + Looviin) con el saldo de la deuda y un botón “Me interesa”. Si el cliente acepta, el resto del flujo (extractos, validación de ingreso, firma) ocurre dentro del mismo chat. Así se ve la respuesta esperada del lado del cliente:

Este es un ejemplo ilustrativo del mensaje co-branded. El texto exacto, el nombre del aliado y los botones se configuran en tu credencial; “Aliado Demo” es un nombre ficticio.

Tabla de decisiones

Score	decision	estado
≥ 70	approved	firma_pendiente
50 – 69	en_revision	en_revision
30 – 49	en_revision	en_revision
< 30	rechazado	rechazado
Monto > límite	rechazado	rechazado

Errores HTTP

Código	Descripción
400	JSON inválido o campos requeridos faltantes
401	API Key inválida o ausente
405	Método no permitido (solo POST/GET)
500	Error interno temporal — reintentar

Cuota diaria por partner

Tu credencial tiene un cap diario negociado con Looviin (ventana rolling 24h). Si un lote excede el restante disponible, las aplicaciones que sobran se rechazan individualmente con el código quota_partner_excedida dentro de errores_detalle[]; el resto del lote se procesa normal (modo procesamiento parcial, HTTP 200):

{
  "procesados": 280,
  "errores": 20,
  "resultados": [ ... 280 items ... ],
  "errores_detalle": [
    {
      "cedula":     "1234567890",
      "error":      "quota_partner_excedida",
      "restante":   0,
      "cap_diario": 300
    }
  ]
}

Si tu credencial fue creada sin cap (campo cap_diario nulo en el LMS), no hay límite por partner — los lotes solo están sujetos al máximo de 100 apps por request.

Consultar cuota antes de enviar (GET)

Para no enviar un lote que vas a exceder, podés consultar tu estado actual con un GET al mismo endpoint:

GET https://api.looviin.com/PRO
X-API-Key: <tu-api-key>

Respuesta:

{
  "partner": {
    "nombre":     "Aliado Demo S.A.S.",
    "pais":       "CO",
    "cap_diario": 300,
    "used_24h":   45,
    "remaining":  255
  },
  "window":     "rolling_24h",
  "fetched_at": "2026-05-23T20:28:07.862918+00:00"
}

El sandbox tiene la pestaña Conexión & cuota con un botón “Consultar cuota” debajo del campo X-API-Key que llama a este endpoint y muestra el resultado en cards. cap_diario y remaining son null si tu credencial no tiene cap.

Lotes

Máximo 100 aplicaciones por request. Las que fallen validación se omiten individualmente; el resto se procesa. Si además el lote excede tu cap diario, se procesan las primeras N apps que entren en el restante y las demás responden con quota_partner_excedida (ver arriba).

Normalización tolerante

El endpoint normaliza la entrada antes de validar. No necesitas adaptar tu formato a estos casos:

Campo	Acepta	Se normaliza a
ingreso, monto_deuda	número o string numérico (2500000 o "2500000"); también los alias heredados ingreso_cop / monto_deuda_cop	número (> 0)
moneda	código de 3 letras en cualquier capitalización (cop, Usd…)	mayúsculas; si no es válida se infiere por el teléfono
num_deudas	string o entero ("1" o 1)	string "1"/"2"/"3"
antiguedad_mora	cualquier capitalización	minúsculas
historial_previo	cualquier capitalización	minúsculas (enviar si/no sin tilde)
plataforma	texto libre o ausente	minúsculas, gig si vacío
nombre, cedula, ciudad, telefono	con espacios sobrantes	trim()

Motor de scoring

Criterio	Puntos máx
Capacidad de pago (ingreso / cuota de referencia)	25
Canal de origen (GIG = 20 fijo)	20
Antigüedad de mora	20
Número de deudas en mora	20
Historial de pago previo	15
Total	100

Ejemplos (cURL)

POST · enviar lote

curl -X POST https://api.looviin.com/PRO \
  -H "Content-Type: application/json" \
  -H "X-API-Key: TU_API_KEY" \
  -d '{
    "aplicaciones": [
      {
        "nombre":          "Ana García",
        "cedula":          "9876543210",
        "ciudad":          "Medellín",
        "telefono":        "+573109876543",
        "plataforma":      "inDrive",
        "moneda":          "COP",
        "ingreso":         3200000,
        "monto_deuda":     600000,
        "num_deudas":      "2",
        "antiguedad_mora": "6a12",
        "historial_previo":"si",
        "optin_whatsapp":  true
      }
    ]
  }'

GET · consultar cuota

curl https://api.looviin.com/PRO \
  -H "X-API-Key: TU_API_KEY"