# API de integración para cobranzas Este módulo agrega operaciones de solo lectura para la futura gestión de cobranzas. No modifica ni reutiliza los contratos de los endpoints legacy de `PHANTOMAPI`. Durante las pruebas contra la instalación productiva del cliente solo están autorizadas consultas. No deben agregarse a este router acciones de escritura en Phantom ni operaciones que contacten clientes reales. `Consulta_Masiva_Datos` utiliza HTTP `POST` por contrato de Phantom, pero sigue siendo una operación exclusivamente consultiva. ## Endpoints ### `GET /cobranzas/cartera` Consulta paginada sobre `Consulta_Masiva_Datos` con `BalanceCC=1` y `CompAdeudados=1`. Parámetros: - `estado`: opcional; `Activo`, `Suspendido` o `Baja`. - `idDesde`: opcional; por defecto `1`. - `idHasta`: opcional; por defecto `999999999`. - `limit`: opcional; por defecto `100`, máximo `1000`. - `offset`: opcional; por defecto `0`. Ejemplo: ```text GET /cobranzas/cartera?estado=Suspendido&limit=100&offset=0 ``` ### `GET /cobranzas/clientes/:ida/detalle` Consulta `Consulta_Cliente_Avanzada` directamente por IDA. Normaliza cuenta, servicio, conexión, productos, promesa activa, medio de pago preferido y conexiones asociadas. `MedioPagoPreferido` se expone como `medioPago`; sus valores `SDC` y `SDT` identifican la adhesión a débito automático. Las credenciales de autogestión no forman parte de la respuesta normalizada. ### `GET /cobranzas/clientes/:ida/comprobantes-impagos` Consulta `Phantom_Ultima_Factura` con `JSON=1` y `SoloImpagas=1`. Parámetros: - `limit`: opcional; por defecto `20`, máximo `100`. - `offset`: opcional; por defecto `0`. Una respuesta de Phantom indicando que no existen facturas se normaliza como una colección vacía. ## Hallazgos en la instalación local Verificados el 5 de agosto de 2026 con muestras anonimizadas: - La consulta masiva devuelve `Balance_CC`, `C_Comprobantes_Adeudados`, `Estado`, ciudad y datos de contacto. - La cartera activa supera los 1000 registros, por lo que la sincronización deberá recorrer páginas hasta que `hayMas` sea falso. - Al 5 de agosto de 2026 la consulta masiva todavía no devolvía medio de pago. El 10 de agosto de 2026 se verificó que Phantom incorporó `MedioPago`: devuelve `SDT`, `SDC` o cadena vacía. El normalizador expone el valor como `medioPago` y señala la presencia del campo mediante `medioPagoDisponible`. - La consulta avanzada devuelve estado de servicio, estado de conexión, promesa activa, tecnología, productos y conexiones asociadas. - La consulta avanzada sigue devolviendo el medio de pago en `MedioPagoPreferido`, pero ya no es necesaria para clasificar la cartera mientras la consulta masiva incluya `MedioPago`. - Se contrastó un cliente activo conocido contra `Consultar_Preventas`. La instalación no admite todavía el filtro `DocPreventa` documentado en la wiki actual. La búsqueda compatible por rangos de ID (1-20000) y por fechas (2015-2026) no encontró una preventa para ese cliente, aunque sí existe en la cartera real. Preventas no puede asumirse como una fuente relacionada uno a uno con clientes activos. - Las facturas impagas incluyen período, importe, primer y segundo vencimiento, hash de descarga y datos SIRO. - Se inspeccionaron 224 facturas impagas de 167 clientes (120 activos y 47 suspendidos). Ninguna incluyó una clave de medio de pago ni valores `SDC`/`SDT`. Los campos observados fueron `Comp_ID`, `Detalle`, `Estado`, `Hash_Descarga`, `IDT`, `Periodo`, `Primer_Vto`, `Segundo_Vto`, `Tipo`, `Total`, `URL_PAGO`, `RLink_CE`, `SIRO_CB_CR`, `SIRO_CE` y `SIRO_QR`. - `URL_PAGO` está presente sólo en algunos comprobantes. - La documentación de Pasarelas indica que `SDC`/`SDT` bloquean QR, código de barras y botones de pago antes del primer vencimiento, y que el PDF muestra una leyenda de adhesión. En una muestra de 119 facturas todavía no vencidas, 43 presentaron el patrón sin URL/QR/código de barras pero con `SIRO_CE`; sin un cliente confirmado como adherido no puede asumirse que ese patrón sea exclusivo. El PDF de un cliente de control permitió extraer texto, pero no contenía una leyenda de débito automático ni códigos `SDC`/`SDT`. - Se validaron luego tres clientes confirmados externamente: uno `SDT`, uno `SDC` y uno sin débito. Los PDFs de `SDT` y `SDC` contienen texto extraíble con la leyenda `Su cuenta se encuentra adherida al...`; el PDF sin débito no contiene ninguna leyenda de adhesión. El texto no diferencia `SDC` de `SDT`, pero permite identificar de forma binaria la adhesión. En la factura impaga futura, el cliente `SDC` no tenía QR ni código de barras, mientras que el control sin débito sí tenía ambos. El cliente `SDT` ya tenía la factura pagada, por lo que sus campos de pago no sirven como señal de clasificación. - `SoloImpagas=1` puede incluir comprobantes todavía no vencidos. El vencimiento debe calcularse comparando `Primer_Vto` con la fecha efectiva del proceso. - La cantidad de comprobantes de la cuenta puede no coincidir con la cantidad de comprobantes devuelta para una conexión. El diseño debe contemplar cuenta raíz y conexiones asociadas. ## Diagnóstico temporal de respuesta cruda Disponible únicamente desde la propia máquina mientras se inspecciona el contrato de Phantom: ```text GET /cobranzas/diagnostico/consulta-masiva-raw?idDesde=1006311&idHasta=1006311&limit=1 ``` Devuelve directamente el payload de `Consulta_Masiva_Datos`, sin wrapper ni normalización. La ruta debe eliminarse una vez finalizado el diagnóstico de `MedioPagoPreferido`. ## Pruebas ```text npm test ``` Las pruebas usan clientes simulados y no acceden a Phantom.