🏥 API_SM — Motor Central de Catálogos Normativos en Salud (CUPS, CIE-10, EPS) & Inspector FHIR Res. 1888 (IHCE)
API_SM es una plataforma centralizada de microservicios y panel administrativo SPA (Vue 3 + Django REST Framework + MariaDB 11) diseñada para proveer catálogos normativos oficiales del sector salud en Colombia (CUPS, CIE-10 y Entidades / EPS), homologación masiva por versiones y un Inspector / Traductor Clínico de Bundles HL7 FHIR R4 (Resolución 1888 / IHCE Minsalud) con validación cruzada en lote contra la base de datos oficial.
A diferencia de repositorios estáticos o scripts monolíticos que mezclan HTML dentro de vistas de Python, API_SM implementa una arquitectura Monorepo Multicontenedor 100% desacoplada con herramientas especializadas para interoperabilidad clínica:
-
🩺 Inspector y Traductor Clínico de Bundles FHIR R4 (Resolución 1888 / IHCE Ministerio de Salud):
- Auto-detección inteligente de los 4 tipos de RDA oficiales:
RDA de Paciente (Antecedentes Clínicos)RDA de Consulta ExternaRDA de UrgenciasRDA de Hospitalización
- Traducción completa a lenguaje clínico humano (8 pestañas estructuradas):
- 👤 Paciente (
Patient): Priorización estricta del estándar colombiano (ColombianPersonIdentifier:CC,TI,CE,DE,PA,RC,MS,AS,CN,PE,PT) sobre el código genérico HL7v2-0203(PN), nombres desglosados, sexo biológico, identidad de género, fecha de nacimiento con cálculo de edad, nacionalidad, municipio/país de residencia, zona territorial y teléfono. - 🏥 Encuentro / Atención (
Encounter): Modalidad de atención, clasificación, vía de ingreso, causa o motivo de atención, triage, estado y periodo de la atención. - 🏢 Prestador e IPS / EPS (
Organization+Practitioner+Location): Identificación tributaria (NIT), código de habilitación REPS, ubicación física, aseguradora/administradora (EAPB) y profesionales de salud intervinientes. - 🧬 Antecedentes Clínicos Completos (
AllergyIntolerance,FamilyMemberHistory,MedicationStatement,ConditionStatementRDA):- Alergias: Estado clínico (
Active/Inactive), Estado de verificación (Confirmed/Unconfirmed), Tipo de alergia (Alergia/Intolerancia), Código y Nombre del alergeno. - Familiares: Estado del antecedente (
Completed), Parentesco (FTH,MTH, etc.), Diagnóstico (CIE-10) y Descripción. - Farmacológicos: Estado de la declaración del medicamento, Código
MipresINN/DCI, Nombre del medicamento y Dosificación (dosage.text). - Patológicos: Condiciones previas y comorbilidades reportadas.
- Alergias: Estado clínico (
- 🔬 Diagnósticos (
Condition+Encounter.diagnosis): Clasificación de diagnósticos de ingreso, principales, relacionados y de egreso con su rol, tipo y confirmación. - 💉 Procedimientos, Medicamentos e Incapacidades (
Procedure,MedicationRequest,MedicationAdministration,Observation,ServiceRequest): Cruce de procedimientosCUPS, prescripciones, administraciones de medicamentos, signos vitales/antropometría y órdenes médicas. - 📑 Documento Clínico (
Composition+DocumentReference): Metadatos del RDA, autor principal, custodio, nivel de confidencialidad, eventos clínicos del acto (Composition.event), secciones estructuradas y anexos PDF/Base64. - ✅ Cruce Normativo en Lote contra Base de Datos Oficial (
API_SM): Extrae todos los códigosCIE-10,CUPSyEPSpresentes en el Bundle JSON y los valida en una sola consulta batch contra MariaDB, indicando si el código existe, su nombre oficial en el catálogo vigente o si presenta discrepancias.
- 👤 Paciente (
- Auto-detección inteligente de los 4 tipos de RDA oficiales:
-
⚡ Motor de Consultas REST de Alta Velocidad (Retrocompatible con Sistemas HIS / HCE Legacy):
- Endpoints públicos
/api/entidades,/api/cie10y/api/cupsoptimizados para integrarse de forma transparente con sistemas de Historia Clínica Electrónica (Symfony 1.4, Laravel, Node.js, etc.). - Búsqueda simultánea por código exacto o coincidencia parcial de descripción/nombre, filtrado por versión normativa (
Año 2024,Año 2025,Año 2026, etc.) y paginación configurable.
- Endpoints públicos
-
📥 Importador Masivo Inteligente (Excel
.xlsx/.xlsy.csv) + Exportador CSV en 1 Clic:- Procesamiento vectorizado con
pandas+openpyxlcapaz de insertar o actualizar miles de registros de CUPS, CIE-10 y EPS mediante operaciones por lotes (bulk_create/update_conflicts). - Detección automática de columnas, asignación de etiquetas de versión (
versionyversion_fecha) y descarga directa del catálogo filtrado en formato.csvcompatible con Excel (UTF-8 con BOM).
- Procesamiento vectorizado con
-
🧱 Arquitectura Monorepo Desacoplada Multicontenedor (
Frontend+Backend+MariaDB 11):- Frontend (
frontend/): SPA reactiva en Vue 3 (<script setup>) + Vue Router 4 + Pinia + Vite 5, con diseño moderno oscuro/claro, barra lateral colapsable y componentes reutilizables. - Backend (
backend/): API pura en Django 4.2 LTS + Django REST Framework + Gunicorn, separando controladores (views.py), serializadores (serializers.py) y capa de servicios (services/fhir_inspector.py,services/importer.py,services/exporter.py). - Base de Datos (
db): Contenedor MariaDB 11 afinado para bajo consumo de memoria (innodb-buffer-pool-size=64M,performance-schema=OFF) con healthcheck nativo antes de iniciar las migraciones de Django.
- Frontend (
git clone https://github.com/alexmargomez/API_SM.git
cd API_SM
cp .env.example .envEdita el archivo .env según tu entorno local o de producción:
# ==========================================
# Variables de Entorno - API_SM (Docker Compose)
# ==========================================
# 1. Puertos Expuestos (Sincronizados automáticamente por ALpanel)
BACKEND_PORT=8000
FRONTEND_PORT=5174
DB_EXTERNAL_PORT=3307
# 2. Claves de Django (Backend)
SECRET_KEY=poner_aqui_clave_secreta_django_segura
DEBUG=False
ALLOWED_HOSTS=localhost,127.0.0.1,backend
CSRF_TRUSTED_ORIGINS=http://localhost,https://localhost,http://localhost:5174
# 3. Claves de Base de Datos (MariaDB 11)
MARIADB_DATABASE=api_sm_db
MARIADB_USER=api_user
MARIADB_PASSWORD=api_password
MARIADB_ROOT_PASSWORD=api_root_password
DB_NAME=api_sm_db
DB_USER=api_user
DB_PASSWORD=api_password
DB_HOST=db
DB_PORT=3306
# 4. Frontend (Vue 3 + Vite)
VITE_API_URL=/api
VITE_BACKEND_PROXY=http://backend:8000docker compose up -d --buildAl iniciar, el contenedor api_sm_django esperará a que api_sm_mariadb pase el healthcheck, ejecutará automáticamente python manage.py makemigrations && python manage.py migrate y levantará el servidor Gunicorn.
- Panel Administrativo SPA (Vue 3):
http://localhost:5174 - API REST Backend (Django):
http://localhost:8000/api/ - Base de Datos MariaDB (Puerto Externo):
localhost:3307
docker exec -it api_sm_django python manage.py createsuperuserAPI_SM cumple al 100% con la especificación multicontenedor de ALpanel para despliegues automatizados en servidores VPS:
Variable en .env |
Contenedor Docker | Función en ALpanel |
|---|---|---|
FRONTEND_PORT |
api_sm_frontend |
Puerto del Frontend Vue 3 (5174). Se sincroniza automáticamente con el Frontend Target configurado en la pestaña Dominios & SSL de ALpanel. |
BACKEND_PORT |
api_sm_django |
Puerto del Backend Django/Gunicorn (8000). Se sincroniza con el Backend Target (/api/*) y actualiza automáticamente VITE_BACKEND_PROXY. |
DB_EXTERNAL_PORT |
api_sm_mariadb |
Puerto Externo SQL (3307). ALpanel verifica los puertos libres del VPS y auto-asigna un puerto disponible sin colisionar con otros proyectos. |
ALLOWED_HOSTS / CSRF_TRUSTED_ORIGINS |
api_sm_django |
ALpanel inyecta automáticamente el dominio HTTPS real al asignarlo en Dominios & SSL, manteniendo el repositorio libre de dominios o IPs quemadas. |
develop: Rama activa de desarrollo e integración de nuevas funcionalidades.main: Rama estable de producción. Una vez probado endevelop, se realiza el Merge Pull Request haciamainen GitHub y se despliega en 1 clic desde ALpanel usandoGit Pull+Restart Docker(oRebuildpreservando intactos los datos de MariaDB).
API_SM/
├── docker-compose.yml # 🐳 Orquestación de los 3 servicios (db, backend, frontend) + red bridge y volúmenes
├── .env.example # 📋 Plantilla limpia de variables de entorno (compatible con ALpanel)
│
├── backend/ # ⚙️ BACKEND API REST (Python 3.11 + Django 4.2 + DRF + Gunicorn)
│ ├── Dockerfile # Imagen ligera python:3.11-slim con dependencias de compilación MySQL
│ ├── manage.py # CLI administrativo de Django
│ ├── requirements.txt # Dependencias Python (Django, DRF, corsheaders, mysqlclient, pandas, openpyxl, gunicorn)
│ ├── core/ # 🏛️ Configuración central del proyecto Django
│ │ ├── settings.py # Configuración dinámica vía variables de entorno (.env), CORS, CSRF y MariaDB
│ │ ├── urls.py # Enrutador raíz (/admin/ y /api/)
│ │ ├── wsgi.py # Punto de entrada WSGI para Gunicorn en producción
│ │ └── asgi.py # Punto de entrada ASGI
│ └── api/ # 📦 Aplicación principal de catálogos normativos y herramientas clínicas
│ ├── models.py # Modelos ORM: Eps (codigo, nombre, nit, regimen), Cie10 y Cups (versionados)
│ ├── serializers.py # Serializadores Django REST Framework
│ ├── views.py # Controladores REST (Endpoints públicos, Panel SPA, Auth y FHIR Inspector)
│ ├── urls.py # Definición de rutas bajo el prefijo /api/
│ └── services/ # 🧠 CAPA DE SERVICIOS DE DOMINIO (Lógica desacoplada de las vistas HTTP)
│ ├── fhir_inspector.py # Motor traductor de Bundles HL7 FHIR R4 (Res. 1888 / IHCE) + validación DB en lote
│ ├── importer.py # Procesador masivo de archivos Excel (.xlsx/.xls) y CSV con pandas
│ └── exporter.py # Generador de descargas CSV en streaming con codificación UTF-8-SIG
│
└── frontend/ # 🎨 FRONTEND SPA (Vue 3 Composition API + Pinia + Vue Router 4 + Vite 5)
├── Dockerfile # Contenedor Node.js con servidor Vite y proxy inverso dinámico hacia backend
├── package.json # Dependencias del cliente (vue, vue-router, pinia, vite)
├── vite.config.js # Configuración de Vite y proxy automático de /api -> VITE_BACKEND_PROXY
├── index.html # Plantilla raíz de la SPA
└── src/
├── main.js # Inicialización de Vue 3, Pinia y Vue Router
├── App.vue # Layout maestro con Sidebar reactivo y área de trabajo dinámica
├── router/
│ └── index.js # Definición de rutas SPA y guardias de navegación (requiresAuth)
├── stores/
│ └── auth.js # Store Pinia para sesión de usuario, login/logout y verificación /api/auth/me/
├── services/
│ └── api.js # Cliente HTTP centralizado (fetch wrapper con credenciales y manejo de errores)
├── components/ # 🧩 Componentes UI reutilizables
│ ├── SidebarNav.vue # Menú lateral con navegación categorizada y estado de sesión
│ ├── SearchFilterBar.vue # Barra de búsqueda en vivo + selector de versión + exportación CSV
│ └── PaginationBar.vue # Paginador reactivo con control de página y conteo de registros
└── views/ # 🖥️ Vistas principales de la aplicación
├── DashboardView.vue # Panel de métricas globales (totales CUPS, CIE-10, EPS y desglose por versión)
├── EntidadesView.vue # Explorador y buscador de Entidades / Administradoras (EPS)
├── Cie10View.vue # Explorador normativo de diagnósticos CIE-10 con filtro por versión
├── CupsView.vue # Explorador normativo de procedimientos CUPS con filtro por versión
├── FhirInspectorView.vue # 🩺 Inspector / Traductor interactivo de Bundles FHIR Res. 1888 (8 módulos + drag & drop)
├── ImportView.vue # Consola de carga masiva Excel/CSV (protegida por autenticación)
├── DocsView.vue # Documentación interactiva de los endpoints de la API con ejemplos cURL/JSON
└── LoginView.vue # Vista de inicio de sesión administrativo
Diseñados para consumo directo desde sistemas externos sin requerir sesión del panel:
| Método | Endpoint | Parámetros Query (GET) |
Descripción |
|---|---|---|---|
GET |
/api/entidades |
q (búsqueda), codigo, regimen, limit |
Consulta de Entidades / Administradoras (EPS) por código de habilitación, NIT o nombre. |
GET |
/api/cie10 |
q (búsqueda), codigo, version, limit |
Consulta de diagnósticos CIE-10 por código exacto o texto descriptivo y versión normativa. |
GET |
/api/cups |
q (búsqueda), codigo, version, limit |
Consulta de procedimientos CUPS por código exacto o descripción y versión normativa. |
# Buscar procedimientos CUPS que coincidan con "890201" (Consulta de primera vez)
curl -X GET "http://localhost:8000/api/cups?q=890201&limit=10"| Método | Endpoint | Autenticación | Descripción |
|---|---|---|---|
GET |
/api/panel/stats/ |
Pública (Lectura) | Métricas globales de registros (EPS, CIE-10, CUPS) y agrupación histórica por versiones. |
GET |
/api/panel/entidades/ |
Pública (Lectura) | Listado paginado de EPS con filtros de búsqueda y régimen. |
GET |
/api/panel/cie10/ |
Pública (Lectura) | Listado paginado de CIE-10 con selector de versión y búsqueda instantánea. |
GET |
/api/panel/cups/ |
Pública (Lectura) | Listado paginado de CUPS con selector de versión y búsqueda instantánea. |
GET |
/api/panel/export/<entity>/ |
Pública (Lectura) | Descarga directa en .csv (entidades, cie10 o cups) aplicando los filtros activos. |
POST |
/api/tools/fhir-inspector/ |
Pública (Utilidad) | Recibe un bundle FHIR R4 (JSON), lo traduce en 8 secciones clínicas y valida CIE-10, CUPS y EPS contra la base de datos. |
POST |
/api/panel/import/ |
🔒 Requiere Login | Importación masiva de archivos .xlsx, .xls o .csv hacia entidades, cie10 o cups. |
POST |
/api/auth/login/ |
Pública | Inicio de sesión administrativo en el panel SPA. |
POST |
/api/auth/logout/ |
🔒 Requiere Login | Cierre de sesión activa. |
GET |
/api/auth/me/ |
Pública | Verifica el estado de autenticación actual del usuario en la SPA. |
El servicio backend/api/services/fhir_inspector.py procesa cualquier Bundle transaccional o documental bajo los lineamientos técnicos de la Resolución 1888 de 2025 (Ministerio de Salud y Protección Social de Colombia):
- Priorización de Sistemas de Codificación Nacionales (
CodeSystemMinsalud):- En recursos
Patient,Practitioner,RelatedPersonyOrganization, prioriza automáticamente los sistemas oficialesColombianPersonIdentifier,ColombianOrganizationIdentifiersyColombianDocumentTypes(CC,TI,CE,DE,PA,NIT, etc.) por encima del tipo genérico internacionalhttp://terminology.hl7.org/CodeSystem/v2-0203(PN/TAX), mostrando el identificador compuesto tal como lo exige el validador del Ministerio (ej.DE-095305827-14).
- En recursos
- Desglose Integral de Antecedentes Clínicos (
RDA de PacienteyRDA de Encuentros):- Alergias (
AllergyIntolerance): MuestraEstado clínico(clinicalStatus),Estado de verificación(verificationStatus),Tipo de alergia(type/category),CódigoyNombre del alergeno. - Antecedentes Familiares (
FamilyMemberHistory): MuestraEstado del antecedente familiar(status),Parentesco(relationship),Diagnóstico(condition.codeCIE-10) yDescripción. - Antecedentes Farmacológicos (
MedicationStatement): MuestraEstado de la declaración del medicamento(status), códigoMipresINN/DCI,MedicamentoyDosificación(dosage.text).
- Alergias (
- Auditoría Cruzada contra Catálogos Locales:
- Todos los códigos detectados en el JSON se consultan en bloque (
__in) contra las tablasCie10,CupsyEpsde API_SM, generando un semáforo de conformidad (✔ Encontrado en BDvs⚠ No registrado en catálogo local) junto con el porcentaje global de coincidencia normativa.
- Todos los códigos detectados en el JSON se consultan en bloque (