Flujo Embebido — cómo embebernos

🇺🇸 Read this in English →

Empecemos
por la verdad: como Lender, no embebés nada #

Este es el malentendido número uno, así que lo dejamos clarísimo
desde la primera línea: en el flujo embebido, tu institución NO
embebe ningún widget, SDK ni iframe de Prosperas. Es al
revés.

Prosperas hospeda toda la experiencia del Consumer y llama a
TU API. El Consumer explora las ofertas de tu institución,
completa sus datos y elige una oferta, todo dentro de la interfaz de
Prosperas, sin salir en ningún momento. Recién al final —cuando la
solicitud ya fue enviada y aceptada para procesamiento— Prosperas
redirige al Consumer a tu portal para que firme o cierre la
operación.

Dicho de otra forma: no tenés que construir ni mantener una UI de
originación para el Consumer. Vos exponés dos capacidades de API en
tiempo real; nosotros nos encargamos de la experiencia de punta a
punta.

Referencia en producción: el Origin
Wasti opera hoy exactamente bajo este modelo. Si querés
un caso real contra el cual validar tu integración, ese es.

Quién construye qué (de un
vistazo) #

Responsabilidad	Quién la asume
UI del Consumer (explorar ofertas, cargar datos, elegir oferta)	Prosperas
API de decisión y de envío que Prosperas consume	Vos (el Lender)
Portal final para firmar/cerrar (post-redirección)	Vos (el Lender)
Postbacks de estado de vuelta a Prosperas	Vos (el Lender)
Adapter que traduce el modelo de Prosperas a tu API	Prosperas

La asimetría
del contrato (y por qué te conviene) #

Antes de entrar en las capacidades, entendé cómo se reparten las
responsabilidades técnicas, porque la primera dirección es un beneficio
directo para vos:

• Prosperas → Lender: nos adaptamos a TU API
  existente. No te pedimos que implementes un contrato fijo de
  Prosperas ni que repliques el de otro Lender (como Wasti). Nuestra capa
  de integración construye un adapter por Lender: el
  protocolo, la autenticación, los endpoints y los nombres de campos son
  los tuyos. El mapeo exacto de campos se acuerda durante
  el onboarding. No hay un esquema rígido que tengas que cumplir.

• Lender → Prosperas: acá el contrato es nuestro.
  Los postbacks de estado (aprobación, desembolso, rechazo) siguen un
  formato definido por Prosperas y tu institución se adapta a él. El
  detalle completo está en la guía del Sistema de
  Postbacks.

Esta asimetría te da libertad para exponer tu API de decisión y envío
con tu propio diseño, mientras mantenemos consistencia del lado de las
notificaciones para todos los Lenders del marketplace.

Las dos capacidades
requeridas #

Tu integración se reduce a dos capacidades lógicas —
ojo, no necesariamente dos endpoints únicos. Podés dividir cada una en
varias llamadas (por ejemplo, un paso de token y otro de validación
documental) o fusionarlas en menos llamadas, siempre que respetes el
input/output de abajo.

#	Capacidad	Qué te envía Prosperas (input)	Qué le devolvés a Prosperas (output)
1	Decisión de crédito en tiempo real (pre-aprobación)	Tracking ID + identidad e ingresos del Consumer	Una decisión (approved / rejected / pending) y, si aprueba, el catálogo de ofertas disponibles
2	Envío de la aplicación (submission)	Tracking ID (+ referencia de aplicación de tu sistema, si aplica) + datos completos del Consumer + oferta elegida	Un estado final + una URL de redirección hacia tu portal

Requisitos duros que no
pueden faltar #

Por más que dividas o fusiones llamadas, estas dos reglas son
innegociables:

1. La decisión con ofertas debe llegar
   antes de que el Consumer complete el resto de la
   aplicación. Prosperas necesita saber qué ofertas mostrar antes de seguir
   pidiendo datos.
2. La URL de redirección debe llegar al
   final, una vez enviada la aplicación. Sin esa URL no podemos
   completar el hand-off del Consumer hacia tu portal.

Si tu proceso de decisión es asíncrono (revisión manual, validación
externa), respondé con estado pending y resolvé después por
polling o callback — pero la regla “decisión + ofertas primero,
redirección al final” sigue aplicando.

Cómo se ven las
llamadas (ejemplo ilustrativo) #

Ejemplo ilustrativo — el formato real se adapta a TU
API. Los cuerpos de abajo son solo un modelo mental para que
entiendas qué información viaja en cada dirección. No son un
contrato rígido: los nombres de campos, la estructura, el
protocolo y la autenticación reales se acuerdan en el onboarding y se
mapean contra tu API existente. No implementes esto literalmente.

Capacidad 1 —
Decisión de crédito (pre-aprobación) #

Prosperas te llama con la identidad y los ingresos del Consumer:

// Prosperas → Lender  (request ilustrativo)
{
  "trackingId": "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "consumer": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "fullName": "Nombre Apellido",
    "monthlyIncome": 3200000,
    "currency": "COP"
  }
}

Vos respondés con la decisión y, si aprobás, el catálogo de
ofertas:

// Lender → Prosperas  (response ilustrativo — caso aprobado)
{
  "trackingId": "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "decision": "approved",              // approved | rejected | pending
  "offers": [
    {
      "offerId": "OF-001",
      "amount": 5000000,
      "termMonths": 24,
      "monthlyPayment": 265000,
      "annualRate": 0.28
    }
  ]
}

Si rechazás o la decisión queda pendiente, no mandás ofertas:

// Lender → Prosperas  (response ilustrativo — rechazo)
{
  "trackingId": "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "decision": "rejected",
  "reason": "consumer_not_eligible"    // decisión de negocio, NO falla técnica
}

Capacidad 2 —
Envío de la aplicación (submission) #

Con la oferta ya elegida por el Consumer, Prosperas te envía los
datos completos:

// Prosperas → Lender  (request ilustrativo)
{
  "trackingId": "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "lenderApplicationRef": "APP-99182",   // opcional: tu referencia, si aplica
  "selectedOfferId": "OF-001",
  "consumer": {
    "documentType": "CC",
    "documentNumber": "1234567890",
    "fullName": "Nombre Apellido",
    "email": "consumer@example.com",
    "phone": "+573001234567"
    // ...resto de datos completos del formulario
  }
}

Vos respondés con el estado final y la URL de redirección al portal
donde el Consumer firma:

// Lender → Prosperas  (response ilustrativo)
{
  "trackingId": "b3f1c2a4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
  "status": "submitted",
  "redirectUrl": "https://portal.tulender.com/firmar?ref=APP-99182"
}

Repetimos: los nombres exactos (trackingId,
decision, offers, redirectUrl,
etc.) son ilustrativos. En tu integración real usamos
tus nombres de campos.

El tracking ID: un
identificador, un journey #

Cada solicitud que pasa por el flujo embebido lleva un
tracking ID (un UUID) que Prosperas genera al iniciar
el journey del Consumer. Es la referencia interna de esa sesión y la
columna vertebral de la trazabilidad de punta a punta:

• Viaja como trackingId en cada llamada que Prosperas le
  hace a tu API (pre-aprobación y submission).
• Viaja como clickId / click_id en la URL de
  redirección del hand-off final hacia tu portal.
• Tu institución debe repetirlo (echo) exactamente en
  cada postback de estado que le envíes a Prosperas — así conectamos cada
  notificación con el journey correcto.

Un tracking ID = un solo journey. No contiene ningún
dato personal del Consumer: es un identificador opaco, pensado
exclusivamente para correlación entre sistemas. Para el ciclo de vida
completo, mirá el “ciclo de vida del tracking ID” en el
Overview, y para el formato exacto en las
notificaciones, el Sistema de Postbacks.

Qué esperamos de tu API
(no funcionales) #

Como el Consumer espera en vivo dentro del flujo de
Prosperas, tu API de decisión y submission tiene que cumplir con
expectativas claras de latencia y comportamiento ante fallas:

• Latencia objetivo: p95 menor a 5 segundos por
  llamada.
• Timeouts de Prosperas: entre 15 y 30 segundos. Si
  no recibimos respuesta a tiempo, reintentamos hasta 3
  veces con backoff.
• Idempotencia obligatoria por tracking ID:
  justamente porque reintentamos, tu API debe ser idempotente por
  tracking ID. Recibir la misma llamada más de una vez no debe
  generar decisiones ni aplicaciones duplicadas. Devolvé el resultado de
  la primera vez.
• Distinguí rechazo de falla técnica: tu API tiene
  que diferenciar un rechazo del Consumer (decisión de
  negocio: no calificó, no cumplió la política de riesgo) de una
  falla técnica (error interno, timeout de un servicio
  downstream). Esta distinción es clave para que Prosperas sepa cuándo
  reintentar y cuándo no.

Cuidado: la
idempotencia va en direcciones opuestas #

Este es el punto que más confunde, así que prestá atención porque las
dos direcciones se comportan al revés:

Dirección	Quién reintenta	¿El receptor es idempotente?	Qué te toca a vos
Prosperas → Lender (decisión / submission)	Prosperas (hasta 3 veces)	Sí — TU API debe serlo, por tracking ID	Deduplicar por tracking ID y devolver el mismo resultado ante reintentos
Lender → Prosperas (postbacks)	Vos (Prosperas NO te reintenta)	No — el endpoint de postbacks no es idempotente	Vos sos dueño de tus reintentos; mantenelos acotados y reintentá solo ante fallas confirmadas, porque un reintento sobre un envío que sí llegó puede crear un evento duplicado

En resumen: cuando Prosperas te llama, la seguridad ante
duplicados es tu responsabilidad (idempotencia por tracking ID). Cuando
vos llamás a Prosperas con un postback, la responsabilidad de no
duplicar también es tuya (reintentos acotados) — pero por un
motivo distinto: el endpoint de postbacks registra cada evento aceptado
y no deduplica. El detalle está en el Sistema de
Postbacks.

Próximos pasos #

• Sistema de Postbacks — cómo notificar a Prosperas
  los cambios de estado usando el tracking ID (y por qué esa dirección no
  es idempotente).
• Requisitos de datos de producto — qué información
  necesitamos sobre tus ofertas para que rendericen bien en el catálogo
  que ve el Consumer.

---

Última verificación: 2026-07-01 · v1.1