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

El API expone dos entornos con la misma interfaz — misma ruta, mismo formato de request y de response. Solo cambia el segmento final de la URL:

Entorno	Endpoint	Estado
Producción	POST https://api.looviin.com/PRO	● Disponible
Sandbox / DEV	POST https://api.looviin.com/DEV	● Disponible (simulación)

Content-Type: application/json en ambos entornos.

Entorno DEV (sandbox de simulación): /DEV usa el mismo contrato que /PRO (mismos campos, mismo scoring, mismos códigos de respuesta), pero corre en modo simulación: valida y puntúa tu lote sin persistir la solicitud, sin enviar WhatsApp y sin consumir cuota — podés re-probar los mismos datos cuantas veces quieras. La respuesta incluye "mode":"dev" y cada resultado lleva "simulated":true (con id:null, porque no se crea ninguna solicitud real). Para que veas el mensaje que recibiría el usuario sin enviar nada, cada resultado que dispararía un outbound incluye "would_notify" (preview: tipo de notificación — approved/rejected/offer —, destino y plantilla). Usalo para validar tu integración de punta a punta antes de pasar a /PRO.

Request — body

Los nombres de los campos van en inglés (convención de la industria). Por compatibilidad, el endpoint /PRO aún acepta los nombres en español como alias heredado, pero documentamos y recomendamos los de inglés.

{
  "applications": [
    {
      "name":           "Juan Pérez",
      "id_number":      "1234567890",
      "city":           "Bogotá",
      "phone":          "+573001234567",
      "platform":       "rappi",
      "currency":       "COP",
      "income":         2500000,
      "debt_amount":    800000,
      "num_debts":      "1",
      "debt_age":       "lt6",
      "prior_history":  "no",
      "whatsapp_optin": true
    }
  ]
}

Campos

Campo	Tipo	Req.	Descripción
name	string	Sí	Nombre completo del solicitante. Alias ES: nombre
id_number	string	Sí	Cédula de ciudadanía. Alias ES: cedula
city	string	Sí	Ciudad de residencia. Alias ES: ciudad
phone	string	No	Número con código de país. Alias ES: telefono
platform	string	No	rappi | inDrive | uber | texto libre (nombre de la plataforma). Alias ES: plataforma
currency	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. Alias ES: moneda
income	number	Sí	Ingresos mensuales generados en tu plataforma, en la moneda declarada (> 0). Alias ES: ingreso / ingreso_cop
debt_amount	number	Sí	Monto de la deuda a consolidar, en la moneda declarada (> 0). Alias ES: monto_deuda / monto_deuda_cop
num_debts	string	Sí	"1" | "2" | "3". Alias ES: num_deudas
debt_age	string	Sí	Ver tabla abajo. Alias ES: antiguedad_mora
prior_history	string	Sí	"yes" | "no". Alias ES: historial_previo ("si"/"no")
whatsapp_optin	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. Alias ES: optin_whatsapp

Wrapper: el array raíz es applications (alias ES heredado: aplicaciones). Máximo 100 por request.

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 whatsapp_optin. Es un requisito de la plataforma de WhatsApp/Meta para mensajes iniciados por la empresa: solo se contactará a los usuarios que dieron whatsapp_optin: true.

Valores de debt_age

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

La respuesta va en inglés (mismo estándar que el request).

Éxito 200

{
  "processed": 1,
  "errors": 0,
  "results": [
    {
      "id_number": "1234567890",
      "name":      "Juan Pérez",
      "id":        42,
      "score":     75,
      "decision":  "approved",
      "status":    "pending_signature"
    }
  ]
}

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

{
  "processed": 1,
  "errors": 1,
  "results": [ ... ],
  "errors_detail": [
    { "id_number": "0000000000", "error": "income is required and must be > 0 (numeric)" }
  ]
}

¿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 phone (WhatsApp), no el id_number. Si ya existe una aplicación abierta (no rechazada ni desembolsada) con ese número, la nueva se rechaza con el motivo “A request already exists for this WhatsApp number”. El id_number es obligatorio y se devuelve igual en cada resultado para emparejarlo con tu envío.

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

Qué recibe el cliente por WhatsApp

Cuando una aplicación entra con whatsapp_optin: true y queda registrada, Looviin dispara un outbound de WhatsApp al número de phone: 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	status
≥ 70	approved	pending_signature
50 – 69	in_review	in_review
30 – 49	in_review	in_review
< 30	rejected	rejected
Monto > límite	rejected	rejected

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_exceeded dentro de errors_detail[]; el resto del lote se procesa normal (modo procesamiento parcial, HTTP 200):

{
  "processed": 280,
  "errors": 20,
  "results": [ ... 280 items ... ],
  "errors_detail": [
    {
      "id_number": "1234567890",
      "error":     "quota_partner_exceeded",
      "remaining": 0,
      "daily_cap": 300
    }
  ]
}

Si tu credencial fue creada sin cap (campo daily_cap 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": {
    "name":      "Aliado Demo S.A.S.",
    "country":   "CO",
    "daily_cap": 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. daily_cap 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_exceeded (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
income, debt_amount	número o string numérico (2500000 o "2500000"); también los alias heredados ingreso/ingreso_cop · monto_deuda/monto_deuda_cop	número (> 0)
currency	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_debts	string o entero ("1" o 1)	string "1"/"2"/"3"
debt_age	cualquier capitalización	minúsculas
prior_history	yes/no (o el alias ES si/no), cualquier capitalización	minúsculas (si/no interno)
platform	texto libre o ausente	minúsculas, gig si vacío
name, id_number, city, phone	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 '{
    "applications": [
      {
        "name":           "Ana García",
        "id_number":      "9876543210",
        "city":           "Medellín",
        "phone":          "+573109876543",
        "platform":       "inDrive",
        "currency":       "COP",
        "income":         3200000,
        "debt_amount":    600000,
        "num_debts":      "2",
        "debt_age":       "6a12",
        "prior_history":  "yes",
        "whatsapp_optin": true
      }
    ]
  }'

GET · consultar cuota

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