Update DOCUMENTACION.md with complete project documentation
This commit is contained in:
Lizandro Guarnizo
+450
-347
@@ -1,347 +1,450 @@
|
|||||||
# RIPS Manager — Documentación Técnica
|
# RIPS Manager — Documentación Completa
|
||||||
|
|
||||||
Sistema web para generar y enviar JSON de RIPS (Res. 2275/2023) a una API, conectándose a una base de datos Firebird.
|
**Desarrollado por [U-SITE SAS BIC](https://u-site.app/)**
|
||||||
|
|
||||||
---
|
**Repositorio**: `https://github.com/U-SITE-SAS-BIC/rips_manager`
|
||||||
|
|
||||||
## Arquitectura
|
Sistema web para generar y enviar JSON de RIPS (Registro Individual de Prestación de Servicios de Salud) según la **Resolución 2275 de 2023** del Ministerio de Salud y Protección Social de Colombia.
|
||||||
|
|
||||||
```
|
---
|
||||||
┌─────────────┐ ┌──────────────────┐ ┌──────────────┐
|
|
||||||
│ Navegador │────▶│ FastAPI (8080) │────▶│ Firebird BD │
|
## 1. Arquitectura
|
||||||
│ (Tailwind) │◀────│ + Jinja2 │◀────│ (datos) │
|
|
||||||
└─────────────┘ └──────────────────┘ └──────────────┘
|
```
|
||||||
│
|
┌────────────────────┐
|
||||||
▼
|
│ Navegador │
|
||||||
┌──────────────┐
|
│ Tailwind + CM │
|
||||||
│ SQLite │
|
└────────┬───────────┘
|
||||||
│ (app.db) │
|
│ HTTP
|
||||||
└──────────────┘
|
┌────────▼───────────┐
|
||||||
│
|
│ FastAPI (8080) │
|
||||||
▼
|
│ + Jinja2 │
|
||||||
┌──────────────┐
|
│ + Auth Middleware │
|
||||||
│ API externa │
|
└───┬────┬────┬──────┘
|
||||||
│ (envío RIPS)│
|
│ │ │
|
||||||
└──────────────┘
|
┌──────────┘ │ └──────────┐
|
||||||
```
|
▼ ▼ ▼
|
||||||
|
┌──────────┐ ┌──────────┐ ┌──────────────┐
|
||||||
## Stack técnico
|
│ Firebird │ │ SQLite │ │ API externa │
|
||||||
|
│ (datos) │ │ (app.db) │ │ (receptor) │
|
||||||
| Componente | Tecnología |
|
└──────────┘ └──────────┘ └──────────────┘
|
||||||
|---|---|
|
```
|
||||||
| Backend | Python 3.9+ / FastAPI |
|
|
||||||
| Frontend | Jinja2 + Tailwind CSS (CDN) + FontAwesome |
|
### Stack Tecnológico
|
||||||
| Base de datos app | SQLite (usuarios, config, logs, queries) |
|
|
||||||
| Base de datos datos | Firebird (vía `fdb`) |
|
| Componente | Tecnología | Versión |
|
||||||
| Autenticación | JWT + bcrypt + HttpOnly cookies |
|
|---|---|---|
|
||||||
| Cliente HTTP | httpx (async) |
|
| Backend | FastAPI | 0.115.6 |
|
||||||
| Servidor | uvicorn |
|
| Servidor ASGI | Uvicorn | 0.34.0 |
|
||||||
|
| Templates | Jinja2 | 3.1.5 |
|
||||||
---
|
| CSS | Tailwind CSS | CDN |
|
||||||
|
| Editor SQL | CodeMirror | 5.65.16 CDN |
|
||||||
## Endpoints (20 totales)
|
| BD de la app | SQLite | — |
|
||||||
|
| BD de datos | Firebird | vía fdb >= 2.0.0 |
|
||||||
### Autenticación (6 endpoints)
|
| Autenticación | python-jose (JWT) + bcrypt | 3.3.0 / 4.2.1 |
|
||||||
|
| Cliente HTTP | httpx | 0.28.1 |
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| Multipart | python-multipart | 0.0.20 |
|
||||||
|---|---|---|---|
|
| Archivos async | aiofiles | 24.1.0 |
|
||||||
| GET | `/auth/login` | Página de inicio de sesión | Pública |
|
|
||||||
| POST | `/auth/login` | Procesa login, devuelve cookie JWT | Pública |
|
---
|
||||||
| GET | `/auth/register` | Página de registro | Pública |
|
|
||||||
| POST | `/auth/register` | Registra nuevo usuario | Pública |
|
## 2. Endpoints (20 totales)
|
||||||
| GET | `/auth/logout` | Cierra sesión (elimina cookie) | Pública |
|
|
||||||
| POST | `/auth/api/login` | Login vía API (devuelve token JSON) | Pública |
|
### Autenticación — `app/routes/auth.py`
|
||||||
|
|
||||||
### Dashboard (1 endpoint)
|
| Método | Ruta | Descripción | Auth |
|
||||||
|
|---|---|---|---|
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| GET | `/auth/login` | Página de inicio de sesión | Pública |
|
||||||
|---|---|---|---|
|
| POST | `/auth/login` | Procesa login, setea cookie HttpOnly con JWT | Pública |
|
||||||
| GET | `/dashboard` | Estadísticas de envíos, últimos registros | Requerida |
|
| GET | `/auth/register` | Página de registro | Pública |
|
||||||
|
| POST | `/auth/register` | Crea usuario (username, email, password) | Pública |
|
||||||
### Configuración (2 endpoints)
|
| GET | `/auth/logout` | Elimina cookie, redirige a login | Pública |
|
||||||
|
| POST | `/auth/api/login` | Login API, devuelve `{"access_token": "...", "token_type": "bearer"}` | Pública |
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
|
||||||
|---|---|---|---|
|
### Dashboard — `app/routes/dashboard.py`
|
||||||
| GET | `/config` | Página de configuración (Firebird + API + prestador) | Requerida |
|
|
||||||
| POST | `/config/save` | Guarda toda la configuración | Requerida |
|
| Método | Ruta | Descripción | Auth |
|
||||||
|
|---|---|---|---|
|
||||||
### Consultas SQL (3 endpoints)
|
| GET | `/dashboard` | Estadísticas: total envíos exitosos/errores, últimos 10 registros | Requerida |
|
||||||
|
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
### Configuración — `app/routes/config.py`
|
||||||
|---|---|---|---|
|
|
||||||
| GET | `/queries` | Página de gestión de consultas SQL | Requerida |
|
| Método | Ruta | Descripción | Auth |
|
||||||
| POST | `/queries/create` | Crea nueva consulta SQL | Requerida |
|
|---|---|---|---|
|
||||||
| POST | `/queries/delete/{id}` | Elimina consulta SQL | Requerida |
|
| GET | `/config` | Página de configuración (Firebird, API, prestador) | Requerida |
|
||||||
| POST | `/queries/update/{id}` | Actualiza consulta SQL | Requerida |
|
| POST | `/config/save` | Guarda configuración (11 claves) | Requerida |
|
||||||
|
|
||||||
### Terceros (3 endpoints)
|
### Consultas SQL — `app/routes/queries.py`
|
||||||
|
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| Método | Ruta | Descripción | Auth |
|
||||||
|---|---|---|---|
|
|---|---|---|---|
|
||||||
| GET | `/terceros` | Página de envío de terceros | Requerida |
|
| GET | `/queries` | Página con 3 pestañas: Probador / Constructor / Editor | Requerida |
|
||||||
| POST | `/terceros/test-connection` | Prueba conexión Firebird | Requerida |
|
| POST | `/queries/run-sql` | Ejecuta SQL raw contra Firebird (max 200 filas) | Requerida |
|
||||||
| POST | `/terceros/preview` | Vista previa del JSON de terceros | Requerida |
|
| POST | `/queries/test` | Prueba consulta guardada (max 20 filas) | Requerida |
|
||||||
| POST | `/terceros/send` | Genera y envía JSON de terceros a la API | Requerida |
|
| POST | `/queries/esquema` | Devuelve esquema completo: tablas + columnas + tipos | Requerida |
|
||||||
|
| POST | `/queries/tablas` | Lista nombres de tablas | Requerida |
|
||||||
### Transacción RIPS (3 endpoints)
|
| POST | `/queries/create` | Crea nueva consulta | Requerida |
|
||||||
|
| POST | `/queries/update/{id}` | Actualiza consulta | Requerida |
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| POST | `/queries/delete/{id}` | Elimina consulta | Requerida |
|
||||||
|---|---|---|---|
|
|
||||||
| GET | `/transaccion` | Página de envío de transacción RIPS | Requerida |
|
### Terceros — `app/routes/terceros.py`
|
||||||
| POST | `/transaccion/preview` | Vista previa del JSON de transacción | Requerida |
|
|
||||||
| POST | `/transaccion/send` | Genera y envía JSON de transacción a la API | Requerida |
|
| Método | Ruta | Descripción | Auth |
|
||||||
|
|---|---|---|---|
|
||||||
### Automatización (2 endpoints)
|
| GET | `/terceros` | Página de envío de terceros | Requerida |
|
||||||
|
| POST | `/terceros/test-connection` | Prueba conexión Firebird | Requerida |
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| POST | `/terceros/preview` | Vista previa del JSON de terceros | Requerida |
|
||||||
|---|---|---|---|
|
| POST | `/terceros/send` | Genera y envía JSON de terceros a la API | Requerida |
|
||||||
| GET | `/automation` | Página de automatización 2 pasos | Requerida |
|
|
||||||
| POST | `/automation/run` | Ejecuta Paso 1 (terceros) + Paso 2 (transacción) | Requerida |
|
### Transacción RIPS — `app/routes/transaccion.py`
|
||||||
|
|
||||||
### Logs (1 endpoint)
|
| Método | Ruta | Descripción | Auth |
|
||||||
|
|---|---|---|---|
|
||||||
| Método | Ruta | Descripción | Autenticación |
|
| GET | `/transaccion` | Página de envío de transacción RIPS | Requerida |
|
||||||
|---|---|---|---|
|
| POST | `/transaccion/preview` | Vista previa del JSON de transacción | Requerida |
|
||||||
| GET | `/logs` | Historial de envíos con filtros | Requerida |
|
| POST | `/transaccion/send` | Genera y envía JSON de transacción a la API | Requerida |
|
||||||
|
|
||||||
---
|
### Automatización — `app/routes/automation.py`
|
||||||
|
|
||||||
## Flujo de autenticación
|
| Método | Ruta | Descripción | Auth |
|
||||||
|
|---|---|---|---|
|
||||||
```
|
| GET | `/automation` | Página de automatización (2 pasos) | Requerida |
|
||||||
Navegador Servidor
|
| POST | `/automation/run` | Paso 1 (terceros) + Paso 2 (transacción) por rango de fechas | Requerida |
|
||||||
│ │
|
|
||||||
│── GET /auth/login ───────▶│
|
### Logs — `app/routes/logs.py`
|
||||||
│◀──── HTML login page ─────│
|
|
||||||
│ │
|
| Método | Ruta | Descripción | Auth |
|
||||||
│── POST /auth/login ───────▶│ (username + password)
|
|---|---|---|---|
|
||||||
│ │── verifica credenciales
|
| GET | `/logs` | Historial de envíos con filtros (tipo, status, factura) | Requerida |
|
||||||
│ │── genera JWT
|
|
||||||
│◀── 302 /dashboard ────────│ (Set-Cookie: token=JWT; HttpOnly)
|
### Root
|
||||||
│ │
|
|
||||||
│── GET /dashboard ────────▶│ (Cookie: token=JWT)
|
| Método | Ruta | Descripción | Auth |
|
||||||
│ │── middleware verifica JWT
|
|---|---|---|---|
|
||||||
│ │── setea request.state.user
|
| GET | `/` | Redirige a `/dashboard` | Pública |
|
||||||
│◀──── HTML dashboard ──────│
|
|
||||||
```
|
---
|
||||||
|
|
||||||
- **Cookie HttpOnly**: no accesible desde JavaScript (seguridad XSS)
|
## 3. Modelo de Base de Datos
|
||||||
- **JWT expira en 12 horas**
|
|
||||||
- **Bearer token** también soportado para llamadas API (`Authorization: Bearer <token>`)
|
### SQLite (`rips_manager.db`)
|
||||||
|
|
||||||
---
|
#### Tabla `users`
|
||||||
|
| Columna | Tipo | Descripción |
|
||||||
## Flujo de envío de RIPS
|
|---|---|---|
|
||||||
|
| id | INTEGER PK AUTOINCREMENT | ID único |
|
||||||
### Manual (página Terceros + Transacción)
|
| username | TEXT UNIQUE NOT NULL | Nombre de usuario |
|
||||||
|
| email | TEXT UNIQUE NOT NULL | Correo electrónico |
|
||||||
```
|
| password_hash | TEXT NOT NULL | Hash bcrypt |
|
||||||
1. Configurar conexión Firebird y API (una vez)
|
| created_at | TEXT DEFAULT datetime('now') | Fecha de creación |
|
||||||
2. Definir consultas SQL en "Consultas SQL"
|
|
||||||
3. Ir a "Terceros" → seleccionar consulta → "Vista Previa" → "Enviar a API"
|
#### Tabla `config`
|
||||||
4. Ir a "Transacción RIPS" → seleccionar consulta + fechas → "Enviar a API"
|
| Columna | Tipo | Descripción |
|
||||||
```
|
|---|---|---|
|
||||||
|
| id | INTEGER PK AUTOINCREMENT | ID único |
|
||||||
### Automatizado (página Automatización)
|
| key | TEXT UNIQUE NOT NULL | Clave de configuración |
|
||||||
|
| value | TEXT | Valor |
|
||||||
```
|
|
||||||
1. Seleccionar consulta de terceros (Paso 1)
|
**Claves predefinidas:**
|
||||||
2. Seleccionar consulta de transacción (Paso 2)
|
|
||||||
3. Definir rango de fechas
|
| Clave | Default | Descripción |
|
||||||
4. "Ejecutar Automatización Completa"
|
|---|---|---|
|
||||||
└── Paso 1: Envía todos los terceros del período
|
| `firebird_host` | `localhost` | Host Firebird |
|
||||||
└── Paso 2: Envía todas las transacciones del período
|
| `firebird_port` | `3050` | Puerto Firebird |
|
||||||
```
|
| `firebird_database` | — | Ruta BD Firebird |
|
||||||
|
| `firebird_user` | `SYSDBA` | Usuario Firebird |
|
||||||
### Estructura de los JSON generados
|
| `firebird_password` | `masterkey` | Contraseña Firebird |
|
||||||
|
| `api_url` | — | URL de la API destino |
|
||||||
#### JSON Terceros
|
| `api_method` | `POST` | Método HTTP (POST/PUT) |
|
||||||
```json
|
| `api_key` | — | API Key (Bearer token) |
|
||||||
{
|
| `api_timeout` | `30` | Timeout en segundos |
|
||||||
"tipoDocumentoIdentificacion": "CC",
|
| `num_documento_obligado` | — | NIT del prestador |
|
||||||
"numDocumentoIdentificacion": "27765610",
|
| `cod_prestador` | — | Código del prestador |
|
||||||
"primerNombre": "MARIA",
|
|
||||||
"segundoNombre": "ELENA",
|
#### Tabla `queries`
|
||||||
"primerApellido": "GOMEZ",
|
| Columna | Tipo | Descripción |
|
||||||
"segundoApellido": "RUIZ",
|
|---|---|---|
|
||||||
"fechaNacimiento": "1954-01-19",
|
| id | INTEGER PK AUTOINCREMENT | ID único |
|
||||||
"codSexo": "F",
|
| name | TEXT NOT NULL | Nombre descriptivo |
|
||||||
"codEntidadAdministradora": "EPS010",
|
| query_type | TEXT NOT NULL | `terceros` o `transaccion` |
|
||||||
"tipoUsuario": "12",
|
| query_text | TEXT NOT NULL | SQL con parámetros `:param` |
|
||||||
"codPaisResidencia": "170",
|
| description | TEXT | Descripción |
|
||||||
"codMunicipioResidencia": "54001",
|
| created_at | TEXT DEFAULT datetime('now') | Fecha de creación |
|
||||||
"codZonaTerritorialResidencia": "02",
|
|
||||||
"incapacidad": "NO",
|
**Consultas por defecto** (3):
|
||||||
"codPaisOrigen": "170",
|
1. `Terceros - Datos del paciente` — Busca paciente por `:doc_num`
|
||||||
"direccionResidencia": "CRA 5 #10-20",
|
2. `Procedimientos por factura` — Busca servicios por `:factura`, `:fecha_ini`, `:fecha_fin`
|
||||||
"codZonaResidencia": "02"
|
3. `Procedimientos por fecha` — JOIN servicios + pacientes por rango de fechas
|
||||||
}
|
|
||||||
```
|
#### Tabla `envios`
|
||||||
|
| Columna | Tipo | Descripción |
|
||||||
#### JSON Transacción RIPS
|
|---|---|---|
|
||||||
```json
|
| id | INTEGER PK AUTOINCREMENT | ID único |
|
||||||
{
|
| user_id | INTEGER FK → users(id) | Usuario que envió |
|
||||||
"numDocumentoIdObligado": "900278729",
|
| tipo | TEXT NOT NULL | `terceros` o `transaccion` |
|
||||||
"numFactura": "LHXC03404",
|
| factura | TEXT | Número de factura |
|
||||||
"tipoNota": null,
|
| fecha_inicio | TEXT | Inicio del rango |
|
||||||
"numNota": null,
|
| fecha_fin | TEXT | Fin del rango |
|
||||||
"usuarios": [{
|
| pacientes_count | INTEGER DEFAULT 0 | Cantidad de pacientes |
|
||||||
"tipoDocumentoIdentificacion": "CC",
|
| servicios_count | INTEGER DEFAULT 0 | Cantidad de servicios |
|
||||||
"numDocumentoIdentificacion": "27765610",
|
| status | TEXT NOT NULL DEFAULT 'pendiente' | `success` o `error` |
|
||||||
"codEntidadAdministradora": "EPS010",
|
| json_enviado | TEXT | JSON completo enviado |
|
||||||
"tipoUsuario": "12",
|
| respuesta_api | TEXT | Respuesta de la API |
|
||||||
"fechaNacimiento": "1954-01-19",
|
| codigo_cuv | TEXT | Código CUV (si aplica) |
|
||||||
"codSexo": "F",
|
| created_at | TEXT DEFAULT datetime('now') | Fecha del envío |
|
||||||
"codPaisResidencia": "170",
|
|
||||||
"codMunicipioResidencia": "54001",
|
---
|
||||||
"codZonaTerritorialResidencia": "02",
|
|
||||||
"incapacidad": "NO",
|
## 4. Autenticación
|
||||||
"consecutivo": 1,
|
|
||||||
"codPaisOrigen": "170",
|
### Flujo Login
|
||||||
"servicios": {
|
```
|
||||||
"procedimientos": [{
|
Navegador Servidor
|
||||||
"consecutivo": 1,
|
│ │
|
||||||
"codProcedimiento": "903841",
|
│── POST /auth/login ──────▶│ (username + password)
|
||||||
"fechaInicioAtencion": "2026-06-11 00:00",
|
│ │── verifica bcrypt
|
||||||
"codDiagnosticoPrincipal": "R790",
|
│ │── genera JWT HS256
|
||||||
"codDiagnosticoRelacionado": null,
|
│◀── 302 /dashboard ────────│ (Set-Cookie: token=JWT; HttpOnly)
|
||||||
"finalidadTecnologiaSalud": "23",
|
│ │
|
||||||
"viaIngresoServicioSalud": "02",
|
│── GET /dashboard ────────▶│ (Cookie: token=JWT)
|
||||||
"modalidadGrupoServicioTecSal": "01",
|
│ │── middleware decodifica JWT
|
||||||
"grupoServicios": "02",
|
│ │── request.state.user = payload
|
||||||
"codServicio": 706,
|
│◀──── HTML dashboard ──────│
|
||||||
"codPrestador": "540010152002",
|
```
|
||||||
"tipoDocumentoIdentificacion": "CC",
|
|
||||||
"numDocumentoIdentificacion": "27898369",
|
### Middleware (`main.py:48-68`)
|
||||||
"vrServicio": 8000,
|
- Rutas públicas: `/auth/login`, `/auth/register`, `/auth/api/login`, `/static/*`
|
||||||
"valorPagoModerador": 0,
|
- Lee token de: `Cookie: token` → `Authorization: Bearer`
|
||||||
"conceptoRecaudo": "05",
|
- Si inválido y `/api/` → 401 JSON; si HTML → redirect `/auth/login`
|
||||||
"numAutorizacion": null,
|
|
||||||
"idMIPRES": null,
|
### JWT
|
||||||
"codComplicacion": null,
|
- Algoritmo: HS256
|
||||||
"numFEVPagoModerador": null
|
- Clave: `rips-manager-secret-key-change-in-production`
|
||||||
}]
|
- Payload: `{user_id, username}` (sin expiración)
|
||||||
}
|
|
||||||
}]
|
---
|
||||||
}
|
|
||||||
```
|
## 5. Estructuras JSON
|
||||||
|
|
||||||
---
|
### JSON Terceros (17 campos)
|
||||||
|
```json
|
||||||
## Base de datos SQLite (app)
|
{
|
||||||
|
"tipoDocumentoIdentificacion": "CC",
|
||||||
### Tabla `users`
|
"numDocumentoIdentificacion": "27765610",
|
||||||
| Columna | Tipo | Descripción |
|
"primerNombre": "MARIA",
|
||||||
|---|---|---|
|
"segundoNombre": "ELENA",
|
||||||
| id | INTEGER PK | Auto-incrementable |
|
"primerApellido": "GOMEZ",
|
||||||
| username | TEXT UNIQUE | Nombre de usuario |
|
"segundoApellido": "RUIZ",
|
||||||
| email | TEXT UNIQUE | Correo electrónico |
|
"fechaNacimiento": "1954-01-19",
|
||||||
| password_hash | TEXT | Hash bcrypt de la contraseña |
|
"codSexo": "F",
|
||||||
| created_at | TEXT | Fecha de creación |
|
"codEntidadAdministradora": "EPS010",
|
||||||
|
"tipoUsuario": "01",
|
||||||
### Tabla `config`
|
"codPaisResidencia": "170",
|
||||||
| Columna | Tipo | Descripción |
|
"codMunicipioResidencia": "54001",
|
||||||
|---|---|---|
|
"codZonaTerritorialResidencia": "01",
|
||||||
| id | INTEGER PK | Auto-incrementable |
|
"incapacidad": "NO",
|
||||||
| key | TEXT UNIQUE | Clave de configuración |
|
"codPaisOrigen": "170",
|
||||||
| value | TEXT | Valor |
|
"direccionResidencia": "CRA 5 #10-20",
|
||||||
|
"codZonaResidencia": "01"
|
||||||
Claves predefinidas:
|
}
|
||||||
- `firebird_host`, `firebird_port`, `firebird_database`, `firebird_user`, `firebird_password`
|
```
|
||||||
- `api_url`, `api_method`, `api_key`, `api_timeout`
|
|
||||||
- `num_documento_obligado`, `cod_prestador`
|
### JSON Procedimiento (20 campos P01-P20)
|
||||||
|
```json
|
||||||
### Tabla `queries`
|
{
|
||||||
| Columna | Tipo | Descripción |
|
"consecutivo": 1,
|
||||||
|---|---|---|
|
"codProcedimiento": "903841",
|
||||||
| id | INTEGER PK | Auto-incrementable |
|
"fechaInicioAtencion": "2026-06-11 00:00",
|
||||||
| name | TEXT | Nombre descriptivo |
|
"codDiagnosticoPrincipal": "R790",
|
||||||
| query_type | TEXT | `terceros` o `transaccion` |
|
"codDiagnosticoRelacionado": null,
|
||||||
| query_text | TEXT | Sentencia SQL con parámetros |
|
"finalidadTecnologiaSalud": "23",
|
||||||
| description | TEXT | Descripción |
|
"viaIngresoServicioSalud": "02",
|
||||||
| created_at | TEXT | Fecha de creación |
|
"modalidadGrupoServicioTecSal": "01",
|
||||||
|
"grupoServicios": "02",
|
||||||
### Tabla `envios`
|
"codServicio": 706,
|
||||||
| Columna | Tipo | Descripción |
|
"codPrestador": "540010152002",
|
||||||
|---|---|---|
|
"tipoDocumentoIdentificacion": "CC",
|
||||||
| id | INTEGER PK | Auto-incrementable |
|
"numDocumentoIdentificacion": "27898369",
|
||||||
| user_id | INTEGER FK | Usuario que realizó el envío |
|
"vrServicio": 8000,
|
||||||
| tipo | TEXT | `terceros` o `transaccion` |
|
"valorPagoModerador": 0,
|
||||||
| factura | TEXT | Número de factura |
|
"conceptoRecaudo": "05",
|
||||||
| fecha_inicio / fecha_fin | TEXT | Rango de fechas del envío |
|
"numAutorizacion": null,
|
||||||
| pacientes_count / servicios_count | INTEGER | Cantidades |
|
"idMIPRES": null,
|
||||||
| status | TEXT | `success` o `error` |
|
"codComplicacion": null,
|
||||||
| json_enviado | TEXT | JSON completo enviado |
|
"numFEVPagoModerador": null
|
||||||
| respuesta_api | TEXT | Respuesta de la API |
|
}
|
||||||
| codigo_cuv | TEXT | Código CUV (si aplica) |
|
```
|
||||||
| created_at | TEXT | Fecha del envío |
|
|
||||||
|
### JSON Transacción
|
||||||
---
|
```json
|
||||||
|
{
|
||||||
## Parámetros en consultas SQL
|
"numDocumentoIdObligado": "900278729",
|
||||||
|
"numFactura": "LHXC03404",
|
||||||
Las consultas pueden usar estos parámetros que el sistema reemplaza automáticamente:
|
"tipoNota": null,
|
||||||
|
"numNota": null,
|
||||||
| Parámetro | Ejemplo | Uso |
|
"usuarios": [{
|
||||||
|---|---|---|
|
"tipoDocumentoIdentificacion": "CC",
|
||||||
| `:doc_num` | `WHERE doc = :doc_num` | Filtrar por documento de paciente |
|
"numDocumentoIdentificacion": "27765610",
|
||||||
| `:factura` | `WHERE fact = :factura` | Filtrar por número de factura |
|
"codEntidadAdministradora": "EPS010",
|
||||||
| `:fecha_ini` | `WHERE fecha >= :fecha_ini` | Fecha inicio del rango |
|
"tipoUsuario": "12",
|
||||||
| `:fecha_fin` | `WHERE fecha <= :fecha_fin` | Fecha fin del rango |
|
"fechaNacimiento": "1954-01-19",
|
||||||
|
"codSexo": "F",
|
||||||
---
|
"codPaisResidencia": "170",
|
||||||
|
"codMunicipioResidencia": "54001",
|
||||||
## Estructura del proyecto
|
"codZonaTerritorialResidencia": "02",
|
||||||
|
"incapacidad": "NO",
|
||||||
```
|
"consecutivo": 1,
|
||||||
rips_manager/
|
"codPaisOrigen": "170",
|
||||||
├── main.py # Entry point, middleware, rutas
|
"servicios": {
|
||||||
├── requirements.txt # Dependencias Python
|
"procedimientos": [
|
||||||
├── rips_manager.db # SQLite (autogenerado)
|
{ /* procedimiento */ }
|
||||||
├── DOCUMENTACION.md # Este archivo
|
]
|
||||||
├── README.md # Documentación de RIPS
|
}
|
||||||
├── ejemplo_terceros.json # JSON de ejemplo terceros
|
}]
|
||||||
├── ejemplo_transaccion_rips.json # JSON de ejemplo transacción
|
}
|
||||||
├── app/
|
```
|
||||||
│ ├── __init__.py
|
|
||||||
│ ├── auth.py # JWT, bcrypt, get_current_user
|
---
|
||||||
│ ├── database.py # SQLite init y conexión
|
|
||||||
│ ├── models.py # Pydantic models
|
## 6. Flujo de Datos
|
||||||
│ ├── routes/
|
|
||||||
│ │ ├── auth.py # Login, register, logout
|
### Terceros
|
||||||
│ │ ├── dashboard.py # Página principal con stats
|
```
|
||||||
│ │ ├── config.py # Configuración Firebird + API
|
1. Config → leer firebird_host, api_url, etc.
|
||||||
│ │ ├── queries.py # CRUD de consultas SQL
|
2. Firebird → conectar + ejecutar query → filas
|
||||||
│ │ ├── terceros.py # Generar y enviar JSON terceros
|
3. Mapear fila → JSON (generar_terceros)
|
||||||
│ │ ├── transaccion.py # Generar y enviar JSON transacción
|
4. httpx → POST/PUT {api_url}/terceros
|
||||||
│ │ ├── automation.py # Paso 1 + Paso 2 automático
|
5. Guardar en envios (JSON + respuesta)
|
||||||
│ │ └── logs.py # Historial de envíos
|
```
|
||||||
│ ├── services/
|
|
||||||
│ │ ├── firebird_service.py # Conexión y consultas Firebird
|
### Transacción
|
||||||
│ │ ├── json_generator.py # Construcción de JSON RIPS
|
```
|
||||||
│ │ └── api_client.py # Envío HTTP a API externa
|
1. Config → leer Firebird + API
|
||||||
│ └── templates/ # 10 plantillas Jinja2 + Tailwind
|
2. Firebird → ejecutar query → filas
|
||||||
```
|
3. Agrupar por (factura, paciente)
|
||||||
|
4. Cada grupo → JSON (generar_transaccion)
|
||||||
---
|
5. Cada grupo → httpx → {api_url}/transaccion
|
||||||
|
6. Cada envío → log en envios
|
||||||
## Cómo ejecutar
|
```
|
||||||
|
|
||||||
```bash
|
### Automatización
|
||||||
cd /Users/lizandro/Documents/proyectos/rips_manager
|
```
|
||||||
pip3 install -r requirements.txt
|
Paso 1: Terceros
|
||||||
python3 main.py
|
- Query tipo 'terceros' por rango de fechas
|
||||||
```
|
- Deduplicar por documento
|
||||||
|
- Enviar cada uno
|
||||||
Abrir en el navegador: **http://localhost:8080**
|
|
||||||
|
Paso 2: Transacción
|
||||||
---
|
- Query tipo 'transaccion' por mismo rango
|
||||||
|
- Agrupar por factura
|
||||||
## Secuencia para primer uso
|
- Enviar cada grupo agrupado
|
||||||
|
```
|
||||||
1. Abrir http://localhost:8080/auth/register
|
|
||||||
2. Crear usuario y contraseña
|
---
|
||||||
3. Iniciar sesión
|
|
||||||
4. Ir a **Configuración** → configurar Firebird, API, datos del prestador
|
## 7. Parámetros en Consultas SQL
|
||||||
5. Ir a **Consultas SQL** → ajustar las queries a los nombres reales de tablas
|
|
||||||
6. Usar **Terceros**, **Transacción RIPS** o **Automatización**
|
| Parámetro | Ejemplo | Descripción |
|
||||||
|
|---|---|---|
|
||||||
|
| `:doc_num` | `WHERE doc = :doc_num` | Filtrar por documento |
|
||||||
|
| `:factura` | `WHERE factura = :factura` | Filtrar por factura |
|
||||||
|
| `:fecha_ini` | `WHERE fecha >= :fecha_ini` | Fecha inicio |
|
||||||
|
| `:fecha_fin` | `WHERE fecha <= :fecha_fin` | Fecha fin |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Estructura del Proyecto
|
||||||
|
|
||||||
|
```
|
||||||
|
rips_manager/
|
||||||
|
├── main.py # Entry point, middleware, rutas
|
||||||
|
├── requirements.txt # 9 dependencias
|
||||||
|
├── rips_manager.db # SQLite (autogenerado)
|
||||||
|
├── README.md # Documentación de usuario
|
||||||
|
├── DOCUMENTACION.md # Documentación técnica
|
||||||
|
├── ejemplo_terceros.json # JSON ejemplo
|
||||||
|
├── ejemplo_transaccion_rips.json # JSON ejemplo
|
||||||
|
├── arrancar.sh # Inicio macOS/Linux
|
||||||
|
├── run.bat # Inicio Windows (minimizado)
|
||||||
|
├── run.ps1 # Inicio Windows PowerShell
|
||||||
|
├── run.vbs # Inicio Windows (sin ventana)
|
||||||
|
├── stop.bat # Detener servidor
|
||||||
|
├── app/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ ├── auth.py # JWT, bcrypt, get_current_user
|
||||||
|
│ ├── database.py # SQLite init y conexión
|
||||||
|
│ ├── models.py # Pydantic models
|
||||||
|
│ ├── routes/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── auth.py # Login, register, logout
|
||||||
|
│ │ ├── dashboard.py # Estadísticas
|
||||||
|
│ │ ├── config.py # Configuración
|
||||||
|
│ │ ├── queries.py # CRUD + Probador + Constructor
|
||||||
|
│ │ ├── terceros.py # Envío terceros
|
||||||
|
│ │ ├── transaccion.py # Envío transacción
|
||||||
|
│ │ ├── automation.py # Automatización 2 pasos
|
||||||
|
│ │ └── logs.py # Historial
|
||||||
|
│ ├── services/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── firebird_service.py # Conexión y consultas Firebird
|
||||||
|
│ │ ├── json_generator.py # Construcción de JSON RIPS
|
||||||
|
│ │ └── api_client.py # Envío HTTP
|
||||||
|
│ └── templates/
|
||||||
|
│ ├── base.html # Layout (sidebar, Tailwind, CodeMirror, FontAwesome)
|
||||||
|
│ ├── login.html
|
||||||
|
│ ├── register.html
|
||||||
|
│ ├── dashboard.html
|
||||||
|
│ ├── config.html
|
||||||
|
│ ├── queries.html # Probador / Constructor / Editor
|
||||||
|
│ ├── terceros.html
|
||||||
|
│ ├── transaccion.html
|
||||||
|
│ ├── automation.html
|
||||||
|
│ └── logs.html
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Cómo Ejecutar
|
||||||
|
|
||||||
|
### Windows
|
||||||
|
```powershell
|
||||||
|
git clone https://github.com/U-SITE-SAS-BIC/rips_manager.git
|
||||||
|
cd rips_manager
|
||||||
|
powershell -ExecutionPolicy Bypass -File run.ps1
|
||||||
|
```
|
||||||
|
O doble clic en `run.bat` (inicia minimizado).
|
||||||
|
|
||||||
|
### macOS / Linux
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/U-SITE-SAS-BIC/rips_manager.git
|
||||||
|
cd rips_manager
|
||||||
|
chmod +x arrancar.sh
|
||||||
|
./arrancar.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Acceder
|
||||||
|
- Local: `http://localhost:8080`
|
||||||
|
- Red: `http://<IP_LOCAL>:8080`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Primer Uso
|
||||||
|
|
||||||
|
1. Abrir `http://localhost:8080/auth/register`
|
||||||
|
2. Crear usuario y contraseña
|
||||||
|
3. Iniciar sesión
|
||||||
|
4. Ir a **Configuración** → configurar Firebird, API, datos del prestador
|
||||||
|
5. Ir a **Consultas SQL** → ajustar/queries a nombres reales de tablas
|
||||||
|
6. Usar el **Probador** para probar consultas
|
||||||
|
7. Usar **Terceros**, **Transacción RIPS** o **Automatización**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Créditos
|
||||||
|
|
||||||
|
© 2026 **U-SITE SAS BIC** — Todos los derechos reservados.
|
||||||
|
|
||||||
|
- **Web**: [https://u-site.app/](https://u-site.app/)
|
||||||
|
- **Sistema**: RIPS Manager v1.0
|
||||||
|
- **Propósito**: Generación y envío de RIPS según Res. 2275/2023
|
||||||
|
- **Campos cubiertos**: Procedimientos (20 campos P01-P20 del Anexo Técnico 1)
|
||||||
|
|||||||
Reference in New Issue
Block a user