+
+
+
+ Objetivo del sistema
+
+
+ Sistema web de integración de datos clínicos para el Laboratorio Clínico Ximena Caicedo, que permite el intercambio de información de ventas y recepciones (RDA) con el sistema TNS (Tecnología de Negocios en Salud), de manera estructurada, segura y trazable.
+
+
+ Centraliza la gestión de contratos, el envío de facturas de venta, la generación de RDA de pacientes, la sincronización con WhatsApp ERP y el registro completo de toda la actividad del sistema.
+
+
+
+
Firebird
Base de datos clínica
+
+
+
+
+
+ Arquitectura técnica
+
+
+
+
Stack tecnológico
+
+ | Componente | Tecnología |
|---|
+
+ | Backend | Python 3 + FastAPI (async) |
+ | Frontend | Jinja2 + TailwindCSS + Font Awesome |
+ | BD local | SQLite 3 (WAL mode) |
+ | BD clínica | Firebird 2.5 — 192.168.0.125:3025 |
+ | API externa | TNS — REST JSON + Bearer Token |
+ | Servidor | Windows — uvicorn :8080 |
+ | Auth | JWT + bcrypt |
+
+
+
+
+
Flujo de datos
+
+ {% for step in [
+ ('1','Navegador','Usuario accede y se autentica con JWT.','blue'),
+ ('2','Firebird','Sistema consulta recepciones/facturas.','green'),
+ ('3','Generador','Se construye el JSON según spec TNS.','purple'),
+ ('4','TNS API','POST con Bearer Token al endpoint.','orange'),
+ ('5','SQLite','Respuesta guardada (success/error).','gray'),
+ ('6','Historial','Registro disponible para reenvío.','blue'),
+ ] %}
+ -
+ {{ step[0] }}
+
{{ step[1] }}: {{ step[2] }}
+
+ {% endfor %}
+
+
+
+
+
+
+ Acceso y credenciales
+
+
+
+
+
URL del sistema (red local)
+
http://192.168.0.125:8080
+
+
+
+
Credenciales iniciales
+
+ | Campo | Valor |
|---|
+
+ | Usuario | admin |
+ | Contraseña | admin123 |
+
+
+
+
+
Importante
+
Cambiar la contraseña al primer ingreso. Menú usuario → Cambiar contraseña.
+
Nuevos usuarios: acceder a /register con sesión activa.
+
+
+
+
+
+ Dashboard — Panel principal
+
+ /dashboard — Pantalla de inicio. Resumen en tiempo real del estado del sistema.
+
+ - Total de envíos exitosos acumulados (todos los tipos).
+ - Total de envíos con error.
+ - Conteo de terceros registrados en TNS.
+ - Conteo de transacciones RDA enviadas.
+ - Número de facturas únicas procesadas.
+ - Últimos 10 envíos con usuario, tipo, factura y estado.
+
+
+
+
+
+ Configuración
+
+ /config — Parámetros de conexión y credenciales del sistema.
+
+ | Parámetro | Descripción |
|---|
+
+ {% for row in [
+ ('firebird_host','IP del servidor Firebird (ej: 192.168.0.125)'),
+ ('firebird_port','Puerto Firebird (ej: 3025)'),
+ ('firebird_database','Ruta completa del archivo .FDB en el servidor'),
+ ('firebird_user / password','Credenciales de acceso a Firebird (SYSDBA / masterkey)'),
+ ('tns_empresa','NIT de la empresa en TNS'),
+ ('tns_usuario / password','Credenciales de acceso a la API TNS'),
+ ('api_sucursal','Código de sucursal para los endpoints TNS (ej: 81080)'),
+ ('prefijo_tns_default','Prefijo por defecto para facturas (ej: 00)'),
+ ('num_documento_obligado','NIT del obligado para RIPS'),
+ ('profesional_default','Código del profesional por defecto en RDA'),
+ ('api_timeout','Tiempo máximo de espera para llamadas TNS (segundos)'),
+ ('whatsapp_url / api_key','URL y clave para integración con WhatsApp ERP'),
+ ] %}
+
+ | {{ row[0] }} |
+ {{ row[1] }} |
+
+ {% endfor %}
+
+
+
+
Probar conexión TNS — verifica credenciales y obtiene token JWT.
+
Probar Firebird — verifica conectividad con la base de datos clínica.
+
+
+
+
+ Contratos
+
+ /contratos — Gestión de convenios. Define cómo se procesa la información de cada aseguradora.
+
+ | Campo | Descripción |
|---|
+
+ {% for row in [
+ ('N° Contrato','Código del convenio. Referenciado por CODCONTRATO en Firebird.'),
+ ('NIT Empresa','NIT de la aseguradora o empresa del convenio.'),
+ ('Tipo Usuario','Código RIPS: 11=Contributivo, 12=Particular, 07=Póliza, 01=Subsidiado.'),
+ ('Descripción','Nombre descriptivo del convenio.'),
+ ('Excluir RDA','Si activo, las recepciones de este contrato NO se envían en RDA.'),
+ ('Excluir Ventas','Si activo, las facturas de este contrato NO aparecen en Ventas.'),
+ ('Sin Contrato','JSON RDA se envía con numeroContrato: null.'),
+ ('Forma de Pago','Código CIAC / CR / MU. Vacío = determinado automáticamente.'),
+ ] %}
+
+ | {{ row[0] }} |
+ {{ row[1] }} |
+
+ {% endfor %}
+
+
+
+
Códigos de Pago
+
Sección en la misma página para agregar/eliminar códigos (CIAC, CR, MU ya vienen por defecto). El select inline de cada fila asigna la forma de pago al contrato sin recargar la página.
+
+
+
+
+ Ventas — Facturación CMXC
+
+ /ventas — Consulta y envío de facturas de venta al endpoint TNS /v2/facturacion/Ventas/Crear. Solo procesa facturas con PREFIJO = CMXC.
+
+
+
Flujo de uso
+
+ - 1 Seleccionar rango de fechas (FECHAFACT).
+ - 2 Clic en "Cargar" → consulta Firebird y agrupa por factura.
+ - 3 Tabla muestra: clave, paciente, contrato, exámenes, valor, estado.
+ - 4 Botón "Enviar" individual o "Ver JSON" para inspeccionar.
+ - 5 Botón "Enviar Todo" procesa todos los pendientes en lote.
+
+
+
+
Filtros automáticos
+
+ - Solo facturas con PREFIJO = CMXC.
+ - Excluye facturas anuladas (ANULADA = T).
+ - Excluye contratos marcados "Excluir Ventas".
+ - Fecha aplicada sobre FECHAFACT, no FECHA_RECEPCION.
+
+
Agrupación
+
Una factura puede tener múltiples recepciones. Se agrupan por CMXC-{NUM} y se envían como un único JSON con todos los ítems en detallePedido.
+
+
+
+
+
+ Automatización RDA
+
+ /automation — Envío masivo de recepciones RDA al endpoint /v2/rda/RdaPaciente/Insertar. Procesa PREFIJO = LHXC, RCXC, SC.
+
+
+
Flujo de uso
+
+ - 1 Seleccionar rango de fechas y (opcional) contrato específico.
+ - 2 "Cargar" → consulta Firebird con join a PACIENTE, RELACION, EXAMEN, MEDICO.
+ - 3 Tabla muestra estado de cada recepción.
+ - 4 Envío individual o masivo "Enviar Todo Pendiente".
+ - 5 "Solo pendientes" omite las ya enviadas exitosamente.
+
+
+
+
Comportamiento automático
+
+ - Si el paciente no existe en TNS, lo registra automáticamente antes del RDA.
+ - Excluye recepciones con PS_NUM (muestras especiales).
+ - Excluye contratos marcados "Excluir RDA".
+ - Contratos "Sin Contrato" → numeroContrato: null en JSON.
+ - Tipo de usuario (tipousuario) tomado del mapa de contratos.
+ - Sincroniza el paciente en WhatsApp ERP (opcional).
+
+
+
+
+
+
+ Terceros
+
+ /terceros — Registro manual de pacientes en TNS via /v2/tablas/Tercero/Crear.
+
+ - Búsqueda de paciente en Firebird por número de documento.
+ - Vista previa del JSON antes de enviar a TNS.
+ - Envío individual con respuesta inmediata.
+ - Listado de los últimos 20 terceros registrados.
+ - Acceso a consultas SQL guardadas de tipo "terceros".
+ - Sincronización opcional del paciente en WhatsApp ERP.
+
+
+
+
+
+ Transacción — RDA Manual
+
+ /transaccion — Envío manual de RDA para una factura o recepción específica usando una consulta SQL guardada.
+
+ - Selector de consulta SQL (tipo "transaccion") guardada.
+ - Campos de filtro: número de factura, rango de fechas.
+ - Vista previa del JSON RDA generado antes de enviar.
+ - Manejo de contratos: excluidos, sin contrato, tipo de usuario.
+
+
+
+
+
+ Pacientes / Sincronización
+
+ /pacientes — Sincronización masiva de pacientes con el sistema WhatsApp ERP del laboratorio.
+
+ - Consulta todos los pacientes en Firebird por rango de fechas.
+ - Sincronización masiva al WhatsApp ERP (insertar o actualizar).
+ - Migración de diagnósticos CIE-10 (12.000+ registros en lotes de 200).
+ - Vista de exámenes por cédula de paciente.
+ - Log de cada sincronización: creados, actualizados, omitidos, errores.
+
+
+
+
+
+ Consultas SQL (Queries)
+
+ /queries — Gestión de consultas SQL reutilizables que se ejecutan contra Firebird.
+
+
terceros
Consultas para datos de pacientes (Tercero/Crear en TNS).
+
transaccion
Consultas para recepciones RDA (RdaPaciente/Insertar).
+
ventas
Consultas históricas para facturas de venta.
+
Las consultas se pueden crear, editar y eliminar. Se cargan como selector en los módulos Terceros y Transacción. Soportan parámetros :fecha_ini, :fecha_fin, :num_factura, :doc_num.
+
+
+
+
+ Prueba RDA
+
+ /test-rda — Herramienta de diagnóstico para probar el envío de RDA por recepción o factura específica.
+
+ - Búsqueda por IDRECEPCION o NUM_FACTURA específico.
+ - Genera y muestra el JSON RDA completo antes de enviar.
+ - Opción: enviar solo tercero, solo RDA, o ambos.
+ - Muestra respuesta completa de TNS incluyendo mensajes de error detallados.
+ - Ideal para diagnóstico de registros individuales con problemas.
+
+
+
+
+
+ Historial de Envíos
+
+ /logs — Registro completo de todos los envíos al sistema TNS con filtros avanzados y reenvío.
+
+
+
Filtros disponibles
+
+ - Tipo: terceros / transaccion / ventas.
+ - Estado: success / error / warning.
+ - Número de factura o cédula.
+ - Rango de fechas. Paginación 50/pág.
+
+
+
+
Por cada registro
+
+ - Tipo, factura, contrato, usuario, estado.
+ - JSON completo enviado (formateado).
+ - Respuesta completa de TNS.
+ - Botón "Reenviar" para registros con error.
+
+
+
+ Reenvío: obtiene el JSON guardado, hace nueva autenticación TNS y reenvía al endpoint correcto según el tipo. El registro se actualiza con el nuevo resultado.
+
+
+
+
+
+ Resumen Diario
+
+ /logs/resumen — Vista consolidada de todos los envíos de un día, agrupados por factura/paciente.
+
+ - Total del día, exitosos y con error.
+ - Estado final por registro (éxito si algún intento fue exitoso).
+ - Número de intentos y hora del primer/último envío.
+ - Filtro por tipo de envío.
+
+
+
+
+
+ Registro de Actividad
+
+ /logs/actividad — Log de auditoría de todas las acciones de los usuarios del sistema.
+
+
+
Acciones registradas
+
+ - Creación, edición y eliminación de contratos.
+ - Cambios en configuración del sistema.
+ - Envíos individuales y masivos (terceros, RDA, ventas).
+ - Reenvíos desde historial.
+ - Cambios de forma de pago en contratos.
+ - Sincronizaciones con WhatsApp ERP.
+
+
+
+
Filtros
+
+ - Por usuario.
+ - Por tipo de acción.
+ - Por rango de fechas.
+ - Paginación 50/pág.
+
+
+
+
+
+
+ ERP Lab / WhatsApp
+
+ /envios/erp — Integración con el sistema WhatsApp ERP del laboratorio.
+
+ - Sincronización de pacientes recientes (ventana configurable de minutos).
+ - Migración masiva de diagnósticos CIE-10 (12.000+) en lotes de 200.
+ - Indicador de estado de configuración (URL y API Key).
+ - Log por sincronización: total, creados, actualizados, omitidos, errores.
+
+ /envios/tns — Vista de envíos recientes al sistema TNS con estado consolidado.
+
+
+
+
+ Referencia JSON — Factura de Venta
+
+ POST {TNS_BASE}/v2/facturacion/Ventas/Crear?codigosucursal={api_sucursal}
+ {
+ "codigoPrefijo": "CMXC",
+ "numero": "00309",
+ "numeroFactura": "00309",
+ "sucursal": "00",
+ "fecha": "15/07/2026",
+ "kardexId": 0,
+ "codigoPedido": "",
+ "nombreCliente": "",
+ "codTercero": "900123456-7", // NIT con dígito de verificación
+ "codVendedor": "00",
+ "codDespachar": "00",
+ "codFormaPago": "CR", // CIAC | CR | MU
+ "codBanco": "", // siempre vacío
+ "fechaVence": "14/08/2026", // FECHAFACT + DIASVENC días
+ "fechaEntrega": "15/07/2026",
+ "plazoDias": 30, // 0 si CIAC, DIASVENC si CR/MU
+ "observacion": "",
+ "sucursal": "00",
+ "codigoCentroCosto": "00",
+ "codigoArea": "00",
+ "terminal": "00",
+ "detallePedido": [
+ {
+ "codMat": "90600", // CUPS del examen
+ "codBodega": "00",
+ "cantidad": 1,
+ "tipoUnidad": "M",
+ "descuento": 0,
+ "descuentoValor": 0,
+ "centrosCostos": "00",
+ "porcIva": 0,
+ "valor": 7000,
+ "impConsumo": 0,
+ "observacion": "",
+ "lote": "",
+ "fechaVenceLote": "",
+ "nroDocumento": "",
+ "itemsSerial": [],
+ "tipoSerial": ""
+ }
+ ],
+ "detalleFormaPago": [],
+ "asentar": 0,
+ "detalleDescuentos": []
+}
+
+
+
+
+ Referencia JSON — RDA Paciente
+
+ POST {TNS_BASE}/v2/rda/RdaPaciente/Insertar?codigosucursal={api_sucursal}
+ {
+ "codigoPrefijo": "LHXC",
+ "numero": "05103",
+ "fecha": "15/07/2026",
+ "codTercero": "1090512345", // código paciente en Firebird
+ "codVendedor": "00",
+ "codigoCentroCosto": "00",
+ "tipoIngreso": "1",
+ "fechaHoraIngreso": "15/07/2026 08:30:00",
+ "fechaHoraEgreso": "15/07/2026 08:35:00",
+ "modalidadAtencion": "01",
+ "numeroContrato": "040", // null si sin_contrato=1
+ "descuento": 0,
+ "diagnosticoprincipal": "Z017",
+ "discapacidad": "08",
+ "tipousuario": "11", // del mapa de contratos
+ "viaIngreso": "01",
+ "esTerapia": false,
+ "esProcedimiento": false,
+ "numeroAutorizacion": null,
+ "detallePedido": [
+ {
+ "codigoMaterial": "90600", // CUPS del examen
+ "codigoBodega": "00",
+ "cantidad": 1,
+ "observacion": "",
+ "profesional": "12345678",
+ "especialidad": "01",
+ "profesionalRemisionante": "00",
+ "diagnosticoprincipal": "Z017",
+ "fechaHoraRealizacion": "15/07/2026 08:30:00"
+ }
+ ]
+}
+
+
+
+
+ Lógica de negocio — Formas de Pago
+
+ El sistema determina codFormaPago con la siguiente prioridad:
+
+ Prioridad 1: Si el contrato tiene "Forma de Pago" asignada → se usa esa, ignorando el total.
+ Prioridad 2: Si no tiene asignación → automático: CIAC si total=$0, CR si total>$0.
+
+
+ | Código | Nombre | plazoDias | fechaVence |
|---|
+
+ | CIAC | Contado inmediato | 0 | = fecha de la factura |
+ | CR | Crédito | DIASVENC (30) | FECHAFACT + 30 días |
+ | MU | Mixto | DIASVENC (30) | FECHAFACT + 30 días |
+
+
+ codBanco siempre se envía como cadena vacía "". DIASVENC se lee de FACTURA_DIAN.DIASVENC en Firebird.
+
+
+
+
+ Lógica de negocio — Exclusiones y Prefijos
+
+
+
+
Banderas de contrato
+
+ | Bandera | Efecto |
|---|
+
+ | excluir_rda=1 | NO aparece en RDA / Automatización. |
+ | excluir_ventas=1 | NO aparece en Ventas. |
+ | sin_contrato=1 | JSON RDA con numeroContrato: null. |
+ | cod_forma_pago | Override de forma de pago en venta. |
+
+
+
+
+
Prefijos de factura
+
+ | Prefijo | Módulo |
|---|
+
+ | CMXC | Ventas — remisiones externas. |
+ | LHXC | Automatización RDA. |
+ | RCXC | Automatización RDA. |
+ | SC | Automatización RDA. |
+
+
+
+
+
+
+
+ Soporte técnico
+
+
+
+
U-SITE S.A.S. BIC
+
contacto@u-s.app
+
https://u-s.app
+
Lunes a viernes — días hábiles
+
+
+
Antes de contactar soporte
+
+ - • Verificar red entre servidor y 192.168.0.125 (Firebird).
+ - • Confirmar que uvicorn está corriendo en el puerto 8080.
+ - • Probar credenciales TNS en /config.
+ - • Revisar error específico en /logs.
+ - • Consultar /logs/actividad para rastrear la operación.
+
+
+
+ RIPS Manager v1.0 — Desarrollado por U-SITE S.A.S. BIC para Laboratorio Clínico Ximena Caicedo
+
+
+
+