apitelematel 0.1.0
API hexagonal para Progress OpenEdge usando Flask y ODBC
Requires Python: >=3.10

# API para Progress OpenEdge

Proyecto inicial para una API que expone consultas a una base de datos Progress OpenEdge a través de ODBC, siguiendo una arquitectura hexagonal en Python y Flask.

## Estructura

- `apitelematel/`: código principal del paquete.
- `tests/`: pruebas unitarias e integradas previstas.
- `scripts/`: utilidades de despliegue y mantenimiento.

## Configuración mínima

1. Clonar el repositorio y crear un entorno virtual.
2. Instalar dependencias: `pip install -r requirements.txt`.
3. Definir variables de entorno en `.env` o el sistema:
   - `SECRET_KEY`: clave secreta compartida para autenticación.
   - `PROGRESS_CONN_STR`: cadena ODBC completa (`DSN=tlmplus;UID=usuario;PWD=pass`), usada como conexión por defecto.
   - `PROGRESS_CONN_<ALIAS>`: cadenas específicas para cada alias (ej. `PROGRESS_CONN_TLMPLUS2=DSN=tlmplus2;...`).
   - Si no quieres usar `PROGRESS_CONN_STR`, puedes definir `PROGRESS_DSN`, `PROGRESS_USER` y `PROGRESS_PASSWORD` para construir una conexión por defecto.
   - `QUERY_TIMEOUT`: timeout para consultas (opcional, por defecto 30 segundos).

## Arranque

Usar el entrypoint expuesto en `pyproject.toml`, ejecutar `flask run` apuntando a `apitelematel.app:create_app` o, en Windows Server, lanzar `scripts\start_api.bat` para exportar el `.env` antes de arrancar `python -m apitelematel`.

## Checklist de despliegue en Windows Server 2012
1. Clonar el repo y crear el virtualenv `python -m venv .venv`, activar y ejecutar `pip install -r requirements.txt`.
2. Crear o actualizar `.env` con `SECRET_KEY`, `PROGRESS_CONN_<ALIAS>` (por ejemplo `TLMPLUS`, `TLMPLUS1`, `TLMPLUS2`), y `QUERY_TIMEOUT`.
3. Ejecutar `scripts\start_api.bat` para cargar el `.env` y lanzar la aplicación en el puerto 5000.
4. Abrir el firewall de Windows para permitir tráfico HTTP/TCP entrante al puerto 5000.
5. Registrar la aplicación como servicio (p.ej. con NSSM o un script programado) que arranque `scripts\start_api.bat`.
6. Monitorear `logs/output.log` o el destino donde apuntes `logging` para capturar errores y accesos.

## Ejemplos de consulta:
curl -X POST http://www.piscinaspepe.com:5000/query   -H "Content-Type: application/json"   -H "X-Secret-Key: me-gusta-la-fruta-como-a-sanchez"   -d '{
    "query": "SELECT c.cod_cli, c.nom_cli FROM PUB.gmclien c WHERE c.cod_cli<=2000 ORDER BY c.cod_cli",
    "max_rows": 1000,
    "connection_key": "TLMPLUS"
  }'

curl -X POST http://www.piscinaspepe.com:5000/query   -H "Content-Type: application/json"   -H "X-Secret-Key: me-gusta-la-fruta-como-a-sanchez"   -d '{
    "query": "SELECT f.num_fac, f.fec_fac, f.cod_cli, f.raz_cli FROM PUB.gvfacab f ORDER BY f.fec_fac",
    "max_rows": 1000,
    "connection_key": "TLMPLUS1"
  }'

curl -X POST http://www.piscinaspepe.com:5000/query   -H "Content-Type: application/json"   -H "X-Secret-Key: me-gusta-la-fruta-como-a-sanchez"   -d '{
    "query": "SELECT f.num_fac, f.fec_fac, f.cod_cli, f.raz_cli FROM PUB.gvfacab f ORDER BY f.fec_fac",
    "max_rows": 100000,
    "connection_key": "TLMPLUS1"
  }'

## Organización por versiones y secciones

- Todas las rutas principales diseñadas actualmente se publican bajo `GET /api/v1.0/...` para diferenciar versiones. `GET /api_v1.0/...` se mantiene como alias compatible para quien todavía use la estructura anterior. Dentro de cada versión, las funcionalidades se organizan por secciones (clientes, facturas, almacén, etc.), lo que permite añadir nuevas versiones o secciones sin romper la API antigua.

## Ruta `/api_v1.0/clientes`
- Método `GET`.
- Parámetros:
  - `cod_cli` (obligatorio): entero que identifica al cliente (usa `0` para listar todos).
  - `connection_key` (opcional): alias del DSN configurado en `.env`.
  - `max_rows`, `timeout`: también se aceptan para controlar la consulta.
- Respuesta: `row` contiene el único cliente si solo hay uno (y `rows` queda vacío); cuando hay múltiples (`row_count > 1`) `rows` tendrá la lista completa y `row` será `{}`.
- Ejemplo:
  ```bash
  curl -G http://www.piscinaspepe.com:5000/api_v1.0/clientes \
    -H "X-Secret-Key: me-gusta-la-fruta-como-a-sanchez" \
    --data-urlencode "cod_cli=5" \
    --data-urlencode "connection_key=TLMPLUS1" \
    --data-urlencode "max_rows=1"
  ```
- También puedes ejecutar `scripts/test_clientes.py` para llamar al endpoint con `--cod_cli`, `--connection_key`, `--max_rows` y `--timeout`.
- Para facturas de venta existe `scripts/test_facturas_venta.py`, que acepta `--num_fac`, `--connection_key`, `--max_rows` y `--timeout`.
- Para probar consultas libres puedes usar `scripts/test_query.py`, que envía un payload JSON a `/query` y admite `query`, `max_rows`, `connection_key`, `url` y `secret`.

## Ruta `/api_v1.0/facturas_venta`
- Método `GET`.
- Parámetros:
  - `num_fac` (entero). Usa `0` para listar las últimas `max_rows` facturas ordenadas por fecha.
  - `connection_key`, `max_rows`, `timeout` (opcional).
- Respuesta: `row` si hay una factura exacta, `rows` con la lista cuando hay varias.
  ```bash
  curl -G http://www.piscinaspepe.com:5000/api_v1.0/facturas_venta \
    -H "X-Secret-Key: me-gusta-la-fruta-como-a-sanchez" \
    --data-urlencode "num_fac=0" \
    --data-urlencode "max_rows=20" \
    --data-urlencode "connection_key=TLMPLUS1"
  ```