Contratos BFF · payloads de las vistas

Cuerpos JSON de Solventa para lo que cada pantalla muestra. No es OpenAPI, no fija el path ni el verbo, y no es el esquema del banco, de la pasarela ni del proveedor de push. El stub sigue siendo ok / fallo / lento.

Cada bloque es el slice de Backlog BFF · Web / Móvil y back-office. La historia de la vista no se repite aquí.

La huella o el rostro no viajan en ningún cuerpo: el dispositivo desbloquea la sesión de HU-121.

HU-121 · Sesión móvil

{
  "correo": "[email protected]",
  "contrasena": "********"
}

{
  "accessToken": "jwt",
  "refreshToken": "jwt",
  "expiraEn": 900
}

POST de refresh manda solo refreshToken. Logout no lleva cuerpo.

HU-122 · Sesión web

Mismos tokens que HU-121. El cuerpo de entrada agrega el rol de escritorio.

{
  "correo": "[email protected]",
  "contrasena": "********",
  "rol": "asesor"
}

rol es cliente, asesor u operador.

HU-123 · Alta móvil y prueba de vida

La selfie se queda en el teléfono. El BFF guarda el resultado simulado.

{
  "nombre": "Camila",
  "apellidos": "Restrepo",
  "documento": "1012345678",
  "correo": "[email protected]",
  "pruebaDeVida": "ok",
  "habeasData": true
}

pruebaDeVida es ok o no. Revocar consentimiento:

{ "habeasData": false }

HU-124 · Alta web

Igual que HU-123, sin pruebaDeVida y sin cámara.

{
  "nombre": "Camila",
  "apellidos": "Restrepo",
  "documento": "1012345678",
  "correo": "[email protected]",
  "habeasData": true
}

HU-125 · Oferta móvil

{
  "ramo": "Protección de dispositivo",
  "datosRiesgo": {
    "valorDispositivo": 2400000,
    "marca": "Pixel",
    "masDe12Meses": false
  }
}

datosRiesgo cambia con el ramo (viaje: destino y duración; vida: suma y edad; clima: evento y umbral; pagos: cuota o crédito). La respuesta es la oferta en firme:

{
  "cotizacionId": "COT-1042",
  "ramo": "Protección de dispositivo",
  "estado": "oferta_vigente",
  "prima": 89000,
  "moneda": "COP",
  "venceEn": "2026-10-01"
}

Reconsultar manda solo cotizacionId y devuelve el mismo cuerpo.

HU-126 · Oferta web

Mismo par que HU-125. En venta asistida se agrega el cliente de la cartera:

{
  "clienteId": "CLI-18",
  "ramo": "Protección de dispositivo",
  "datosRiesgo": { "valorDispositivo": 2400000, "marca": "Pixel", "masDe12Meses": false }
}

HU-127 · Aceptar, emitir y billetera

{ "cotizacionId": "COT-1042" }

Éxito:

{
  "numero": "POL-88219-CO",
  "ramo": "Protección de dispositivo",
  "estado": "vigente",
  "venceEn": "2027-03-12"
}

Rechazo:

{ "estado": "rechazada", "motivo": "Valor del equipo fuera de rango" }

La billetera, online y al volver la red, es la misma lista. La app la cachea; no hay otro cuerpo para el modo offline.

{
  "polizas": [
    {
      "numero": "POL-88219-CO",
      "ramo": "Protección de dispositivo",
      "resumen": "Robo, Pantalla, Hurto",
      "estado": "vigente",
      "venceEn": "2027-03-12"
    }
  ]
}

El detalle de una póliza repite ese objeto y suma la recomendación de siniestro del ramo:

{
  "numero": "POL-88219-CO",
  "ramo": "Protección de dispositivo",
  "resumen": "Robo y Pantalla",
  "estado": "vigente",
  "venceEn": "2027-03-12",
  "queHacer": "Toma la foto del daño y anota fecha y lugar."
}

HU-128 · Emitir y consultar en web

Mismos cuerpos que HU-127, para el cliente y para el asesor.

HU-129 · Aviso, evidencia y estado

Un solo upload: foto, video, recibo o daño, y el soporte recortado. Si el usuario niega la ubicación, geo es null y el aviso sigue.

{
  "poliza": "POL-88219-CO",
  "fechaHecho": "2026-03-12",
  "geo": { "lat": 4.6533, "lng": -74.0836, "precisionM": 12 },
  "adjuntos": [
    { "tipo": "foto", "nombre": "dano.jpg" },
    { "tipo": "video", "nombre": "dano.mp4" },
    { "tipo": "recibo", "nombre": "recibo.jpg" },
    { "tipo": "soporte", "nombre": "acta.jpg" }
  ]
}

{ "siniestroId": "SIN-441", "estado": "recibido" }

Lista y detalle:

{
  "siniestros": [
    {
      "siniestroId": "SIN-441",
      "ramo": "Protección de dispositivo",
      "resumen": "Pantalla rota",
      "estado": "en_evaluacion"
    }
  ]
}

estado es recibido, en_evaluacion, decidido, enrutado o pagado.

HU-130 · Cola del operador

El cliente web reutiliza HU-129. La cola del operador:

{
  "avisos": [
    {
      "siniestroId": "SIN-441",
      "poliza": "POL-88219-CO",
      "ramo": "Protección de dispositivo",
      "estado": "en_evaluacion"
    }
  ]
}

Decisión:

{ "siniestroId": "SIN-441", "decision": "rechazar", "motivo": "Falta el recibo" }

decision es aprobar o rechazar. Sin motivo, el rechazo no se acepta.

HU-131 · Pago automático

{
  "siniestroId": "SIN-220",
  "poliza": "POL-11002-CO",
  "umbral": "retraso mayor a 120 min",
  "monto": 250000,
  "moneda": "COP",
  "estado": "pagado"
}

HU-132 · Trazabilidad web del pago automático

El mismo cuerpo de HU-131, para el cliente de escritorio y para el operador.

HU-133 · Oferta hipotecaria móvil

{
  "credito": { "valor": 180000000, "plazoMeses": 180 },
  "consentimientoPerfil": true
}

{
  "ramo": "Vida crediticia",
  "estado": "oferta_vigente",
  "prima": 64000,
  "moneda": "COP",
  "factores": ["plazo", "valor del crédito"],
  "degradada": false
}

Si el perfilamiento stub no llega a tiempo, degradada es true y la prima es el valor de respaldo.

HU-134 · Oferta hipotecaria web

El mismo cuerpo de HU-133, para el cliente y para el asesor.

HU-135 · Avisos in-app de vigencia

No lleva token de push. Eso es HU-142.

{
  "avisos": [
    { "tipo": "vencimiento", "poliza": "POL-88219-CO", "venceEn": "2027-03-12" },
    { "tipo": "renovacion", "poliza": "POL-88219-CO", "estado": "vigente" }
  ]
}

HU-136 · Renovar, modificar, cancelar

{ "numero": "POL-88219-CO", "verbo": "renovar" }

verbo es renovar, modificar o cancelar. Cancelar exige motivo:

{ "numero": "POL-88219-CO", "verbo": "cancelar", "motivo": "El cliente lo pidió" }

La respuesta es el objeto de póliza de HU-127 con el estado nuevo.

HU-137 · Inicio móvil

Un solo agregado. Cada bloque trae ramo, estado y el siguiente paso.

{
  "ofertaVigente": {
    "cotizacionId": "COT-1042",
    "ramo": "Protección de dispositivo",
    "estado": "oferta_vigente"
  },
  "poliza": {
    "numero": "POL-88219-CO",
    "ramo": "Protección de dispositivo",
    "estado": "vigente"
  },
  "siniestroEnCurso": {
    "siniestroId": "SIN-441",
    "estado": "en_evaluacion"
  },
  "hipotecario": null
}

HU-138 · Inicio web

El mismo agregado de HU-137, con el payload de escritorio (tablas, no cards de 390).

HU-139 · Cartera del asesor

{
  "kpis": { "cotizaciones": 12, "polizas": 40 },
  "cola": [
    { "id": "COT-1042", "tipo": "cotizacion", "ramo": "Protección de dispositivo", "estado": "en_revision" },
    { "id": "POL-88219-CO", "tipo": "poliza", "ramo": "Protección de dispositivo", "estado": "vigente" }
  ]
}

HU-140 · Ficha de clientes

{
  "clientes": [
    {
      "clienteId": "CLI-18",
      "nombre": "Camila Restrepo",
      "documento": "1012345678",
      "correo": "[email protected]",
      "habeasData": true,
      "estado": "activo"
    }
  ]
}

Alta y edición usan ese objeto sin clienteId. Desactivar:

{ "clienteId": "CLI-18", "estado": "inactivo" }

HU-141 es la pantalla de esa ficha, no un contrato.

HU-142 · Token y avisos push

La bandeja es del sistema. El BFF registra el token y nombra la pantalla que se abre.

{ "token": "fcm-stub", "plataforma": "android" }

{
  "tipo": "vencimiento",
  "titulo": "Tu póliza vence",
  "cuerpo": "En 7 días",
  "destino": "aviso-vencimiento",
  "poliza": "POL-88219-CO"
}

tipo es pago_automatico, vencimiento, renovacion o estado_siniestro. destino es parametrico, aviso-vencimiento, aviso-renovacion o detalle-siniestro. El proveedor de push es un stub.

HU-143 · Prestadores y asistencia

{
  "prestadores": [
    { "id": "PR-1", "nombre": "Taller Norte", "distanciaKm": 1.2, "zona": "Chapinero" },
    { "id": "PR-2", "nombre": "Taller Sur", "distanciaKm": 3.4, "zona": "Kennedy" }
  ]
}

{
  "prestadorId": "PR-1",
  "geo": { "lat": 4.6533, "lng": -74.0836 },
  "poliza": "POL-88219-CO"
}

{ "asistenciaId": "AS-18", "estado": "registrada" }

Operaciones lee { "asistenciaId", "prestadorId", "poliza", "estado" }. No entra en la cola de HU-130.