Flujo embebido

Para: Lenders (equipo de integración)

¿Sos un Origin?

Esta guía describe cómo un Lender (banco o fintech) conecta su API al flujo embebido. Si lo que querés es embeber el marketplace de Prosperas dentro de tu app (sos un Origin), empezá por el modelo B2B2C y escribí a rclose@prosperas.com para coordinar tu integración.

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