# Integración TPV Ágora (local en tienda)

Esta guía describe cómo conectar el TPV Ágora que corre en el PC de la tienda con el sistema Laravel.

## Modos de integración

| Modo | Cuándo usarlo | Requisitos |
|------|---------------|------------|
| **CSV manual** | Prueba rápida, pocos movimientos | Exportar desde Ágora e importar en `/tpv/sales` |
| **Carpeta vigilada** | Exportación programada desde Ágora | Carpeta compartida + `AGORA_EXPORT_FOLDER` |
| **API local** | Sincronización casi automática | Licencia *Módulo Servicios de Integración* |

## Opción 1 — Importación CSV (sin licencia extra)

1. En **Ágora Retail → Informes → Diario de albaranes**, pulsa **Exportar**.
   - Puedes usar listado resumido o extendido (con líneas).
2. Guarda el Excel como **CSV** (delimitador `;` recomendado en España).
3. En la app: **TPV Ágora → Importar ventas**.
4. Elige perfil:
   - `Ventas / histórico` — histórico de ventas
   - `Diario de albaranes` — exportación de albaranes
   - `Genérico` — columnas estándar fecha/total/pago

Columnas reconocidas automáticamente (entre otras): `Fecha`, `Total`, `Forma pago`, `Nº albarán`, `Cliente`, `Base`, `IVA`.

## Opción 2 — Carpeta de exportación automática

1. Crea una carpeta, por ejemplo `C:\AgoraExports`.
2. Programa Ágora (o un script externo) para volcar CSV ahí cada noche.
3. En `.env`:

```env
AGORA_EXPORT_FOLDER=C:/AgoraExports
```

4. El scheduler ejecutará `SyncAgoraSalesJob` cada 15 minutos (configurable con `AGORA_SYNC_CRON`).

## Opción 3 — API del Módulo de Servicios de Integración

Recomendado si tu distribuidor Ágora te ha activado la licencia de integración.

1. **Ágora Monitor → Ayuda → Activar licencia de módulo** → *Servicios de Integración*.
2. Anota URL local, token y (si aplica) ID de restaurante/ local.
3. Configura `.env`:

```env
AGORA_API_ENABLED=true
AGORA_API_URL=http://192.168.X.X:PUERTO
AGORA_API_TOKEN=tu-token
AGORA_RESTAURANT_ID=1
AGORA_SALES_ENDPOINT=/integration/sales
AGORA_SALES_JSON_PATH=sales
```

> El endpoint exacto puede variar según versión y distribuidor. Pide a tu partner Ágora la URL y formato JSON de ventas.

4. Comprueba conectividad:

```bash
php artisan app:agora-health-check
php artisan app:agora-sync --days=7
```

## Qué hace el sistema con los datos

1. **Ventas TPV** (`tpv_sales`) — tickets con importe, IVA, forma de pago, payload original.
2. **Cierres de caja** (`cash_closings`) — totales diarios por efectivo, tarjeta, Bizum, transferencia.
3. **Cuadre TPV vs banco** — compara totales diarios TPV con movimientos bancarios importados.
4. **Trazabilidad** — cada sync deja registro en `integration_runs`.

## Comandos útiles

```bash
php artisan app:agora-health-check
php artisan app:agora-sync --days=14
php artisan queue:work   # necesario para sync en background desde la UI
```

## Red local

- El servidor Laravel puede estar en otro PC de la LAN (como Ollama).
- Ágora debe ser accesible por IP fija o hostname local.
- Abre el puerto de integración en el firewall de Windows del TPV.

## Próximos pasos (roadmap)

Ver `docs/IMPLEMENTATION_PLAN.md` — Fases 5-7.