{% extends "base.html" %} {% block title %}Documentación{% endblock %} {% block header %}Documentación del Sistema{% endblock %} {% block content %}

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.

Envío TNS

Ventas y RDA

Firebird

Base de datos clínica

Trazabilidad

Log completo

Arquitectura técnica


Stack tecnológico

ComponenteTecnología
BackendPython 3 + FastAPI (async)
FrontendJinja2 + TailwindCSS + Font Awesome
BD localSQLite 3 (WAL mode)
BD clínicaFirebird 2.5 — 192.168.0.125:3025
API externaTNS — REST JSON + Bearer Token
ServidorWindows — uvicorn :8080
AuthJWT + 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'), ] %}
  1. {{ step[0] }}
    {{ step[1] }}: {{ step[2] }}
  2. {% endfor %}

Acceso y credenciales


URL del sistema (red local)

http://192.168.0.125:8080

Importante

Las credenciales de acceso son suministradas por el administrador del sistema.

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.

{% 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'), ] %} {% endfor %}
ParámetroDescripción
{{ row[0] }} {{ row[1] }}
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.

{% 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.'), ] %} {% endfor %}
CampoDescripción
{{ row[0] }} {{ row[1] }}

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. 1 Seleccionar rango de fechas (FECHAFACT).
  2. 2 Clic en "Cargar" → consulta Firebird y agrupa por factura.
  3. 3 Tabla muestra: clave, paciente, contrato, exámenes, valor, estado.
  4. 4 Botón "Enviar" individual o "Ver JSON" para inspeccionar.
  5. 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. 1 Seleccionar rango de fechas y (opcional) contrato específico.
  2. 2 "Cargar" → consulta Firebird con join a PACIENTE, RELACION, EXAMEN, MEDICO.
  3. 3 Tabla muestra estado de cada recepción.
  4. 4 Envío individual o masivo "Enviar Todo Pendiente".
  5. 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ódigoNombreplazoDiasfechaVence
CIACContado inmediato0= fecha de la factura
CRCréditoDIASVENC (30)FECHAFACT + 30 días
MUMixtoDIASVENC (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

BanderaEfecto
excluir_rda=1NO aparece en RDA / Automatización.
excluir_ventas=1NO aparece en Ventas.
sin_contrato=1JSON RDA con numeroContrato: null.
cod_forma_pagoOverride de forma de pago en venta.

Prefijos de factura

PrefijoMódulo
CMXCVentas — remisiones externas.
LHXCAutomatización RDA.
RCXCAutomatización RDA.
SCAutomatizació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
{% endblock %}