API PCC

Esta API reenvía a PCC (PowerCurve Collections, vía Experian) el payload de cada actividad de gestión de la cartera BBVA (IF_INB01-04), registrando cada consumo y reintentando automáticamente los que fallan. No consulta datos de clientes ni de gestiones en ninguna base de datos: quien la llama ya los maneja externamente y los manda completos en el body de cada request.

Documentación

• docs/INSTALACION.md — requisitos, configuración de .env, esquema de BD esperado y puesta en marcha.
• docs/CONSUMO.md — guía de uso de cada endpoint, ejemplos curl, manejo de errores y códigos de negocio.
• Swagger UI: http://127.0.0.1:4500/docs con el servidor corriendo (ReDoc en /redoc, spec crudo en /openapi.json). Copia estática del spec en docs/openapi.json.
• insumos/ — especificaciones técnicas originales de BBVA/Experian que esta API implementa (Access Token Integration, IF_INB01-04).

Modos de Uso

El sistema puede consumirse desde CLI o través de API

Por CLI

Modo CLI (--endpoint-cli): permite ejecutar un servicio puntual directamente desde la terminal sin levantar el servidor completo. Para los 10 endpoints de actividad, pide cada campo del payload por input() (ver docs/CONSUMO.md para el detalle de cada campo).

python main.py --endpoint-cli salud-financiera --cartera bbva

Opciones

Opciones (choices): Se restringieron las entradas permitidas a los siguientes servicios específicos:

token: Obtención de credenciales de acceso.
resultado-contacto: Registro de resultado de gestión (IF_INB01).
salud-financiera: Evaluación de estado crediticio (IF_INB02).
cierre-contacto: Finalización de proceso de contacto (IF_INB03).
diagnostico-incumplimiento: Registro del motivo de no pago (IF_INB04).
rellamada-dia: Registro de rellamada para el día (IF_INB04).
visita: Registro de captura de visita (IF_INB04).
insolvencia-reportada-particular: Cliente particular reporta insolvencia (IF_INB04 v1.2, sin body).
insolvencia-reportada-pymes: Cliente Pymes reporta insolvencia (IF_INB04 v1.2, sin body).
seguro-desempleo-reportado: Cliente reporta desempleo (IF_INB04 v1.2, sin body).
seguro-fallecimiento-reportado: Se reporta fallecimiento del cliente (IF_INB04 v1.2, sin body).
reintentar-pendientes: Reintenta de inmediato los consumos fallidos guardados en tbl_documentacion_pcc_pendientes.

--cartera (opcional, default bbva): qué base de datos usar para el registro de consumos/reintentos -- mismo concepto que el path param {cartera} del modo API (ver docs/INSTALACION.md).

Por API

Modo Servidor: Se mantiene la funcionalidad de uvicorn en el puerto 4500, permitiendo que los mismos servicios estén disponibles vía HTTP a través de FastAPI.

Iniciar Servidor API

python main.py --serve

Endpoints de la API (FastAPI)

Todos los endpoints tienen el prefijo base /v1/pcc (auth/token, un
endpoint por actividad IF_INB01-04, y el reintento manual
/reintentos/ejecutar). Salvo auth/token, todos reciben un path param,
{cartera} (qué base de datos usar para el registro de consumos/
reintentos -- ver docs/INSTALACION.md):
POST /v1/pcc/{cartera}/resultado-contacto, etc. El resto de los datos
van en el body JSON, incluida obligacion. Ver el detalle de cada uno,
con ejemplos de request/response, en docs/CONSUMO.md
o en el Swagger UI (/docs). GET /health (sin prefijo /v1/pcc) da
un liveness check simple del proceso.

Reintentos de consumos fallidos

Todo consumo NO exitoso de un endpoint de actividad queda registrado en
tbl_documentacion_pcc_pendientes y se reintenta automáticamente hasta 3
veces (30s, 2min, 5min), además de poder reintentarse manualmente
(POST /v1/pcc/{cartera}/reintentos/ejecutar o --endpoint-cli reintentar-pendientes --cartera <cartera>).
Cada consumo (éxito, fallo o reintento) queda además auditado en
tbl_log_documentacion_pcc. Ver el detalle completo, incluido el script
para crear ambas tablas, en
docs/CONSUMO.md y
docs/sql/tbl_documentacion_pcc.sql.

Validación de códigos

Los campos resultado, canal, accion y motivo_no_pago se validan contra las tablas de códigos oficiales definidas en las especificaciones técnicas (services/experian_codes.py) antes de llamar a PCC. Si un código no es válido, la API responde HTTP 400 de inmediato en vez de descubrirlo en la respuesta de PCC. Si falta un campo obligatorio del body, responde 422 (validación de Pydantic) sin llegar a llamar a PCC.

Desde IF_INB04 v1.2, los códigos numéricos (resultado, accion, motivo_no_pago) usan 4 dígitos con ceros a la izquierda (ej. "0110", "0411"); motivo_no_pago antes era texto libre sin validar.

Las precondiciones de negocio descritas en IF_INB04 (ej. Salud Financiera solo aplica si el contrato está en fase preventiva y el Resultado Contacto fue exitoso) no se validan del lado de esta API — se asume que PCC las valida server-side y devuelve el error correspondiente, el cual queda registrado en los logs de error.

Logging y monitoreo

Toda la actividad de la aplicación queda registrada en logs/, con rotación diaria y 7 días de respaldo:

Las credenciales (PASSWORD, DATABASE_BBVA_PASSWORD y equivalentes por cartera, etc.) nunca se escriben en texto plano en los logs; solo se reporta si están configuradas o no.