Integración para Origins

Para: Origins (equipo de producto e integración)

Un Origin es la app que tus usuarios ya usan a diario — un operador móvil, una billetera digital, una app de pagos — desde la cual originás el interés en un crédito y lo dirigís hacia Prosperas. Si todavía no ubicás este rol dentro del modelo B2B2C, empezá por ahí: ahí está el vocabulario común (Origin, Consumer, Lender) que usa el resto de esta guía.

Esta página es tu ruta de integración de punta a punta: qué construís vos, cómo embebés la experiencia, cómo lanzás un journey, cómo le pasás contexto del usuario a Prosperas, cómo te enterás de los cambios de estado y qué reporting recibís.

Quién construye qué

La división de trabajo es simple: vos sos el punto de entrada y el contenedor; Prosperas construye y opera toda la experiencia de crédito.

Responsabilidad	Quién la asume
Punto de entrada dentro de tu app (botón, banner, sección de créditos)	Vos (el Origin)
Contenedor de embebido (webview / <web-view> de mini-programa)	Vos (el Origin)
Creación de la sesión desde tu backend	Vos (el Origin)
Pasar contexto del usuario (datos que ya tenés de él)	Vos (el Origin)
Recibir las notificaciones de estado	Vos (el Origin)
Navegación de back/close del contenedor	Vos (el Origin)
La experiencia de crédito completa (web app white-label)	Prosperas
Catálogo de ofertas y conexión con los Lenders	Prosperas
Seguimiento de estado de cada solicitud	Prosperas
Reporting de tu organización	Prosperas

En otras palabras: vos no construís ni mantenés ninguna pantalla de la experiencia de crédito. Abrís un contenedor, le pasás una sesión, y Prosperas se encarga del resto.

Superficies de embebido

Tenés tres formas de embeber la experiencia. Elegí según el punto de contacto con tu usuario:

a) Webview o mini-programa (recomendado)

La forma recomendada y más usada: abrís la experiencia de Prosperas como página de primer nivel dentro de un webview nativo (Android WebView / iOS WKWebView) o del <web-view> de un mini-programa. La experiencia ocupa toda la superficie del contenedor — no es un widget incrustado dentro de otra pantalla tuya.

b) Campaign link / short link

Un link que lleva un utm_id (opcionalmente un short link de Prosperas) abre la experiencia y Prosperas crea la sesión atribuida por su cuenta — no hace falta que tu backend cree nada de antemano. Es útil para superficies donde no controlás un backend en el momento del clic: banners, SMS, push notifications.

Trade-off

Con esta superficie no hay trabajo de backend de tu lado, pero tampoco podés pasar contexto del usuario al abrir — no tenés una sesión propia todavía para asociarle datos antes de que el usuario entre. Ver Lanzar un journey para el detalle de esta alternativa.

c) Iframe

Embeber la experiencia en un <iframe> solo es posible si Prosperas agregó tu origen exacto a un allowlist durante el onboarding. Esto se coordina de antemano — no es una superficie de auto-servicio. Si tu plan es usar iframe, decilo en el checklist de onboarding para que quede acordado antes de integrar.

Lanzar un journey

Lanzar un journey tiene dos pasos: creás una sesión desde tu backend, y después abrís la experiencia en tu contenedor con la referencia que te devolvió esa sesión.

Paso 1 — Creá la sesión desde tu backend

Creá la sesión del lado del servidor

Este paso se hace desde tu backend, no desde el cliente. Guardá la credencial que te provisiona Prosperas en tu backend — no la embebas en código de cliente ni la pongas en una URL. La sesión se crea server-side y solo el reference_number resultante viaja hacia el cliente.

POST {BASE_URL}/client_app/sessions/
x-api-key: <credencial provista por Prosperas>
Content-Type: application/json

// Origin → Prosperas (body ilustrativo)
{
  "org_name": "TuApp",
  "utm_id": "banner-verano-2026",
  "utm_source": "app",
  "utm_medium": "banner",
  "utm_campaign": "verano2026",
  "utm_content": "home-hero",
  "utm_term": "credito-personal",
  "gclid": "Cj0KCQjw_ejemplo_ilustrativo",
  "document_type": "CC",
  "document_number": "1234567890"
}

Campo	Requerido	Notas
org_name	Sí	El nombre de organización que Prosperas te asigna.
utm_id, utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid	Opcional	Atribución de campaña, si la manejás.
document_type, document_number	Opcional	Prefill del documento del usuario, si ya lo tenés.

Esta lista muestra los campos relevantes para un Origin — no es necesariamente exhaustiva.

Respuesta (201):

// Prosperas → Origin (response ilustrativo)
{
  "reference_number": "3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f"
}

La respuesta puede incluir otros campos que Prosperas usa internamente para enrutamiento de campaña — podés ignorarlos. Lo único que necesitás es reference_number.

Errores:

Código	Significado
401	Credencial ausente, con formato inválido, o de una organización inactiva.
400	La organización indicada no existe.
403	org_name no corresponde a tu credencial.

Paso 2 — Abrí la experiencia en tu contenedor

Con el reference_number en mano, abrí la experiencia en tu webview o mini-programa:

{PWA_URL}/?sessionid=3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f

{PWA_URL} es el dominio white-label que Prosperas te aprovisiona, uno por mercado y ambiente.

Una referencia, un journey

Un reference_number identifica un solo journey. Creá una sesión nueva cada vez que un usuario empieza un journey — no reutilices una sesión vieja para un nuevo intento.

Alternativa — landing de campaña sin sesión propia

Si estás usando la superficie de campaign link / short link, no creás la sesión vos: abrís directamente la experiencia con utm_id, sin sessionid, y Prosperas crea la sesión atribuida por su cuenta:

{PWA_URL}/?utm_id=banner-verano-2026&utm_source=app&utm_medium=banner

Prosperas siempre crea una sesión nueva en este flujo — nunca retoma una sesión existente. El utm_id tiene que coincidir con una clave de campaña acordada previamente con Prosperas.

Pasar el contexto del usuario

Si ya conocés datos del usuario antes de que entre a la experiencia de Prosperas (porque ya está logueado en tu app, por ejemplo), podés pasárselos a la sesión que creaste:

POST {BASE_URL}/client_app/user/sessions/3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f/identify
x-api-key: <credencial provista por Prosperas>
Content-Type: application/json

Todos los campos son opcionales, y se agrupan así:

Identidad

Campo	Notas
name, firstname, second_name, fathers_name, mothers_name	Nombre del usuario, según cómo lo tengas segmentado.
document_type, document_number	Tipo y número de documento.
date_of_birth, gender
provider	Identificador de tu app como fuente del dato.

Contacto

Campo	Notas
email
phone

Perfil (financiero y domicilio)

Campo	Notas
monthly_income, income_source	Ingreso mensual y su fuente.
residence_status
street, address_city, address_region

Es información declarada, no identidad verificada

Los datos que enviás acá se tratan como información declarada — un prefill que el usuario todavía puede confirmar o corregir dentro de la experiencia. No es una aserción de identidad verificada.

Modo visitante

Si todavía no tenés datos del usuario, marcá la sesión como visitante:

{ "is_visitor": true }

Responde 200 y no queda ningún usuario asociado a la sesión. Importante: si llamás a identify sin ningún campo de identidad, se trata exactamente igual que el modo visitante — revisá que realmente estés mandando datos si esa es tu intención.

Respuestas

Respuesta	Significado
200 sin body	Los datos se aplicaron.
200 con {"not_applied":[{"field":"document_number","reason":"locked"}]}	Algunos campos no se modificaron porque la identidad del usuario ya está bloqueada (locked). No es un error — no reintentes.
422 con {"errors":[{"field","code","reason"}]}	Error de validación. Ver códigos abajo.

Códigos de error (422):

code	Significado
INVALID_FORMAT	El valor no tiene el formato esperado para ese campo.
TOO_SHORT	El valor es más corto de lo permitido.
TOO_LONG	El valor es más largo de lo permitido.
LOOKS_LIKE_PHONE	Se detectó un número de teléfono en un campo que no es de teléfono.
PLACEHOLDER_VALUE	El valor parece un placeholder (por ejemplo "test" o "N/A") en vez de un dato real.

Ante un 422, corregí el dato y volvé a llamar — no reintentes el mismo payload tal cual.

¿Necesitás reconocer usuarios por tu propio user ID o SSO?

Este endpoint genérico no asigna un identificador propio tuyo al usuario. Si necesitás que Prosperas reconozca usuarios por tu ID interno o mediante el login/SSO de tu app, eso es un adapter a medida que se coordina durante el onboarding — no está disponible a través de este endpoint genérico.

El tracking ID

El reference_number que recibiste al crear la sesión es el tracking ID del journey: nace en ese momento, viaja con la solicitud a lo largo de toda la experiencia y hasta el Lender, y vuelve a vos como click_id en las notificaciones de estado.

Guardalo asociado a tu usuario para poder reconciliar cada notificación con el journey correcto. Para el ciclo de vida completo del identificador, mirá el ciclo de vida del Tracking ID en el Overview.

Si en cambio usaste la alternativa de campaign link / short link, no fuiste vos quien creó la sesión — la crea Prosperas por su cuenta. En ese caso, la primera vez que ves el tracking ID de ese journey es en la primera notificación de estado que te llega.

Notificaciones de estado

Prosperas puede notificar a una URL HTTPS tuya cada vez que un Lender reporta un cambio de estado para un lead de tus usuarios. Esto se configura por evento durante el onboarding: la URL, el método (POST recomendado, o GET), y si querés recibir datos del cliente.

Payload POST (ilustrativo):

{
  "click_id": "3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f",
  "event": "approval",
  "occurred_at": "2026-09-16T14:03:22Z",
  "data": {}
}

Campo	Notas
click_id	El tracking ID — es tu reference_number de la sesión que creaste.
event	El nombre del evento, en minúsculas.
occurred_at	Timestamp ISO-8601, tal como lo reportó el Lender.
data	Detalle que reportó el Lender. El objeto data.client solo aparece si acordaste recibir datos del cliente.

Eventos: application, approval, disbursement, rejected, y los eventos de estado de pago no_payment_yet, on_time, late, default, paid_in_full. El significado de cada uno está documentado en la tabla de Eventos y ciclo de vida y en Actualizaciones de estado de pago de la guía de Postbacks — no lo repetimos acá para no generar dos fuentes de verdad.

Variante GET

Si tu receptor no puede recibir un body, existe una variante GET con los mismos campos como query parameters, salvo que data no se envía:

GET https://tu-dominio.com/tu-endpoint?click_id=3f1c9a52-...&event=approval&occurred_at=2026-09-16T14:03:22Z

Si necesitás el detalle de data, usá POST.

Semántica de entrega

Leé esto antes de implementar el receptor

Comportamiento	Detalle
Timeout	10 segundos.
Reintentos por error de red / timeout	Hasta 3 reintentos, a los ~1, 2 y 4 minutos.
Reintentos ante error HTTP (4xx/5xx)	No hay reintento. Respondé 2xx rápido y procesá de forma asíncrona.
Duplicados	Podés recibir la misma notificación más de una vez — deduplicá por click_id + event + occurred_at. No dedupliques solo por click_id + event: algunos eventos de estado de pago (por ejemplo late) pueden repetirse legítimamente para el mismo journey a medida que pasa el tiempo.
Orden	No está garantizado.

Recomendaciones para tu receptor:

• Usá siempre HTTPS.
• Usá un path difícil de adivinar.
• Si creás las sesiones desde tu backend, validá que el click_id corresponda a una sesión tuya. Las sesiones de links de campaña las crea Prosperas, así que su click_id no lo vas a conocer de antemano.

Requisitos del contenedor

Tu contenedor (webview o <web-view> de mini-programa) tiene que cumplir con un piso mínimo:

Requisito	Detalle
Motor mínimo	Chrome / Android WebView 88+, Safari / iOS WKWebView 14+
JavaScript, cookies y local storage	Habilitados
Cámara / carga de archivos	Habilitalos si podés — algunos Lenders pueden pedir captura de documentos.
Links externos	Permití que se abran los sitios de los Lenders, según lo que tu contenedor soporte.
Navegación de back/close	La experiencia no envía ninguna señal de “volver a la app”. El botón de back/close es responsabilidad de tu contenedor.

Ambientes

Igual que para los Lenders, Prosperas opera ambientes separados por mercado. En la documentación vas a ver {BASE_URL} (la API) y {PWA_URL} (tu experiencia white-label) — los valores reales te los entregamos durante el aprovisionamiento.

Nota

Estos valores son un ejemplo ilustrativo, NO son hostnames reales. Sirven solo para ver la forma que tienen.

Mercado	Desarrollo (ejemplo ilustrativo)	Producción (ejemplo ilustrativo)
Colombia (CO)	https://api.dev.co.prosperas.com	https://api.co.prosperas.com
México (MX)	https://api.dev.mx.prosperas.com	https://api.mx.prosperas.com

Ambiente	Uso
Desarrollo	Ambiente de pre-producción: para integrar y probar tu flujo antes de salir a producción.
Producción	Tráfico real de tus usuarios.

Desarrollo = staging

Es el mismo tipo de ambiente de pre-producción que la página de Onboarding — pensada para Lenders — llama “staging”. Un solo ambiente, dos nombres según la audiencia.

Las credenciales son distintas por ambiente — no mezcles la credencial de desarrollo con la de producción, ni viceversa.

Reporting

Tu equipo recibe acceso al portal de Prosperas, con un dashboard de resumen limitado a tu organización. Ahí vas a poder ver:

• Sesiones y visitantes únicos.
• Journeys iniciados y cuántos llegan a ver el catálogo de ofertas.
• Leads y su estado (pendiente, en solicitud, aprobado, rechazado, desembolsado).
• Tasas de aprobación y rechazo.
• Filtros por fecha y por UTM.

El detalle de conversión por Lender/producto puede habilitarse según lo que hayas acordado con Prosperas.

Checklist de onboarding

Lo que nos compartís

• Superficie de embebido que vas a usar (webview / mini-programa / iframe) — si es iframe, el origen exacto que hay que allowlistear.
• Mercado(s) donde vas a operar.
• Qué datos de usuario podés compartir y de qué fuente vienen.
• Las claves de UTM/campaña que va a enviar tu app.
• URLs de notificación por evento, el método (POST/GET), y si aceptás recibir datos del cliente.
• Dominios de destino, si vas a usar short links.
• Contacto técnico y contacto de negocio.

Lo que te entregamos

• Nombre de organización y credencial por ambiente, entregada de forma segura fuera de banda.
• {BASE_URL} por ambiente y mercado.
• Tu {PWA_URL} white-label.
• Acceso al portal para tu equipo.
• Claves de campaña / short links, si aplica.
• Confirmación de la configuración de notificaciones.

Para empezar

Escribí a rclose@prosperas.com con esta información para arrancar el onboarding.

Próximos pasos

• ¿Qué es Prosperas? — el modelo B2B2C completo y el ciclo de vida del tracking ID.
• Onboarding de partners — cómo conseguir tus credenciales y ambientes.
• Postbacks de estado — el significado completo de cada evento de estado.
• Dudas sobre tu integración: rclose@prosperas.com.

---

Última verificación: 2026-09-16 · v1.0