# SAP Business One Service Layer — conexión e inventario

Documento de trabajo (2026-11-16). Resume cómo se conecta BiIbero al Service Layer de SAP, lo que se verificó y lo decidido para la pantalla **Inventario**. Las credenciales y la dirección del servidor **no** se escriben aquí ni en el código: viven solo en el `.env`.

---

## 1. Conexión

| Tema | Detalle |
|---|---|
| API | SAP Business One Service Layer, `https://<servidor>:50000/b1s/v2` (OData v4). Documentación oficial: *Working with SAP Business One Service Layer* (SAP Help, versión 9.3). |
| Variables `.env` | Las mismas que el proyecto **sistemaIbero**: `BASE_URL_SAP`, `COMPANY_DB_SAP`, `USER_SAP`, `PASSWORD_SAP`, `SAP_COOKIE`. Documentadas (vacías) en `.env.example`. |
| Configuración | `config/sap.php` (lee esas variables). Opcionales: `SAP_VERIFICAR_SSL` (por defecto `false`, igual que sistemaIbero: el certificado es autofirmado), `SAP_PAGINA` (filas por página, 500), `SAP_TIMEOUT` (120 s). |
| Cliente | `app/Services/Sap/ServiceLayer.php` — solo lectura. `ServiceLayer::sesion(fn ($sl) => ...)` hace `POST /Login`, ejecuta el trabajo y **siempre** `POST /Logout` (las sesiones abiertas ocupan licencia). Métodos: `get($recurso, $query)` y `todos($coleccion, $query)` (sigue `@odata.nextLink`; usa `Prefer: odata.maxpagesize`). |
| Prueba | `php artisan sap:probar [--articulo=PT000569]` → login, 5 artículos `PT…` con existencia, detalle por almacén de un artículo, lista de almacenes, logout. No muestra credenciales. |

### Reglas
- **Solo lectura.** BiIbero no crea ni modifica nada en SAP. Crear una consulta en `/SQLQueries` es una escritura en producción: solo con aprobación expresa.
- **Nunca** leer ni imprimir el `.env`; las credenciales se usan solo vía `config()`.
- No consultar SAP en cada visita a una pantalla: leer con un proceso programado y guardar una foto en la base local.

### Resultado de la prueba (2026-11-16)
`sap:probar` → **Login correcto**, lectura de artículos y almacenes, sesión cerrada. Conexión OK desde este equipo.

### Referencia: sistemaIbero
- Usa las mismas variables (`config/services.php` → `services.sap.*`) y `Http::withoutVerifying()`.
- `SAP_COOKIE` no es una credencial: es el nombre de la clave de caché donde guarda la sesión (`B1SESSION`).
- Consultas guardadas en SAP que usa (colección Postman): solo `SQLQueries('prom_resumen_ds2')`. No hay ninguna de inventario.

---

## 2. Datos de inventario disponibles en SAP

`GET /Items('<código>')?$select=ItemCode,ItemName,QuantityOnStock,ItemWarehouseInfoCollection`

| Campo | Significado |
|---|---|
| `QuantityOnStock` | Existencia total del artículo (suma de **todos** los almacenes). Puede tener decimales (p. ej. 530.45). |
| `QuantityOrderedFromVendors` | Pedido a proveedores. |
| `QuantityOrderedByCustomers` | Comprometido con clientes. |
| `ItemWarehouseInfoCollection[]` | Por almacén: `WarehouseCode`, `InStock`, `Committed`, `Ordered`. |

### Almacenes (`GET /Warehouses`)
| Código | Nombre |
|---|---|
| 01 | Alimentos y bebidas |
| 02 | Materia prima |
| 03 | Materia prima defectuosas o vencidas |
| 04 | Material de empaque |
| 05 | Material de empaque defectuosos |
| 06 | Muestras médicas |
| 07 | Muestras médicas defectuosas o vencidas |
| 08 | Producto en proceso |
| **09** | **Producto terminado** |
| 10 | Productos terminados defectuosos o vencidos |
| 11 | Productos terminados maquila |
| 12 | Suministros de oficina |
| 13 | Suministros producción |
| 14 | Calidad |
| 15 | Cuarentena |
| 16 | Almacén devoluciones |

---

## 3. El Excel de referencia: *Inventario Productos Terminados.xlsx*

Hoja **Inventario** (400 productos) + hoja **Sheet** (exportación de SAP: Descripción, Código, Existencia; 590 filas).

| Columna | Cómo se obtiene en el Excel |
|---|---|
| CÓDIGO, PRODUCTO | Escritos. |
| EXISTENCIA | `XLOOKUP(código, Sheet!B:B, Sheet!C:C)` → de la exportación de SAP. |
| PROMEDIO DE VENTAS | **Valores escritos a mano** (con decimales, p. ej. 836.778, 771.2085); no hay fórmula. |
| MESES DE EXISTENCIA | `IFERROR(EXISTENCIA / PROMEDIO, "Sin Data")`. |
| PRODUCTOS AGOTADOS (E2) | `COUNTIF(E5:E430, "<=0.1")` → productos con **0.1 meses o menos** (no solo existencia 0). |
| Filas en amarillo | Resaltado manual; no se replica (decisión del usuario). |

### ¿De qué almacén sale la existencia del Excel? → **almacén 09**
Comparación de 21 productos (SAP del 2026-11-16 contra el Excel, que es una foto anterior):

- **Prueba directa:** PT000507 tiene **0.214** en el Excel y hoy **1,558.214** en el almacén 09 (misma fracción .214); el total de todos los almacenes es 2,638.2765. → misma fuente, el 09, con reposición posterior.
- El **almacén 11** (maquila) está en 0 en los 21 productos.
- El total de todos los almacenes incluye el **almacén 10** (defectuosos o vencidos), que en algunos productos es grande y falsearía los meses de existencia:

| Producto | Excel | Almacén 09 hoy | Almacén 10 hoy | Total hoy |
|---|---|---|---|---|
| PT000507 | 0.214 | 1,558.214 | 1,080.06 | 2,638.28 |
| PT000569 | 453 | 2,632 | 1 | 2,633 |
| PT000495 | 476 | 161 | 710 | 872 |
| PT000055 | 1,652 | 1,523 | 3,317.43 | 4,840.43 |
| PT000198 | 4,246 | 3,567 | 1,551.16 | 5,118.41 |
| PT000328 | 5,132 | 5,476 | 431.06 | 5,907.06 |

**Decisión (2026-11-16): la existencia del Inventario = solo almacén 09.** El almacén 10 puede mostrarse aparte como dato informativo.

### Promedio de ventas
Se comparó el promedio del Excel (10 productos) contra la venta en unidades de `public.fact_ventas_sap`:

| Cálculo | Diferencia media vs Excel |
|---|---|
| **3 meses cerrados** (`cantidad`, ago–oct) | **19.3 %** (la más cercana; p. ej. PT000569: 1,664 vs 1,658) |
| 3 meses incluyendo el actual | 24.7 % |
| 6 meses cerrados | 27.7 % |
| 12 meses cerrados | 47.5 % |
| `cantidad_vendida` / `cantidad_total_con_oferta` | > 85 % (no sirven) |

Ninguno coincide exacto (el Excel tiene valores escritos a mano, de otra fecha o fuente). **Propuesta:** promedio de unidades (`cantidad`) de los últimos N meses cerrados, con selector **4 / 6 / 12** (4 por defecto, pedido del usuario). Pendiente confirmar con el usuario de dónde salen los promedios del Excel.

---

## 4. Pantalla Inventario — construida (2026-11-16)

| Pieza | Archivo |
|---|---|
| Tablas `inventario_existencias` (foto) e `inventario_lecturas` (historial) + permiso `inventario.ver` (ejecutivo) | `database/migrations/2026_11_16_170000_create_inventario_existencias_table.php` |
| Lectura de SAP | `app/Services/Sap/ExistenciasSap.php` — consulta cruzada, almacenes 09 y 10 (587 artículos `PT…` en ~2 s con login/logout) |
| Comando | `php artisan sap:inventario` — programado cada hora al minuto 15 (`routes/console.php`; requiere el programador) |
| Pantalla | `/inventario` → `InventarioController` + `resources/js/pages/Inventario.tsx`; menú principal, debajo de Ventas Diarias |

La pantalla muestra: resumen (agotados ≤ 0.1 meses, menos de 1 mes, productos, sin ventas), filtros, buscador, selector de promedio 4/6/12 meses cerrados, tabla ordenada por meses de existencia, almacén 10 como referencia, exportar a Excel y (administradores) "Actualizar desde SAP". Se listan los productos de la tabla **`inventario_productos`** con `mostrar = true` que además estén activos en SAP (447 hoy). Esa tabla se cargó con los 450 códigos del Excel (3 son códigos viejos ya inactivos en SAP). Para mostrar u ocultar un producto: **Administración → Productos → editar → "Pantalla Inventario: Mostrar / Ocultar"** (se guarda al instante), o en SQL `INSERT INTO app.inventario_productos (item_code, mostrar, created_at, updated_at) VALUES ('PT000603', true, now(), now()) ON CONFLICT (item_code) DO UPDATE SET mostrar = true, updated_at = now();`. No usar `inventario_existencias` para esto: es la foto de SAP y se reemplaza cada hora.

### Lecciones del Service Layer
- **No pedir `Items` con `ItemWarehouseInfoCollection` completo:** cada artículo trae los 16 almacenes con decenas de campos (~25 KB; 587 artículos ≈ 15 MB, 19 s y memoria agotada). `$select` no permite elegir campos dentro de esa colección (`Invalid navigation property`). **Solución: consulta cruzada** con `POST /QueryService_PostQuery` (solo lectura) — `QueryPath: $crossjoin(Items,Items/ItemWarehouseInfoCollection)` y `QueryOption: $expand=Items($select=…),Items/ItemWarehouseInfoCollection($select=WarehouseCode,InStock,Committed,Ordered)&$filter=Items/ItemCode eq Items/ItemWarehouseInfoCollection/ItemCode and … WarehouseCode eq '09'` → ~120 KB, 0.3 s (`ServiceLayer::consulta`). En esta consulta `Valid`/`Frozen` llegan como `Y`/`N` (en `GET /Items` como `tYES`/`tNO`).
- **`@odata.nextLink` ya trae el filtro y el `$skip`** (codificados): la página siguiente se pide sin pasar parámetros (pasar `[]` reemplaza la query y repite la primera página sin fin).
- **Siempre `$orderby`** al paginar: sin orden fijo, `$skip` puede devolver un artículo repetido o saltarse otro.
- **Zona horaria (corregido en general el 2026-11-16):** la app estaba en UTC y PostgreSQL en hora local (-04), así que las horas que guardaba Laravel quedaban 4 h adelantadas. Ahora `config/app.php` y las conexiones de `config/database.php` usan `America/Santo_Domingo`; la migración `2026_11_16_180000_corregir_zona_horaria` corrigió lo ya guardado.

## 4.1 Diseño original (referencia)

Decidido con el usuario:
- Nueva opción **Inventario** en el menú principal; acceso **Administrador y CEO/Ejecutivo** (permiso `inventario.ver`).
- Existencia = **almacén 09**; promedio = selector 4/6/12 meses cerrados; meses de existencia = existencia ÷ promedio ("Sin data" si no hay promedio); **agotados = meses ≤ 0.1** (como el Excel).

Diseño propuesto:
1. Tablas locales `inventario_existencias` (código, nombre, existencia 09, comprometido, pedido, vencido 10, leído en) e `inventario_lecturas` (historial de lecturas: estado, productos, duración, error).
2. Comando `php artisan sap:inventario`: una sesión del Service Layer, `GET /Items?$filter=startswith(ItemCode,'PT')&$select=ItemCode,ItemName,ItemWarehouseInfoCollection` paginado, guarda la foto. Programado cada hora en `routes/console.php`.
3. Pantalla `/inventario` (patrón visual de Administración → Usuarios): "Existencias al <fecha>", contador de agotados, buscador, filtros (todos / agotados / menos de 1 mes), tabla ordenada por meses de existencia, paginación, exportar a Excel; botón "Actualizar desde SAP" para administradores.
