Sistema de postback

🇺🇸 Read this in English →

Resumen #

Cuando un consumidor solicita uno de tus productos a través de
Prosperas, vos procesás esa solicitud de tu lado (la aprobás,
desembolsás los fondos o la rechazás). Un postback es
la forma en que le contás a Prosperas qué pasó, casi en tiempo real,
para que podamos actualizar el estado del lead, conciliar el revenue y
mantener sincronizada la experiencia del consumidor.

La integración es deliberadamente chica: un endpoint, una
credencial, un formato de payload.

{BASE_URL} es la URL base de Prosperas para tu mercado
(Colombia / México). Prosperas te va a dar las URLs exactas de staging y
producción durante el onboarding.

Autenticación #

Todo postback tiene que autenticarse. Prosperas revisa primero la
API key, y después la IP de origen. Si
ninguna de las dos coincide con una credencial registrada, la solicitud
se rechaza con 403.

API key (recomendado) #

Enviá tu key en el header HTTP:

X-API-KEY: <tu-key>

• El nombre del header no distingue
  mayúsculas/minúsculas (X-API-KEY,
  x-api-key, X-Api-Key funcionan igual).
• La key se valida por coincidencia exacta de string.
  Sin prefijo, sin Bearer, sin encoding.

IP allowlist (alternativa) #

Si te provisionaron por IP, no hace falta ningún header — leemos tu
IP de origen desde X-Forwarded-For, después
X-Real-IP, y por último el socket peer.

• La coincidencia es por string exacto contra la IP
  que registramos.
• No soportamos rangos CIDR / subnets. Cada IP de
  salida individual que uses tiene que estar registrada. Si tu
  infraestructura rota IPs, usá el método de API key en su lugar.

La regla del “el lead
tiene que existir” #

La autenticación no depende solo de la credencial — también está
atada a un lead real. Una solicitud es exitosa solo cuando se cumplen
todas estas condiciones:

1. Tu credencial (key o IP) coincide con un origen de lender
   registrado, y
2. el click_id de la solicitud resuelve a un lead,
   y
3. ese lead pertenece a un producto que es de tu
   cuenta de lender.

Si tu credencial es válida pero el click_id no resuelve
a uno de tus leads, igual vas a recibir
403 (no 404). En la práctica
esto significa: un click_id incorrecto, desconocido
o ajeno devuelve 403.

Nota de seguridad: este endpoint no tiene firma
HMAC. Protegé tu API key como cualquier otro secreto: guardala en un
secrets manager, nunca la commitees, nunca la envíes en texto plano, y
pedile a Prosperas que la rote si alguna vez quedó expuesta.

El identificador de
tracking (click_id) #

click_id es el identificador único que conecta el
journey del consumidor entre Prosperas y tus sistemas.

• Prosperas lo genera y te lo entrega en el momento en que redirige al
  consumidor hacia vos (como identificador de tracking/click en la URL de
  handoff).
• Tenés que guardarlo y devolverlo exactamente igual
  en cada postback de esa solicitud.
• No contiene datos personales; es una referencia opaca.

Formatos aceptados:

Más de un guion bajo, o un UUID que no se pueda parsear, devuelve
400.

Contrato de la solicitud #

Método: POST (recomendado). Existe una
variante GET con los mismos campos como query parameters,
pero POST con body JSON es el método server-to-server soportado.

Headers:

Content-Type: application/json
X-API-KEY: <tu-key>

Body (JSON, snake_case):

{
  "click_id": "claro_7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
  "event": "approval",
  "occurred_at": "2026-07-01T12:34:56Z",
  "data": {
    "provider": "tu-marca",
    "client": {
      "email": "consumidor@example.com",
      "fullName": "Ana Gomez",
      "firstName": "Ana",
      "lastName": "Gomez",
      "idNumber": "1234567890",
      "phoneNumber": "3001234567",
      "returningCustomer": false
    }
  }
}

Referencia de campos #

El objeto
data.client (opcional) #

data.client te permite enriquecer el registro del
consumidor. Todos los campos son opcionales.

Importante — nunca sobrescribimos datos que ya ingresó el
consumidor. data.client solo completa campos que
están actualmente vacíos en el registro del consumidor.
Cualquier dato que el consumidor ya haya provisto en el flujo de
Prosperas prevalece. Esto protege la información que el consumidor
ingresó explícitamente.

Cuidado — returningCustomer no es
persistente. Si omitís returningCustomer en un
postback, se trata como false. Si dependés de este flag,
enviálo explícitamente en cada postback donde deba ser
true.

Eventos y ciclo de vida #

Enviá un postback por cada transición de estado, usando el evento que
corresponda a lo que pasó:

application se acepta pero es opcional — enviálo si
tenés un hito significativo de “solicitud recibida”; si no, los tres
resultados terminales (approval, disbursement,
rejected) son lo que más importa.

Enviá los eventos en el orden en que ocurren.
Prosperas tolera eventos que llegan desordenados, pero la entrega en
orden mantiene limpio el historial del lead.

Respuestas y códigos de
estado #

Body de éxito (200 OK):

{
  "ok": true,
  "lead_id": 12345,
  "status": "APPROVAL",
  "user_id": 6789
}

• ok — siempre true en caso de éxito.
• lead_id — el lead de Prosperas contra el cual se
  registró el evento.
• status — el estado interno al que mapeó tu evento
  (APPLICATION / APPROVAL /
  DISBURSEMENT / REJECTED).
• user_id — el id del registro del consumidor, cuando
  está disponible.

Códigos de estado:

Errores comunes (leé
esto antes de integrar) #

Estos cuatro errores explican casi todas las integraciones fallidas
en su primer intento. Evitalos:

Reintentos y garantías de
entrega #

• Los reintentos son tu responsabilidad. Prosperas no
  te reintenta. Ante un 5xx o un error de red, reintentá el
  postback con backoff exponencial (ej. 1s, 2s, 4s, 8s…),
  hasta un límite razonable.
• No reintentes ante 4xx. Un
  400, 403 o 422 significa que la
  solicitud está mal — corregila y enviá una solicitud corregida en lugar
  de insistir con el mismo payload.
• El endpoint no es idempotente. Cada postback
  aceptado registra un evento nuevo. Si reintentás después de una
  solicitud que en realidad tuvo éxito (pero cuya respuesta no recibiste),
  podés generar un evento duplicado. Mantené los reintentos acotados y
  priorizá reintentar solo ante fallas confirmadas.
• Cada solicitud queda registrada de nuestro lado
  (con tu API key enmascarada) para soporte y conciliación.

Ejemplos prácticos #

Caso exitoso — aprobación
(POST) #

curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <tu-key>" \
  -d '{
    "click_id": "claro_7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
    "event": "approval",
    "occurred_at": "2026-07-01T12:34:56Z",
    "data": { "provider": "tu-marca" }
  }'

Respuesta — 200 OK:

{ "ok": true, "lead_id": 12345, "status": "APPROVAL", "user_id": 6789 }

Desembolso
con enriquecimiento de datos del consumidor (POST) #

curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <tu-key>" \
  -d '{
    "click_id": "7e1c2f1f-9b4d-4c1d-9f6c-2f3c1a2b4d5e",
    "event": "disbursement",
    "occurred_at": "2026-07-01T15:00:00Z",
    "data": {
      "provider": "tu-marca",
      "client": { "fullName": "Ana Gomez", "idNumber": "1234567890" }
    }
  }'

Error — campo en camelCase
(422) #

# INCORRECTO: "clickId" (camelCase) en lugar de "click_id"
curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: <tu-key>" \
  -d '{ "clickId": "7e1c2f1f-...", "event": "approval" }'
# → 422 Unprocessable Entity (el campo "click_id" es requerido)

Error — credencial
faltante o incorrecta (403) #

# Sin header X-API-KEY y con una IP que no está en la allowlist → 403
curl -X POST "{BASE_URL}/client_app/webhook/lender/loan-status" \
  -H "Content-Type: application/json" \
  -d '{ "click_id": "7e1c2f1f-...", "event": "approval" }'
# → 403 Forbidden

Referencia rápida #

Notas importantes #

Casing: los campos de nivel superior son snake_case (click_id, occurred_at). El objeto anidado data.client usa camelCase (fullName, idNumber, returningCustomer) — es intencional, no un error.

Respuesta: enviás event en minúscula (approval); la respuesta te devuelve status en MAYÚSCULA (APPROVAL). Es lo esperado.

Idempotencia y reintentos: el endpoint no es idempotente y Prosperas no te reintenta. Si un timeout te deja sin respuesta después de que registramos el evento, un reintento crea un evento duplicado. Recomendación: reintentá solo ante 5xx o errores de red, con backoff exponencial (1s, 2s, 4s…, máx. 3 intentos), y deduplicá de tu lado por click_id + event + occurred_at. (Ojo: tu API de decisión/submission del Flujo embebido SÍ debe ser idempotente por tracking ID — esa dirección la reintentamos nosotros.)

Última verificación: 2026-07-01 · v1.1 · coincide con
Lender-Postback-Integration-Guide.md