# Ventix Public API — Contexto para LLMs

> **Cómo usar este archivo:** descargá este `.md` y pegalo o adjuntalo en Claude, ChatGPT, Gemini, Cursor, Windsurf, GitHub Copilot Workspace, etc. cuando vayas a construir una integración con la Ventix Public API. Contiene **toda la información necesaria** para que el modelo escriba código correcto sin alucinar endpoints, tipos ni headers.

---

## SYSTEM CONTEXT

Estás asistiendo a un desarrollador construyendo una integración (tienda online, app móvil, kiosco, marketplace, ERP) con la **Ventix Public API**, la API REST del sistema POS/ERP **Ventix** (Honduras). Es **multi-tenant** (cada API Key apunta a UN tenant; las queries automáticamente se aíslan a sus datos).

La API se divide en seis áreas:

1. **Catálogo (read-only, `GET`)**: productos, categorías, sucursales, stock por sucursal, info de la tienda. Solo requiere `X-API-Key`.
2. **Auth de clientes del ecommerce (`POST`)**: sign-up, verify-email, sign-in, recuperación de contraseña. Solo requiere `X-API-Key`. Devuelve un JWT del cliente al iniciar sesión.
3. **Perfil del cliente (`GET`/`PUT`)**: el cliente logueado consulta y actualiza su propio perfil. Requiere `X-API-Key` **y** `Authorization: Bearer <jwt>`.
4. **Direcciones de envío del cliente (`GET`/`POST`/`PUT`/`DELETE`)**: el cliente logueado gestiona sus direcciones (CRUD + set-default). Requiere `X-API-Key` y `Authorization: Bearer <jwt>`.
5. **Carrito persistente cross-device (`GET`/`POST`/`PUT`/`DELETE`)**: el cliente logueado mantiene un carrito server-side que sigue al usuario entre dispositivos. Precios siempre frescos, valida el disponible al agregar o subir cantidades, TTL 30 días. Requiere `X-API-Key` y `Authorization: Bearer <jwt>`.

6. **Integración ERP/CRM (`GET`/`POST`/`PUT`/`DELETE`)**: consumí el backend completo de Ventix (catálogos, inventario, ventas, compras, contabilidad…) para construir tu propio front-end o integrar tu ERP. Vive bajo `/api/public/v1/integration/…`, requiere el feature `api_access` (Enterprise) y un **scope** `modulo:verbo` por endpoint. La API Key está ligada a un usuario (actúa como él: se aplican sus restricciones de rol y las escrituras se auditan a su nombre, pero **el rol no concede scopes**). Ver la sección **INTEGRACIÓN — ENDPOINTS** abajo.

Bonus: cuando el cliente está logueado y consume `/products` enviando además su JWT, el `salePrice` se devuelve resuelto según la **lista de precios** que el tenant le haya asignado desde el panel admin (CRM → Clientes).

Cuando el dev te pida "construye un endpoint en mi backend que llame a Ventix", "muéstrame los productos", "haz el flujo de registro del cliente", etc., usá el contexto de abajo. **No inventes endpoints, parámetros, headers o campos** — todo lo que necesitás está en este documento.

---

## METADATA

- **Nombre**: Ventix Public API
- **Versión**: v1 (estable)
- **Estado**: Producción
- **Lenguaje del backend**: .NET 10 (Clean Architecture + CQRS), pero los devs consumidores pueden usar cualquier stack
- **OpenAPI 3.0 spec**: `https://ventix-api.smartbusiness.site/swagger/public-v1/swagger.json`
- **Swagger UI interactivo**: `https://ventix-api.smartbusiness.site/swagger`
- **Documentación humana**: `https://app.smartbusiness.site/docs/api`
- **Soporte**: contacto@smartbusiness.site · WhatsApp +504 8838-8768

---

## INTEGRACIÓN — ENDPOINTS (ERP/CRM)

Estos endpoints exponen el backend de Ventix para integraciones headless. Base: `/api/public/v1/integration/`.
Requieren el feature `api_access` (Enterprise) y un **scope** por endpoint. La API Key se liga al usuario que la crea y actúa como él: sus restricciones de rol siguen aplicando y las escrituras se auditan a su nombre, pero **el rol no concede scopes**. Una key de un TenantAdmin sin scopes no puede llamar a ningún endpoint de integración. Sin el scope → `403` con el mensaje `Esta API key no tiene el permiso requerido. Scope: <scope>`.

**Cómo se conceden los scopes:** al crear la key en el panel (*Configuraciones Globales → API Keys → Nueva API Key*) se marcan los permisos por módulo; `inventory:cost:read` marca también `inventory:read`. Los scopes **no se editan** después: para cambiarlos se crea una key nueva con los scopes correctos y se revoca la anterior. Las keys creadas desde el panel antes de que existiera ese selector no tienen scopes de integración. Si un endpoint responde `403` por scope, pedile al administrador del tenant una key nueva que incluya ese scope; no reintentes con la misma key.

Convención de scopes: `modulo:verbo` (`read` / `write`; `write` = create/update/delete). Ej.: `settings:read`, `inventory:read`, `inventory:write`, `invoicing:write`, `reports:read`. Se soportan comodines `modulo:*` y `*`.

### `GET /integration/taxes` — scope `settings:read`
```typescript
interface Tax { id: string; name: string; percentage: number; isDeleted: boolean; deletedAt: string | null; } // Result<Tax[]>
// query: includeDeleted (incluye los eliminados con isDeleted/deletedAt). tambien: GET /integration/taxes/{id}
// Solo lectura: NO expone DELETE ni restore (el delete de impuestos es SuperAdmin en la API interna).
```

### `GET /integration/paymenttypes` — scope `settings:read` (write: `settings:write`)
```typescript
interface PaymentType { id: string; name: string; isActive: boolean; isDeleted: boolean; deletedAt: string | null; } // Result<Paginated<PaymentType>>
// query: pageNumber, pageSize, search, includeDeleted. tambien: GET /integration/paymenttypes/{id}
// POST, PUT/{id}, DELETE/{id} (soft delete: tombstone restaurable), PATCH/{id}/restore (settings:write; 400 si ya existe uno activo con el mismo nombre).
```

### `GET /integration/units` — scope `settings:read` (write: `settings:write`)
```typescript
interface Unit { id: string; name: string; code: string; symbol: string; isGlobal: boolean; allowsDecimals: boolean; isDeleted: boolean; deletedAt: string | null; } // allowsDecimals: unidad de peso o volumen (v2.21) // Result<Paginated<Unit>>
// query: pageNumber, pageSize, search, includeDeleted. tambien: GET /integration/units/global, GET /integration/units/{id}
// POST, PUT/{id}, DELETE/{id} (soft delete), PATCH/{id}/restore, PATCH/{id}/toggle-status (settings:write; nunca tocan las globales; restore 400 si ya existe una activa con el mismo código).
```

### REPORTES (integración) — scopes `reports:read` / `reports:financial:read`

Reportes de negocio del tenant (solo lectura). Base `/api/public/v1/integration/reports`. **Sin paginación**
(cada reporte devuelve el set completo en `data`). Fechas en zona horaria de Honduras (`startDate`/`endDate`
son días locales). Cada reporte tiene variantes `/pdf` y algunas `/excel`.

- `reports:read`: `products-sold`, `sales-by-cashier`, `monthly-sales` (`year`,`month`), `sales-by-department` (`year`,`month`), `tax-totals`, `sales-by-payment-method`, `sales-by-branch`, `customer-analytics`, `accounts-receivable-aging` (sin fechas), `low-stock` y `restock-recommendations` (solo productos: sin servicios ni combos, desde v2.22), `product-catalog` (PDF-only; `priceListId` requerido, `includeImages` default `false` → en `true` el PDF sale como grilla de tarjetas con la foto principal de cada producto, más lento y pesado; `groupByCategory` default `true` → secciones por categoría, con un producto multi-categoría repetido en cada una; en `false` sale una sola lista alfabética sin repetir productos y con la categoría como dato de cada fila).
- `reports:financial:read`: `profit-margins`, `profit-margins-by-invoice`, `inventory-valuation`, `inventory-count`, `slow-moving-inventory` (dead stock / baja rotación; requiere feature **Inventory**).

```typescript
// GET /integration/reports/products-sold?startDate&endDate -> Result<ProductsSoldReport>
interface ProductsSoldReport { totalRevenue: number; items: { productName: string; quantitySold: number; revenue: number; taxCollected: number; averageUnitPrice: number; }[]; }
// GET /integration/reports/tax-totals?startDate&endDate     -> Result<TaxTotalsReport>
// GET /integration/reports/profit-margins?startDate&endDate -> Result<ProfitMarginReport> (costo/margen, venta sin ISV desde v2.25; scope reports:financial:read)
// Shape completo por reporte en el OpenAPI public-v1. Variantes /pdf y /excel devuelven binario.

// GET /integration/reports/slow-moving-inventory -> Result<SlowMovingInventoryReport>
// query: windowDays=90 (1..1095), slowMoverDaysOfSupply=90 (1..3650), includeZeroStock=false, warehouseId?, categoryId?
// scope reports:financial:read (expone costo y capital inmovilizado) + feature Inventory. Variantes /pdf y /excel.
interface SlowMovingInventoryReport {
  windowDays: number; slowMoverDaysOfSupply: number; includeZeroStock: boolean;
  warehouseId: string | null; warehouseName: string | null;
  categoryId: string | null; categoryName: string | null;
  windowStartDate: string; windowEndDate: string;          // UTC; inicio inclusivo, fin exclusivo
  analyzedProducts: number;                                 // universo evaluado
  totalProducts: number;                                    // = items.length
  neverSoldCount: number; noSalesInWindowCount: number; slowMoverCount: number;
  criticalCount: number; highCount: number;
  totalImmobilizedUnits: number; totalImmobilizedCost: number;
  totalPotentialRevenue: number; totalInventoryCost: number;
  immobilizedCostPercentage: number;                        // 0-100
  items: SlowMovingInventoryItem[];
}
interface SlowMovingInventoryItem {
  productId: string; productName: string; barcode: string | null;
  categoryName: string; brandName: string | null; warehouseName: string | null; unitSymbol: string | null;
  stock: number; costPrice: number; salePrice: number;
  immobilizedCost: number;                                  // stock * costPrice — criterio de orden
  potentialRevenue: number;
  unitsSoldInWindow: number; dailyVelocity: number;
  daysOfInventory: number | null;                           // null si no hubo ventas en la ventana
  lastSaleDate: string | null;                              // null = nunca vendido
  daysSinceLastSale: number | null; daysSinceCreated: number;
  rotationStatus: 'NeverSold' | 'NoSalesInWindow' | 'SlowMover';
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
  suggestedAction: 'Liquidate' | 'Promote' | 'Discontinue';
  reason: string;                                           // texto en español, listo para mostrar
}
// Solo productos físicos (servicios y combos excluidos), pero las ventas de un combo se propagan a sus
// componentes. Un producto creado dentro de la ventana y sin ventas se omite (período de gracia).
// Orden: severidad y, dentro de cada nivel, immobilizedCost descendente. Fuente: facturas emitidas
// (estándar + manuales), no el Kardex.
```

### CATÁLOGOS E INVENTARIO (integración) — scopes `catalog:read` / `inventory:read`

Datos maestros para sincronizar un ERP/CRM. Paginación estándar (`pageNumber`, `pageSize`, `search`).

- `catalog:read`: `GET /integration/brands`(+`/{id}`, param `includeDeleted`), `GET /integration/productfamilies`(+`/{id}`, param `includeDeleted`), `GET /integration/pricelists`(+`/{id}`), `GET /integration/pricelists/resolve?productId&customerId`, `POST /integration/pricelists/resolve-batch` (body `{customerId?, productIds[]}`).
- **Soft delete (marcas/familias)**: el `DELETE` es eliminación lógica (tombstone) — desaparecen de listas pero productos y documentos históricos conservan la referencia. `GET ?includeDeleted=true` los incluye (con `isDeleted`/`deletedAt`); `PATCH /integration/brands/{id}/restore` y `PATCH /integration/productfamilies/{id}/restore` (`catalog:write`) los restauran → `Result<Brand>` / `Result<ProductFamily>`; responde `400` si ya existe un registro activo con el mismo nombre (el nombre de un eliminado puede reutilizarse al crear).
- `inventory:read`: `GET /integration/products`(+`/{id}`, +`/{id}/combo-availability`, param `includeDeleted`), `GET /integration/warehouses`(+`/{id}`, +`/{id}/products`, +`/product-availability/{productId}`), `GET /integration/suppliers`(+`/{id}`, +`/import-template`, param `includeDeleted`) — proveedores requieren feature **MultiWarehouse**.
- **Disponible (desde v2.14)**: el producto trae `reservedStock` (unidades apartadas por pedidos del ecommerce, en todos los almacenes) y `availableStock` (`stock − reservedStock`, nunca negativo; en un combo, cuántos alcanzan con lo disponible de sus componentes). Los dos son `null` en los servicios y en las respuestas de escritura (crear, editar, restaurar, activar o imágenes); `reservedStock` también en los combos, porque lo apartado cuenta en sus componentes. **`stock` sigue siendo la existencia física.** En las bodegas, `GET /integration/warehouses/{id}/products` trae `reservedStock`/`availableStock` por producto y `GET /integration/warehouses/product-availability/{productId}` los trae por bodega, más `totalReserved`/`totalAvailable`. `GET /integration/products/{id}/combo-availability` (`?warehouseId=` o `?branchOfficeId=`; sin ellos, el almacén por defecto de la sucursal de la key o del tenant) resta lo apartado de cada componente en la bodega y responde `400` si el `warehouseId` enviado no existe o no es del tenant. Una venta valida contra el disponible (ver **Stock disponible y concurrencia** en VENTAS / FACTURACIÓN).
- **Soft delete (productos)**: `inventory:write`. El `DELETE /integration/products/{id}` es eliminación lógica (tombstone) → `Result<bool>` — el producto desaparece de listas, dropdowns y del storefront pero las facturas, cotizaciones, órdenes/facturas de compra, notas y movimientos de inventario históricos conservan la referencia. `GET ?includeDeleted=true` incluye los eliminados (el `IntegrationProduct` expone `isDeleted`/`deletedAt`); `PATCH /integration/products/{id}/restore` (`inventory:write`) lo restaura "como estaba" (no cambia `isActive`) → `Result<IntegrationProduct>`. Reemplaza el hard-delete anterior.
- **Productos ocultos de extras del restaurante (desde v2.19)**: los productos de servicio que el módulo de restaurante crea para los extras con precio (modificadores, p. ej. «Queso extra») no se listan ni cuentan en `GET /integration/products`, y `GET /integration/products/{id}` responde para ellos lo mismo que para un id inexistente: `200` con `{ "succeeded": true, "message": "El producto no existe o no pertenece a este tenant.", "data": null }`. `GET /integration/products/{id}/combo-availability` responde `400` con ese mismo mensaje. Sus ventas sí aparecen en las facturas y en `products-sold`, como líneas «+ {Opción}».
- **Stock con decimales (desde v2.21)**: el stock es un número. En los productos que el comercio marcó como **«Se maneja por peso o volumen»** (`allowsDecimalQuantities: true`; solo se puede con una unidad de peso o volumen: kg, g, lb, oz, L, mL, gal…) puede tener **hasta 3 decimales** (`12.5`, `10.375`); en todos los demás sigue siendo entero y sale igual que antes (`5`, nunca `5.000`). Aplica a `stock`, `minStock`, `maxStock`, `reservedStock` y `availableStock` del producto y de las bodegas, a `totalStock`/`totalReserved`/`totalAvailable` de `product-availability` y al `stock` de las secciones. `virtualStock` y el `availableStock` de un combo siguen siendo enteros: cuentan combos, no gramos. Parseá estos campos como número decimal, no como entero.
- **Soft delete (proveedores)**: `inventory:write`. El `DELETE /integration/suppliers/{id}` es eliminación lógica (tombstone) → `Result<Guid>` — el proveedor desaparece de listas pero las órdenes de compra, facturas de compra y entradas de inventario históricas conservan la referencia. `GET ?includeDeleted=true` incluye los eliminados (el `Supplier` expone `isDeleted`/`deletedAt`); `PATCH /integration/suppliers/{id}/restore` (`inventory:write`) lo restaura → `Result<Supplier>`; responde `400` si ya existe un proveedor activo con el mismo nombre (el nombre de un eliminado puede reutilizarse al crear).

```typescript
// GET /integration/products -> Result<Paginated<IntegrationProduct>>  (SIN costo)
interface IntegrationProduct {
  id: string; name: string; type: number; salePrice: number; offerPrice: number | null;   // type: 1 Product, 2 Service, 3 Combo
  isOnOffer: boolean; stock: number; virtualStock: number | null;   // stock = existencia física; virtualStock = combos con la existencia de sus componentes, sin restar lo apartado (0 en un combo solo de servicios)
  reservedStock: number | null;   // apartado por pedidos (todos los almacenes); null en servicios, combos y respuestas de escritura (v2.14)
  availableStock: number | null;  // stock − reservedStock, nunca negativo; en combos, cuántos alcanzan (null si es solo de servicios); null en servicios y respuestas de escritura (v2.14)
  brandId: string | null; brandName: string | null;
  productFamilies: { id: string; name: string }[];
  taxId: string; taxName: string; taxPercentage: number;
  unitOfMeasurementSymbol: string | null; isActive: boolean; isDeleted: boolean; deletedAt: string | null;
  allowsDecimalQuantities: boolean;   // «Se maneja por peso o volumen»: stock y cantidades con hasta 3 decimales (v2.21). Se manda en POST/PUT; solo con una unidad que tenga allowsDecimals
  barcodes: { code: string; isPrimary: boolean }[]; images: { url: string; isPrimary: boolean }[];
  comboComponents: { componentProductId: string; componentName: string; quantity: number; salePrice: number }[];
  // NO incluye costPrice (ni en comboComponents).
}
interface Warehouse { id: string; name: string; branchOfficeName: string; isDefault: boolean; isActive: boolean; }
interface WarehouseProduct { id: string; warehouseId: string; warehouseName: string; productId: string; productName: string; stock: number; reservedStock: number | null; availableStock: number | null; minStock: number | null; maxStock: number | null; } // GET /integration/warehouses/{id}/products: reservedStock = apartado por pedidos en esa bodega; availableStock = stock − reservedStock, nunca negativo (v2.14)
// GET /integration/warehouses/product-availability/{productId} -> Result<ProductAvailability> (totales = suma de las bodegas; cada availableStock se recorta en 0 antes de sumar)
interface ProductAvailability { productId: string; productName: string; totalStock: number; totalReserved: number; totalAvailable: number; warehouseStocks: { warehouseId: string; warehouseName: string; branchOfficeId: string; branchOfficeName: string; stock: number; reservedStock: number; availableStock: number; isFromCurrentBranch: boolean }[]; }
interface ResolvedPrice { productId: string; priceListName: string; isDefaultList: boolean; price: number; hasPrice: boolean; }
interface Supplier { id: string; name: string; rtn: string | null; email: string | null; phoneNumber: string | null; isActive: boolean; isDeleted: boolean; deletedAt: string | null; }
interface Brand { id: string; name: string; logoUrl: string | null; isDeleted: boolean; deletedAt: string | null; }
interface ProductFamily { id: string; name: string; isDeleted: boolean; deletedAt: string | null; }
```

### MOVIMIENTOS DE INVENTARIO Y KARDEX (integración) — scopes `inventory:read` / `inventory:write` / `inventory:cost:read`

Operaciones transaccionales. Los writes se auditan al usuario ligado a la key. El costo/valuación aparece
solo con `inventory:cost:read` (si no, los campos de costo van en `null`); las entradas aceptan `unitCost`
como input al crear.

- **Entradas** `inventory:write` (MultiWarehouse): `GET /integration/inventoryentries`(+`/{id}`), `POST`, `PUT /{id}`, `PATCH /{id}/confirm`, `PATCH /{id}/cancel`.
- **Salidas** `inventory:write` (Inventory; usuario admin/manager): `GET /integration/inventoryexits`(+`/{id}`, +`/{id}/pdf`), `POST`, `PUT /{id}`, `PATCH /{id}/confirm`, `PATCH /{id}/cancel`.
- **Traslados** `inventory:write` (MultiWarehouse): `GET /integration/warehousetransfers`(+`/{id}`, +`/{id}/pdf`), `POST`, `PUT /{id}`, `DELETE /{id}`, `POST /{id}/send|receive|complete|cancel`.
- **Kardex** `inventory:read` (Inventory): `GET /integration/kardex/{productId}`(+`/pdf`, +`/excel`) — params `warehouseId`, `startDate`, `endDate`, `includeCancelled`, `movementTypes`. Sin `movementTypes`, `openingBalance.quantity + summary.totalIn − summary.totalOut = closingBalance.quantity`. Con `includeCancelled=false` se ocultan juntos la venta de un documento anulado y su reversa; si el original es anterior al período, la reversa se muestra. Sin `warehouseId`, `closingBalance` suma todas las bodegas (desde v2.23).
- **Writes de catálogo**: `POST/PUT/DELETE /integration/products`(+`/{id}/toggle`, +`/{id}/restore`) `inventory:write` (el DELETE de productos es soft delete restaurable — ver CATÁLOGOS); `POST/PUT/DELETE /integration/brands` y `/integration/productfamilies` `catalog:write` (el DELETE de marcas/familias es soft delete; restaurar con `PATCH /{id}/restore` — ver CATÁLOGOS). Imágenes de producto, logo de marca y bulk-import (productos/proveedores) por multipart — ver ARCHIVOS Y MULTIPART.
- **Cantidades con decimales (desde v2.21)**: las cantidades de entradas, salidas y traslados (`quantity`, `quantityRequested`, `quantitySent`, `quantityReceived`) y el stock y mínimo/máximo de productos y bodegas aceptan **hasta 3 decimales solo en productos que se manejan por peso o volumen**. En un producto entero, una cantidad con decimales (también `1.0`) responde `400` con `errors: ["'{Producto}' se maneja en unidades enteras: la cantidad no puede tener decimales."]`, igual que antes, cuando esos campos eran enteros. Se valida antes que el stock: una cantidad con decimales nunca vuelve como «Stock insuficiente». Las respuestas traen esas cantidades como número: entero en los productos enteros (`10`) y con hasta 3 decimales en los demás (`12.5`).
- **Documentos de venta y compra con productos por peso o volumen (desde v2.21)**: las líneas de factura, factura manual, nota, cotización y orden de compra guardan la cantidad con 2 decimales. En un producto por peso o volumen la cantidad admite **hasta 2 decimales** (más responde `400`: «'{Producto}': la cantidad admite hasta 2 decimales en una factura.»). Los productos enteros no cambian: esas líneas ya aceptaban decimales.

```typescript
// POST /integration/inventoryentries  (crear entrada; luego PATCH /{id}/confirm -> mueve stock + Kardex + precios)
interface CreateInventoryEntryItem {
  productId: string; quantity: number; unitCost?: number; notes?: string;
  // Precio de venta: intencion capturada en el borrador, aplicada AL CONFIRMAR contra el costo ya recalculado.
  newSalePrice?: number | null;        // lista por defecto, en la convencion del tenant (bruto si priceIncludesTax)
  newSaleMarginPercent?: number | null;// solo si company.pricingMode === 'MarginPercent'; precede a newSalePrice
  listPrices?: { priceListId: string; price?: number | null; marginPercent?: number | null }[]; // otras listas
}
interface CreateInventoryEntry { entryType: number; entryDate: string; warehouseId: string; supplierId?: string; supplierReference?: string; notes?: string; items: CreateInventoryEntryItem[]; }

interface InventoryEntryItemPrice { priceListId: string; priceListName: string; newPrice: number | null; newMarginPercent: number | null; previousPrice: number | null; appliedPrice: number | null; appliedAt: string | null; currentPrice: number | null; }
interface InventoryEntryItem {
  id: string; productId: string; productName: string; quantity: number; unitCost: number | null; notes: string | null;
  newSalePrice: number | null; newSaleMarginPercent: number | null;
  previousSalePrice: number | null; appliedSalePrice: number | null; salePriceAppliedAt: string | null;
  costPrice: number | null; currentSalePrice: number; taxPercentage: number;
  listPrices: InventoryEntryItemPrice[];
}
interface AppliedPriceChange { productId: string; productName: string; priceListId: string | null; priceListName: string | null; isDefaultList: boolean; previousPrice: number | null; newPrice: number; marginPercent: number | null; taxPercentage: number; }
interface InventoryEntry { id: string; entryNumber: string; status: number; warehouseName: string; items: InventoryEntryItem[]; appliedPriceChanges: AppliedPriceChange[]; notRevertedPrices: string[]; }

// unitCost/costPrice/*marginPercent/totalValue/kardex valorizado = null salvo con inventory:cost:read
// (margen + precio permiten deducir el costo).
//
// Formula del precio segun la config del tenant (company.pricingMode x company.priceIncludesTax):
//   Manual            -> se persiste el precio tal cual se envia
//   MarginPercent     -> costo * (1 + margen/100)              si priceIncludesTax = false
//   MarginPercent     -> costo * (1 + margen/100) * (1 + isv/100)  si priceIncludesTax = true
// Ej: costo 100, ISV 15%, margen 30% -> se guarda 149.50 (neto 130.00, margen real 30%).
//
// Un priceListId que apunte a la lista POR DEFECTO se rechaza (400): esa va en newSalePrice.
// Si el producto no tenia fila en la lista por defecto, el confirm la CREA.
// Al cancelar, los precios se revierten SOLO si nadie los cambio despues del confirm;
// los que no, vuelven en notRevertedPrices.
```

### CRM (integración) — scopes `crm:read` / `crm:write`

Clientes, notas de crédito/débito, abonos (saldo a favor), cuentas por cobrar. Writes auditados al usuario de la key.

- **Clientes** `/integration/customers`: GET(+`/{id}`, +`/{id}/summary`, +`/import-template`, param `includeDeleted`), POST, PUT/{id}, PATCH/{id}/credit, DELETE/{id}, PATCH/{id}/restore, POST/bulk-import (import Excel, multipart).
- **Soft delete (clientes)**: el `DELETE /integration/customers/{id}` (`crm:write`) pasó de hard-delete a eliminación lógica (tombstone) y ahora audita — el cliente desaparece de listas pero las facturas, notas, abonos y pedidos históricos conservan la referencia. Para **clientes de ecommerce** además **bloquea el login del storefront** (signin/signup/reset lo tratan como inexistente; el email queda reutilizable para un signup nuevo). `GET ?includeDeleted=true` incluye los eliminados (el `Customer` expone `isDeleted`/`deletedAt`); `PATCH /integration/customers/{id}/restore` (`crm:write`) lo restaura → `Result<Customer>`; responde `400` si ya existe un cliente activo con el mismo email o RTN.
- **Cuentas por cobrar** `/integration/accountsreceivable`: GET(+`/{customerId}`, +`/{customerId}/pdf`).
- **Notas de crédito** `/integration/customernotes`: GET(+`/{id}`, +`/customer/{customerId}`, +`/customer/{customerId}/credit-balance`, +`/{id}/pdf`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status. `POST` responde `400` si la factura original proviene de un pedido de PedidosYa (las NC/ND de esas facturas todavía no están disponibles).
- **NC sobre factura con propina** (desde v2.17): la propina sigue al consumo. Una NC **total** (las NC emitidas cubren todo el `total`) perdona la propina no cobrada (baja `tipAmount` y `outstanding`) y devuelve la cobrada como saldo a favor (`tipForgivenAmount` / `tipRefundedAmount` en la nota). Una NC parcial no toca la propina y nunca la paga: se aplica solo contra el consumo pendiente. Anular la nota lo deshace.
- **Estado de cuenta** (desde v2.17): cada factura trae `total`, `adjustments`, `tipAmount`, `amountToCollect`, `paid` y `outstanding` (`amountToCollect − paid = outstanding`); `paid` es la suma de pagos (antes `total − outstanding`, que con propina daba negativo). `totalOriginal` suma `amountToCollect`.
- **Abonos** `/integration/customeradvancepayments`: GET(+`/{id}`, +`/by-customer/{customerId}`, +`/{id}/pdf`), POST, PUT/{id}, PATCH/{id}/cancel, POST/{id}/attachment, DELETE/{id}/attachment. (Refund fuera de esta versión; adjunto multipart disponible.)

```typescript
interface Customer { id: string; firstName: string; lastName: string; rtn?: string; company?: string; email?: string; phoneNumber?: string; creditEnabled: boolean; creditLimit: number; isActive: boolean; isDeleted: boolean; deletedAt: string | null; }
interface CustomerNote { id: string; noteType: number; status: number; noteNumber: string; originalInvoiceNumber: string; customerName: string; total: number; appliedToInvoice: number; creditGenerated: number; tipForgivenAmount: number; tipRefundedAmount: number; items: { productName: string; quantity: number; unitPrice: number; totalLine: number }[]; }
interface AdvancePayment { id: string; advancePaymentNumber: string; customerName: string; amount: number; paymentTypeName: string; status: number; hasAttachment: boolean; attachmentUrl?: string; refundedAmount?: number; }
// Emitir NC: PATCH /customernotes/{id}/status {newStatus:1} -> aplica a la factura + genera saldo a favor.
// Abonos en efectivo dependen de sesión de caja POS; usar método NO-efectivo en integraciones headless.
```

### VENTAS / FACTURACIÓN (integración) — scopes `sales:read` / `sales:write`, `invoicing:read` / `invoicing:write`

Cotizaciones, facturas (documento fiscal CAI), pagos de factura y CAIs. Facturación es core (sin feature gate propia). Writes auditados al usuario de la key. DTOs filtrados: sin user-ids internos, sin `accessToken` de portal (cotización), sin URL de adjunto ni `cardAuthorizationCode` (pagos); el costo por línea nunca se expone. Visibilidad tenant-wide.

- **Cotizaciones** `/integration/quotations`: GET(+`/{id}`, +`/{id}/pdf`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status. (`generate-link` y comentarios del portal fuera de esta versión.)
- **Facturas** `/integration/invoices`: GET(+`/{id}`, +`/{id}/pdf`, +`/{id}/receipt`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status.
- **Pagos de factura** `/integration/invoicepayments`: GET`?invoiceId=`(+`/{id}/receipt`), POST, PUT/{id}, DELETE/{id}, POST/{id}/attachment, DELETE/{id}/attachment. (Adjunto multipart disponible; el DTO expone `hasAttachment` + `attachmentUrl`.)
- **Facturas de PedidosYa**: una factura generada desde un pedido de PedidosYa solo se gestiona desde ese pedido: `PUT /invoices/{id}`, `DELETE /invoices/{id}`, `PATCH /invoices/{id}/status` y `PUT /invoicepayments/{id}` sobre sus pagos responden `400` (para corregir un pago, eliminarlo y registrarlo de nuevo).
- **Facturas de cuentas de restaurante** (desde v2.15): nacen **emitidas** (sin borrador) y pueden llevar **propina**, que no es base gravable: no suma a `total` pero sí a `outstanding`. `PUT /invoices/{id}` responde `400` (para corregirla, anularla: la cuenta vuelve a *Por cobrar*); `PATCH /invoices/{id}/status` a Emitida sobre una ya emitida responde `200` sin cambios.
- **Propina en la factura** (desde v2.17): `tipAmount` (propina efectiva: la emitida menos lo que perdonó una NC total) y `amountToCollect` (`total` + notas de débito + `tipAmount`). Siempre `outstanding = amountToCollect − pagos`.
- **Reintentar sin duplicar: `Idempotency-Key`** (desde v2.24): header opcional en `POST /invoices` (hasta 64 caracteres: letras, números y `. _ : -`; por ejemplo el id del documento en tu sistema). Si un timeout o un `5xx` te deja sin saber si la factura se creó, reintentá con la **misma** clave: si ya existía, responde `200` con esa factura (mismo `id` y `invoiceNumber`) y el `message` "La factura ya se había creado con esta clave de idempotencia.", sin consumir otro correlativo del CAI ni descontar stock otra vez. La misma clave con otro cliente u otras líneas (producto y cantidad) responde `400` con el número de la factura que la tiene. La clave no vence y es por empresa. Sin el header, cada `POST` crea una factura nueva.
- **Forma de pago** (desde v2.16): el `paymentTypeId` de `POST /invoices` y `PUT /invoices/{id}` tiene que ser una forma de pago del comercio; si no, `400` ("La forma de pago no existe."). Antes se aceptaba cualquier id.
- **Stock disponible y concurrencia**: crear una factura valida contra el **disponible** (existencia del almacén menos lo apartado por otros documentos; las reservas del propio pedido que se factura sí cuentan). Crear, anular o eliminar una factura serializa las operaciones del mismo producto: si el inventario está ocupado más de 5 s responde `400` "El inventario de uno de los productos se está actualizando en otra operación. Intente de nuevo en unos segundos." — transitorio, **reintentar**. Facturar un pedido responde `400` "El pedido cambió de estado mientras se facturaba" si se canceló o facturó mientras tanto.
- **Borrar un borrador = anularlo**: el borrador ya consumió un correlativo del CAI, así que `DELETE /invoices/{id}` no borra la fila: la deja `Anulada` con su número, devuelve el stock (reverso en Kardex), revierte el asiento y la desvincula del pedido o la cotización de origen (se pueden volver a facturar). Si era el borrador de una **cuenta de restaurante**, la cuenta vuelve a *Por cobrar* (desde v2.15; antes respondía `400`).
- **Anular** (`PATCH /invoices/{id}/status` → Anulada) devuelve el stock, el efectivo (con sesión de caja abierta) y el **saldo a favor** usado en sus pagos (un borrador anulado también se desvincula de su pedido o cotización; una factura de **cuenta de restaurante**, emitida o borrador, se desvincula y la cuenta vuelve a *Por cobrar* para refacturarla, desde v2.15); responde `400` si la factura tiene notas de crédito o débito emitidas (anularlas primero). En una factura anulada, `PUT /invoicepayments/{id}` responde `400` y `DELETE /invoicepayments/{id}` responde `400` para los pagos que la anulación ya devolvió (saldo a favor, o efectivo con caja abierta); los de tarjeta o transferencia se pueden eliminar para revertir su cobro.
- **CAIs** `/integration/cai`: GET(+`/{id}`, +`/active`, param `includeDeleted`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/restore, PATCH/{id}/toggle. El DELETE es **soft delete** (las facturas emitidas conservan la referencia fiscal; los defaults de sucursal se desasocian; el código queda reutilizable). `PATCH /{id}/restore` lo restaura **desactivado** (400 si ya existe un CAI activo con el mismo código). `currentCorrelative` es el **último** número usado: el siguiente documento sale con `currentCorrelative + 1` y quedan `finalCorrelative - currentCorrelative`. Al crear, `startingCorrelative` (opcional) es el último número del rango ya usado (por ejemplo, en otro sistema); sin él, el primer documento sale con `initialCorrelative` (desde v2.20).

```typescript
interface Cai { id: string; name: string; code: string; fromDate: string; toDate: string; initialCorrelative: number; finalCorrelative: number; currentCorrelative: number; prefix: string; isActive: boolean; fiscalDocumentType: number; }
interface Quotation { id: string; quotationCode: string; customerId: string; customerName: string; subTotal: number; tax15: number; tax18: number; total: number; status: number; invoiceNumber?: string; items: { productName: string; quantity: number; unitPrice: number; taxPercentage: number; totalLine: number }[]; }
interface Invoice { id: string; caiId: string; caiCode: string; invoiceNumber: string; customerId: string; customerName: string; subTotal: number; tax15: number; tax18: number; total: number; tipAmount: number; amountToCollect: number; outstanding: number; status: number; items: { productId?: string; productName: string; quantity: number; unitPrice: number; taxId: string; taxPercentage: number; totalLine: number }[]; }
interface InvoicePayment { id: string; invoiceId: string; invoiceNumber: string; paymentTypeName: string; paymentDate: string; amount: number; reference?: string; cardLastFourDigits?: string; }
// Crear factura: POST /invoices {caiId, customerId, items:[{productName, unitPrice, quantity, taxId}]} -> Draft (status 0), consume correlativo CAI + descuenta stock. isPos se fuerza a false.
// Mandar siempre el header Idempotency-Key: <id del documento en tu sistema> y reintentar timeouts/5xx con la misma clave.
// Emitir: PATCH /invoices/{id}/status {newStatus:1}. Registrar pago: POST /invoicepayments {invoiceId, paymentTypeId, paymentDate, amount} baja outstanding.
// paymentDate (desde v2.18) se interpreta en hora de Honduras: "YYYY-MM-DD" tal cual; un instante UTC ("…Z") se convierte a UTC−6 antes.
// Si es hoy, el pago queda con la hora actual; otro día, al mediodía hondureño.
// Descubrir CAI vigente: GET /cai/active. Pagos en efectivo pueden requerir caja abierta -> usar método NO-efectivo.
```

### ECOMMERCE (integración) — scopes `sales:read` / `sales:write` (feature `ecommerce`)

Pedidos del storefront y secciones especiales (agrupaciones curadas de productos). DTOs filtrados: sin user-ids internos ni notas internas; el costo nunca se expone.

- **Pedidos** `/integration/orders`: GET(`?search`, `?status`)(+`/{id}`), PATCH/{id}/status, PATCH/{id}/payment-link, PATCH/{id}/confirm-payment. No se crean/borran por API (nacen del carrito); solo se gestionan. Cambiar estado NO factura ni mueve el kárdex, pero SÍ mueve la **reserva de stock** del pedido: Accepted/Processing la renuevan (si venció, vuelve a apartar si hay disponible; si no, el estado cambia igual y el `message` lo advierte) y Cancelled la libera. **Cancelar → `400` si el pedido tiene factura vigente** (anularla primero); **Shipped → `400` si tiene productos y nunca se facturó** (vale una factura del pedido aunque después se haya anulado). `confirm-payment` marca el pago recibido (`paymentConfirmedAt`, idempotente, `400` si está cancelado) y deja la reserva sin vencimiento. Para facturar un pedido: `POST /integration/invoices` con `orderId` (consume la reserva).
- **Secciones especiales** `/integration/specialsections`: GET(+`/{id}`), POST, PUT/{id}, DELETE/{id}, PUT/reorder, POST/{id}/products, DELETE/{id}/products/{itemId}, PUT/{id}/products/reorder, POST/{id}/banner, DELETE/{id}/banner, POST/{id}/banner/mobile, DELETE/{id}/banner/mobile. CRUD por JSON; el banner (imagen) se sube por multipart. El banner móvil es opcional (si falta se usa el de escritorio) y `DELETE /{id}/banner` quita ambas variantes; el encuadre de escritorio va en `bannerFocalX`/`bannerFocalY` del PUT. Los reorder requieren el conjunto completo de ids.
- **Carruseles** `/integration/carousels`: contenedor CRUD por JSON + slides (imagen) por multipart — ver ARCHIVOS Y MULTIPART.

```typescript
interface Order { id: string; orderCode: string; customerId: string; customerName: string; customerEmail?: string; status: number; total: number; paymentLink?: string; paymentProofUrl?: string; paymentConfirmedAt?: string | null; reservationState: 0 | 1 | 2 | 3 | 4; reservationExpiresAt?: string | null; invoiceId?: string; invoiceNumber?: string; items: { productId?: string; productName: string; quantity: number; unitPrice: number; totalLine: number; warehouseId?: string | null }[]; }
// reservationState: 0 None, 1 Active (con reservationExpiresAt = hasta cuándo, UTC; null = no vence), 2 Expired (pedido sigue abierto), 3 Released (cancelado, enviado o liberado a mano: mirá status), 4 Consumed (facturado).
interface SpecialSection { id: string; title: string; subtitle?: string; description?: string; bannerImageUrl?: string; mobileBannerImageUrl?: string | null; bannerFocalX: number; bannerFocalY: number; displayOrder: number; isActive: boolean; products: { id: string; productId: string; displayOrder: number; productName: string; salePrice: number; stock: number }[]; }
// Transiciones de pedido: Pending->Accepted/Cancelled, Accepted->Processing/Cancelled, Processing->Shipped/Cancelled, Shipped->Delivered.
```

### FACTURACIÓN MANUAL (integración) — scopes `invoicing:read` / `invoicing:write` (feature `manual_invoicing`)

Facturas de talonario físico pre-impreso (CAI manual autorizado por la SAR). DTOs filtrados: sin user-ids ni `tenantId`, sin costo.

- **CAI manual** `/integration/manualcai`: GET(`?branchOfficeId`, `?onlyActive`)(+`/{id}`), POST, PUT/{id}, PATCH/{id}/status, DELETE/{id}. No se borra si ya emitió facturas.
- **Factura manual** `/integration/manualinvoice`: GET(+`/{id}`), POST, PUT/{id}, PATCH/{id}/cancel.

```typescript
interface ManualCai { id: string; caiNumber: string; branchOfficeId: string; prefix: string; rangeFrom: number; rangeTo: number; currentCorrelative: number; remainingCorrelatives: number; fromDate: string; issueLimitDate: string; status: number; isActive: boolean; }
interface ManualInvoice { id: string; manualCaiId: string; invoiceNumber: string; correlative: number; issueDate: string; customerId: string; customerName: string; subTotal: number; tax15: number; total: number; outstanding: number; status: number; items: { productName: string; quantity: number; unitPrice: number; taxId: string; totalLine: number }[]; }
// El integrador PROVEE el correlative (del talonario), validado contra el rango del ManualCai. Se crea Issued, descuenta stock. Solo editable sin pagos.
```

### COMPRAS (integración) — scopes `purchasing:read` / `purchasing:write` (feature `purchasing`)

Ciclo de compras: órdenes de compra, facturas de compra, pagos a proveedor, cuentas por pagar, notas de proveedor. El costo de compra es dato legítimo del tenant (se expone); se omiten user-ids internos y la URL de adjuntos.

- **Órdenes de compra** `/integration/purchaseorders`: GET(+`/{id}`, +`/{id}/pdf`, +`/by-supplier/{supplierId}`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status. Aprobar (Draft→Sent→Approved) NO factura ni mueve stock.
- **Facturas de compra** `/integration/purchaseinvoices`: GET(+`/{id}`, +`/by-purchase-order/{poId}`, +`/by-supplier/{supplierId}`, +`/{id}/pdf`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status. Consume correlativo FC; NO mueve stock ni postea al crear: el asiento (opt-in del tenant) se genera al pasar a Received. El número del proveedor es único por proveedor (sin contar canceladas). Pagos requieren estado Received.
- **Pagos de compra** `/integration/purchaseinvoicepayments`: GET`?purchaseInvoiceId=`, POST, PUT/{id}, DELETE/{id}, POST/{id}/attachment, DELETE/{id}/attachment. Baja `outstanding`; soporta "Saldo a Favor"; sin caja. Adjunto multipart disponible (`hasAttachment` + `attachmentUrl`).
- **Cuentas por pagar** `/integration/accountspayable`: GET(+`/{supplierId}`, +`/{supplierId}/pdf`, +`/{supplierId}/summary`).
- **Notas de proveedor** `/integration/suppliernotes`: GET(+`/{id}`, +`/supplier/{supplierId}`, +`/supplier/{supplierId}/credit-balance`, +`/{id}/pdf`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/status.

```typescript
interface PurchaseOrder { id: string; purchaseOrderCode: string; supplierId: string; supplierName: string; subTotal: number; tax15: number; total: number; status: number; items: { productId?: string; productName: string; quantity: number; unitPrice: number; taxId: string; totalLine: number }[]; }
interface PurchaseInvoice { id: string; purchaseInvoiceCode: string; supplierCaiCode?: string; supplierInvoiceNumber: string; supplierId: string; supplierName: string; purchaseOrderId?: string; subTotal: number; tax15: number; total: number; outstanding: number; status: number; invoiceDate: string; }
interface PurchaseInvoicePayment { id: string; purchaseInvoiceId: string; paymentTypeName: string; paymentDate: string; amount: number; reference?: string; }
interface SupplierNote { id: string; noteCode: string; noteType: number; status: number; supplierNoteNumber: string; originalPurchaseInvoiceCode: string; supplierName: string; total: number; appliedToInvoice: number; creditGenerated: number; }
// Crear FC: POST /purchaseinvoices {supplierId, supplierInvoiceNumber, invoiceDate, exempt, taxableAmount15, tax15, ...} (header-only, sin items). PATCH /status a Received (genera el asiento) antes de pagar.
```

### CONTABILIDAD (integración) — scopes `accounting:read` / `accounting:write` (feature `accounting`)

Lectura de la contabilidad + sincronización del plan de cuentas. La contabilidad se puebla por posteo automático de ventas/compras (ya expuestas); el foco es leer para conciliar. Las escrituras contables (opt-in del motor, asientos, cierre) se difieren; el único write es el CRUD del catálogo de cuentas.

- **Catálogo de cuentas** `/integration/ledgeraccounts`: GET(+`/tree`, +`/{id}`, +`/import-template`), POST, PUT/{id}, DELETE/{id}, POST/import (import Excel, multipart) (`accounting:write`).
- **Config contable** `/integration/accountingsettings`: GET (settings, incluye `requireAutoEntryApproval`), GET/mappings.
- **Libro diario** `/integration/journalentries`: GET(`?search&fromDate&toDate&status&automatic`)(+`/{id}`). DTO sin PostedBy/CreatedBy; expone `source` (Manual vs automático). `automatic=true` solo los generados por documentos, `false` solo los manuales.
- **Aprobación (ADR-0048)**: con `requireAutoEntryApproval=true` (por defecto) los asientos automáticos nacen en borrador (`status=1`, sin `entryNumber`) y no entran en los reportes hasta que el tenant los contabiliza en el panel. Para conciliar, lee `status=2`; la bandeja de pendientes es `status=1&automatic=true`. Anular el documento antes de aprobar descarta el borrador (sin reversa). También se asientan los abonos de clientes (`source=13`, contra Anticipos de clientes), el saldo a favor aplicado, el excedente de una NC y las facturas manuales con sus pagos; con `autoPostInventoryEntries`, los ajustes y el inventario inicial cargados con entradas de inventario (las de compra no: las reconoce la factura de compra).
- **Períodos fiscales** `/integration/fiscalperiods`: GET/years, GET/current(`?date`).
- **Reportes contables** `/integration/accountingreports`: balance-sheet(`?cutoffDate`), income-statement, trial-balance, general-ledger(`?ledgerAccountId`), journal — cada uno + `/pdf` + `/excel` (params `fromDate&toDate`).

```typescript
interface LedgerAccount { id: string; code: string; name: string; accountType: number; level: number; normalBalanceSide: number; parentId?: string; isPostable: boolean; isActive: boolean; isSystem: boolean; description?: string; }
interface JournalEntry { id: string; entryNumber?: string; entryDate: string; fiscalPeriodId: string; description: string; status: number; source: number; sourceName: string; totalDebit: number; totalCredit: number; lines: { ledgerAccountCode?: string; ledgerAccountName?: string; debit: number; credit: number; description?: string }[]; }
interface FiscalYear { id: string; year: number; name: string; isClosed: boolean; periods: { id: string; periodNumber: number; name: string; startDate: string; endDate: string; status: number }[]; }
// Fechas contables = calendario, comparación inclusiva → enviar cutoffDate/fromDate/toDate tal cual (SIN conversión TZ). El general-ledger requiere ledgerAccountId (descubrir vía /ledgeraccounts).
```

### CONFIGURACIÓN / PERFIL (integración) — scope `settings:read` / `settings:write`

Perfil del usuario de la key, empresa, sucursales, roles, auditoría y catálogos de configuración. Sin feature de módulo. Algunos recursos exigen que el usuario de la key sea **TenantAdmin**.

- **Perfil** `/integration/me`: GET (perfil propio) + PUT (solo nombre/apellido). Nunca expone isSuperAdmin/tenantId/secretos.
- **Usuarios** `/integration/users`: GET(+`/{id}`) (`settings:read`). CRUD de usuarios diferido.
- **Empresa** `/integration/company`: GET; PUT acotado a identidad/contacto (`settings:write` + **TenantAdmin**) — los flags operativos (priceIncludesTax, creditLimitEnabled, horas de reserva de los pedidos en línea, etc.) se preservan.
- **Sucursales** `/integration/branchoffices`: GET(+`/{id}`, param `includeDeleted`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/restore, PATCH/{id}/toggle-status (`settings:write`). Resuelven el `branchOfficeId` que referencian facturas, pedidos, bodegas y reportes. El DELETE es **soft delete** (tombstone): los documentos históricos conservan la referencia; `GET ?includeDeleted=true` incluye las eliminadas (`isDeleted`/`deletedAt`) y `PATCH /{id}/restore` las restaura (400 si ya existe una activa con el mismo nombre). `toggle-status` desactiva sin eliminar. **Ubicación GPS:** `POST`/`PUT` aceptan `latitude`/`longitude` (`-90..90` / `-180..180`, 6 decimales) — **van siempre juntas** (enviar una sola, o `(0,0)`, responde `400`). ⚠️ **El `PUT` trata la ubicación distinto al resto**: omitir las coordenadas la **PRESERVA** (el resto del PUT es reemplazo total) y solo `"clearCoordinates": true` la borra; mandar el flag junto con coordenadas responde `400`.
- **Roles** `/integration/roles`: GET (roles del tenant).
- **Auditoría** `/integration/auditlogs`: GET(`?userId&auditLogType&dateFrom&dateTo`) (`settings:read` + **TenantAdmin**).
- **Descuentos** `/integration/discounts`, **Tipos de pago** `/integration/paymenttypes`, **Unidades** `/integration/units` (+`/global`, +`/{id}/toggle-status`): GET(+`/{id}`, param `includeDeleted`) + POST/PUT/DELETE + PATCH/`{id}`/restore (`settings:write`). El **DELETE es soft delete** (tombstone): el registro desaparece de listas/dropdowns pero los documentos históricos conservan la referencia; `GET ?includeDeleted=true` incluye los eliminados (los DTOs `Public*` exponen `isDeleted`/`deletedAt`) y `PATCH /{id}/restore` los restaura → `400` si hay conflicto de unicidad activo (nombre en descuentos/tipos de pago, código en unidades). Las escrituras de unidades nunca tocan las globales.
- **Categorías de pago** `/integration/paymentcategories`: GET (catálogo global). **Impuestos** `/integration/taxes`: solo lectura (entidad global; el `Tax` expone `isDeleted`/`deletedAt` y `GET ?includeDeleted=true` incluye los eliminados; no expone DELETE ni restore).
- **Prefijos de documento** `/integration/documentprefixes`: GET(+`/{id}`, param `includeDeleted`) + POST/PUT/DELETE + PATCH/`{id}`/restore (`settings:write` + **TenantAdmin**). El correlativo no es editable. El **DELETE es soft delete** (conserva el correlativo); `PATCH /{id}/restore` restaura (`400` si ya existe un prefijo activo del mismo tipo de documento), y **recrear** (`POST`) un prefijo de un tipo que tiene un tombstone se **bloquea** (`400`) — hay que restaurarlo para no reiniciar la numeración.

```typescript
interface Me { id: string; email?: string; username?: string; firstName: string; lastName: string; fullName: string; avatar?: string; roles: string[]; branchOfficeId?: string; branchOfficeName?: string; isActive: boolean; }
interface Company { id: string; rtn?: string; name: string; address1?: string; email?: string; phoneNumber1?: string; owner?: string; logoUrl?: string; priceIncludesTax: boolean; creditLimitEnabled: boolean; /* + flags de config */ }
interface BranchOffice { id: string; name: string; address?: string; phoneNumber?: string; latitude: number | null; longitude: number | null; defaultCaiId?: string; defaultCaiName?: string; managerId?: string; managerName?: string; isActive: boolean; isDeleted: boolean; deletedAt: string | null; }
// PUT /integration/branchoffices/{id} — body: BranchOffice + { clearCoordinates?: boolean }
interface Discount { id: string; name: string; percentage: number; isDeleted: boolean; deletedAt: string | null; }
interface PaymentType { id: string; paymentCategoryId: string; paymentCategoryName: string; name: string; isActive: boolean; ecommerceBehavior: number; isDeleted: boolean; deletedAt: string | null; }
interface Unit { id: string; name: string; code: string; symbol: string; isActive: boolean; isGlobal: boolean; allowsDecimals: boolean; isDeleted: boolean; deletedAt: string | null; } // allowsDecimals (v2.21): fijo en las globales; en las del tenant se manda en POST/PUT (si el PUT no lo trae, se conserva)
interface DocumentPrefix { id: string; documentType: number; documentTypeName: string; prefix: string; isActive: boolean; isDeleted: boolean; deletedAt: string | null; }
interface Role { id: string; name: string; description?: string; isSystemRole: boolean; }
interface AuditLog { id: number; userId?: string; userFullName: string; auditLogType: number; auditLogTypeName: string; description: string; ipAddress?: string; createdAt: string; }
// Empresa write: POST /company no aplica; PUT solo Name/RTN/Address/Email/Phone/Owner/CompanyType. Deletes de catálogos (descuentos/tipos de pago/unidades/prefijos) = soft delete restaurable con PATCH /{id}/restore (ver arriba).
```

### ARCHIVOS Y MULTIPART (integración)

Único grupo que usa `multipart/form-data` (no JSON). El archivo va en el campo **`file`**. Scope = el de escritura del módulo dueño; actor/auditoría = usuario de la key. Imágenes ≤ 5 MB, comprobantes de pago (imagen o PDF) ≤ 10 MB, imports Excel `.xlsx` ≤ 5 MB. **Toda imagen se optimiza y se guarda como `.webp`**; la respuesta trae la URL final del blob público.

**Medios (subir/borrar):**
- **Imágenes de producto** `/integration/products/{id}/images` (`inventory:write`): POST (multipart), DELETE/{imageId}, PATCH/{imageId}/primary, PUT/reorder (`[guid,…]`).
- **Logo de marca** `/integration/brands/{id}/logo` (`catalog:write` + Ecommerce): POST (multipart), DELETE.
- **Banner de sección** `/integration/specialsections/{id}/banner` (`sales:write` + Ecommerce): POST (multipart), DELETE.
- **Carruseles** `/integration/carousels` (`sales:read`/`sales:write` + Ecommerce): GET(+`/{id}`), POST, PUT/{id}, DELETE/{id} (contenedor, JSON) + slides: POST/{id}/images (**multipart**: `file` = arte de escritorio + **`mobileFile` opcional** + `title`/`description`/`linkUrl`/`focalX`/`focalY`), PUT/{id}/images/{imageId} (metadata JSON + `focalX`/`focalY` opcionales, keep-if-null), DELETE/{id}/images/{imageId} (borra ambos blobs), POST/{id}/images/{imageId}/desktop (**multipart**, reemplaza el arte de escritorio conservando la posición del slide), POST · DELETE /{id}/images/{imageId}/mobile (variante móvil), PUT/{id}/images/reorder. Máx 20 slides.
- **Logo de documentos** `/integration/company/documents-logo` (`settings:write` + **TenantAdmin**): POST (multipart), DELETE.
- **Avatar** `/integration/me/avatar` (`settings:write`): POST (multipart), DELETE.
- **Adjunto de pago (venta)** `/integration/invoicepayments/{id}/attachment` (`invoicing:write`): POST (multipart, imagen/PDF), DELETE.
- **Adjunto de pago (compra)** `/integration/purchaseinvoicepayments/{id}/attachment` (`purchasing:write`): POST (multipart), DELETE.
- **Adjunto de abono** `/integration/customeradvancepayments/{id}/attachment` (`crm:write`): POST (multipart), DELETE.

Los DTOs de pago/abono exponen `attachmentUrl` (+ `hasAttachment`) para consultar el comprobante subido.

**Importación masiva (Excel `.xlsx`):** cada recurso da la plantilla (`GET .../import-template` → bytes `.xlsx`) y la carga (POST multipart, campo `file`). Respuesta `BulkImportResult`; si hay cualquier error de validación no se inserta nada (todo-o-nada).
- **Productos** `GET /integration/products/import-template` → `POST /integration/products/bulk-import` (`inventory:read`/`inventory:write`).
- **Proveedores** `GET /integration/suppliers/import-template` → `POST /integration/suppliers/bulk-import` (`inventory:read`/`inventory:write`).
- **Clientes** `GET /integration/customers/import-template` → `POST /integration/customers/bulk-import` (`crm:read`/`crm:write`).
- **Catálogo de cuentas** `GET /integration/ledgeraccounts/import-template` → `POST /integration/ledgeraccounts/import` (`accounting:read`/`accounting:write`).

```typescript
interface Carousel { id: string; name: string; isActive: boolean; images: CarouselImage[]; }
interface CarouselImage { id: string; imageUrl: string; mobileImageUrl?: string | null; focalX: number; focalY: number; title?: string; description?: string; linkUrl?: string; displayOrder: number; }
interface BulkImportResult { totalRows: number; successCount: number; errorCount: number; errors: { row: number; field: string; message: string }[]; }
// Subir imagen: FormData con campo 'file' (+ title/description/linkUrl/focalX/focalY para slides de carrusel). NO setear Content-Type a mano (el browser pone el boundary).
// Slides y banners de sección son responsive: 'file'/'banner' = arte de ESCRITORIO (obligatorio) y 'mobileFile' / '/banner/mobile' = arte de MÓVIL opcional (si falta, el storefront usa el de escritorio). focalX/focalY (0-100) = object-position del recorte de escritorio. Recomendado escritorio 1920x800 (12:5), móvil 1080x1350 (4:5).
// Ejemplo: const fd = new FormData(); fd.append('file', blob, 'foto.jpg'); fetch(base+'/integration/products/'+id+'/images', { method:'POST', headers:{'X-API-Key':key}, body: fd })
```

> Roadmap: **la API de integración queda completa** — toda la superficie JSON (catálogos, inventario, CRM, ventas, facturación, ecommerce, compras, contabilidad, settings) **más el tramo de multipart** (imágenes/logos/banner/avatar/comprobantes de pago + importación masiva por Excel). La API Key se crea desde el panel (Configuraciones Globales → API Keys), marcando los scopes en el diálogo de creación.

---

## BASE URL

```
https://ventix-api.smartbusiness.site/api/public/v1
```

Todos los endpoints cuelgan de esta base. La versión está en el path (`/v1`).

---

## AUTENTICACIÓN

Hay **dos credenciales** que se combinan según el endpoint.

### 1. `X-API-Key` (obligatorio en TODA request a `/api/public/v1/*`)

```
X-API-Key: vtx_live_<32 caracteres aleatorios>
```

- Las claves comienzan literalmente con el prefijo `vtx_live_`.
- Identifica al **tenant**. Aísla automáticamente todas las queries.
- **NUNCA** mandar la key como query string (`?api_key=...`). Solo header.
- **NUNCA** exponer la key en código JS público del navegador. Patrón correcto: `[Browser] → [Backend del cliente] → [Ventix API]`.
- Se genera desde el panel admin del tenant (`Configuraciones Globales → API Keys`). Si se pierde, hay que crear una nueva — la key se muestra una sola vez al crearla.
- Se puede revocar en cualquier momento; al revocarla, todas las requests devuelven `401`.

### 2. `Authorization: Bearer <jwt>` (clientes finales del ecommerce)

```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
```

- Identifica al **cliente final** dentro del tenant.
- Se obtiene llamando `POST /ecommerce-auth/signin`. El response incluye `accessToken` y `expiresAt` (~60 min).
- **Requerido** para `/ecommerce-profile/me` (GET y PUT).
- **Opcional** para `/products` y `/products/{id}` — si se manda, el `salePrice` se resuelve por la lista de precios del cliente.
- A diferencia de la API Key, este JWT **sí puede vivir en el navegador** (sessionStorage/localStorage): está acotado a un cliente, expira pronto y solo expone sus propios datos.
- No hay refresh token. Cuando expira, el cliente vuelve a llamar `signin`.
- El backend valida que el `tenantId` del JWT coincida con el de la API Key. Si no coinciden → `403`.

### Tabla rápida: qué header necesita cada endpoint

| Endpoint                                              | `X-API-Key` | `Authorization: Bearer` |
|-------------------------------------------------------|:-----------:|:-----------------------:|
| Catálogo (`/store/info`, `/products`, `/categories`, `/branches`, `/inventory/...`, `/sections`) | ✔️ | opcional ‡ |
| Geografía (`/geography/...`)                          |     ✔️      |          —              |
| Auth de cliente (`/ecommerce-auth/*`)                 |     ✔️      |          —              |
| Perfil del cliente (`/ecommerce-profile/me`)          |     ✔️      |          ✔️             |
| Direcciones del cliente (`/ecommerce-profile/addresses/*`) |  ✔️    |          ✔️             |
| Carrito del cliente (`/ecommerce-cart/me`, `/ecommerce-cart/me/items/*`) | ✔️ | ✔️         |

‡ Solo afecta a `/products` y `/products/{id}`: con bearer se resuelve por lista de precios; sin bearer se devuelve el precio base.

### Errores de auth

- **Sin `X-API-Key` o header inválido** → `401 Unauthorized`.
- **Plan del tenant sin feature `ecommerce`** → `403 Forbidden`.
- **JWT inválido / vencido** → `401 Unauthorized` (solo afecta endpoints que requieren bearer).
- **`tenantId` del JWT no coincide con la API Key** → `403 Forbidden`.

---

## RESPONSE ENVELOPE (todas las respuestas)

```json
{
  "succeeded": true,
  "message": "Productos obtenidos exitosamente.",
  "data": { /* payload — depende del endpoint */ },
  "errors": []
}
```

| Campo       | Tipo        | Descripción                                                |
|-------------|-------------|------------------------------------------------------------|
| `succeeded` | `boolean`   | `true` si OK.                                              |
| `message`   | `string`    | Mensaje legible (puede mostrarse al usuario final).        |
| `data`      | `T \| null` | Payload tipado por endpoint (o `null` en errores).         |
| `errors`    | `string[]`  | Detalles adicionales en caso de error.                     |

**Para endpoints paginados, `data` es:**

```json
{
  "items": [ /* array del recurso */ ],
  "totalCount": 142,
  "pageNumber": 1,
  "pageSize": 20,
  "totalPages": 8,
  "hasPreviousPage": false,
  "hasNextPage": true
}
```

**Iterar con `hasNextPage`, no con `totalCount` fijo** — el catálogo crece.

---

## STATUS CODES

| Status | Significado            | Acción del cliente                                         |
|--------|------------------------|------------------------------------------------------------|
| `200`  | OK                     | Procesar `data`.                                           |
| `400`  | Bad Request            | Corregir parámetros, credenciales del cliente, PIN, etc. NO reintentar — salvo el `400` transitorio "El inventario de uno de los productos se está actualizando en otra operación…" (facturas de integración, checkout `POST /ecommerce-orders` y cambios de pedido): reintentar 1–2 veces tras unos segundos. |
| `401`  | Unauthorized           | Key faltante/inválida/revocada/expirada, o JWT del cliente vencido. NO reintentar. |
| `403`  | Forbidden              | Plan del tenant no incluye `ecommerce`, o `tenantId` del JWT ≠ API Key. NO reintentar. |
| `404`  | Not Found              | Recurso no existe o pertenece a otro tenant. NO reintentar.|
| `429`  | Too Many Requests      | Esperar `Retry-After` segundos. Reintentar con backoff.    |
| `5xx`  | Server Error           | Reintentar con backoff exponencial (1s, 2s, 4s, 8s, máx 5). Al crear facturas, reintentar con el mismo `Idempotency-Key` para no duplicarlas.|

**Body de error**:
```json
{ "succeeded": false, "message": "...", "data": null, "errors": [] }
```

**Códigos in-band en el `message`** — algunos errores `400` traen un código en mayúsculas dentro del `message` para que el front pueda branchear sin parsear texto libre:

| Código                | Endpoint(s)                       | Cómo manejarlo                                        |
|-----------------------|-----------------------------------|-------------------------------------------------------|
| `EMAIL_NOT_CONFIRMED` | `POST /ecommerce-auth/signin`     | Redirigir al cliente al flujo "Ingresá el PIN de tu correo". NO mostrar "credenciales inválidas". |

Detección sugerida: `error.message.includes("EMAIL_NOT_CONFIRMED")`.

---

## RATE LIMITS

| Identidad                | Límite      | Ventana | Comportamiento al exceder         |
|--------------------------|-------------|---------|-----------------------------------|
| Por API Key autenticada  | **600**     | 1 min   | `429` + header `Retry-After: <s>` |
| Por IP (no autenticado)  | **100**     | 1 min   | `429` + header `Retry-After: <s>` |

**Estrategia obligatoria**: cachear respuestas en el lado del cliente. El catálogo cambia con baja frecuencia.
- `/products`, `/categories`, `/branches`: TTL 1–5 minutos.
- `/inventory/products/{id}`: TTL 10–30 segundos.
- El disponible (`isAvailable`, `virtualStock`, `/inventory/products/{id}`) cambia con cada pedido: lo que muestres puede quedar atrasado lo que dure tu caché. El carrito y el checkout validan siempre en vivo.

---

## CORS

`Access-Control-Allow-Origin: *` está habilitado para `GET`. Sin embargo, **no llamar la API directamente desde el navegador con la key embedded** — usar siempre proxy en el backend del cliente.

---

## ENDPOINTS — Reference completa

> El **storefront** tiene **36 endpoints** divididos en 7 áreas (la API de **integración** ERP/CRM es
> aparte, ver la sección de arriba):
> - Catálogo (9): `store/info`, `products`, `products/{id}`, `products/search`, `categories`, `branches`, `inventory/products/{id}`, `sections`, `sections/{id}/products`.
> - Auth de cliente (6): `ecommerce-auth/signup`, `.../verify-email`, `.../resend-verification`, `.../signin`, `.../request-password-reset`, `.../reset-password`.
> - Perfil de cliente (2): `GET ecommerce-profile/me`, `PUT ecommerce-profile/me`.
> - Direcciones del cliente (6): `GET/POST /ecommerce-profile/addresses`, `GET/PUT/DELETE /.../{id}`, `POST /.../{id}/set-default`.
> - Carrito del cliente (5): `GET /ecommerce-cart/me`, `POST /ecommerce-cart/me/items`, `PUT /ecommerce-cart/me/items/{productId}`, `DELETE /ecommerce-cart/me/items/{productId}`, `DELETE /ecommerce-cart/me`.
> - Pedidos y checkout (6): `GET /ecommerce-payment-types`, `POST /ecommerce-orders`, `GET /ecommerce-orders`, `GET /ecommerce-orders/{id}`, `PATCH /ecommerce-orders/{id}/cancel`, `POST /ecommerce-orders/{id}/payment-proof`.
> - Geografía (2): `geography/departments`, `geography/departments/{id}/cities`.
>
> **Marcas** (`GET /brands`) y **carruseles** (`GET /carousels`, `GET /carousels/{id}`) también existen
> en el storefront; ver `PUBLIC_API.md` para su contrato completo.

### 1. `GET /store/info`

Devuelve datos básicos públicos del tenant (la "tienda").

**Sin query params.**

**Response 200 — `data`:**

```typescript
interface PublicStoreInfo {
  name: string;              // Nombre legal del negocio
  rtn: string | null;        // RTN (registro tributario nacional, Honduras)
  email: string | null;
  phoneNumber: string | null;
  address: string | null;    // Dirección concatenada (Address1 + Address2)
  logoUrl: string | null;    // URL pública del logo (Azure Blob)
  currency: "HNL";           // Por ahora siempre HNL (Lempiras hondureñas)
  priceIncludesTax: boolean; // Si true, los salePrice de /products YA incluyen ISV
  showOutOfStockProducts: boolean; // Si true, el catálogo lista también los productos sin disponible, con isAvailable=false (v2.14)
  branches: PublicBranch[];  // Sucursales activas
}

interface PublicBranch {
  id: string;                // UUID de la sucursal
  name: string;
  address: string | null;
  phoneNumber: string | null;
  latitude: number | null;   // Ubicacion GPS; ver GET /branches
  longitude: number | null;  // Siempre viaja junto a latitude, o ambas null
  acceptsOnlineOrders: boolean; // ver GET /branches
}
```

**Uso típico:** mostrar header de la tienda online (logo, nombre, contacto). Se llama una sola vez al inicio y se cachea.

**`showOutOfStockProducts`** (desde v2.14): el comercio muestra en el catálogo los productos **sin disponible** (agotados o
con todas sus unidades apartadas por pedidos), con `isAvailable: false`. Con `false` (el default) `/products`, la búsqueda
y las secciones no los listan. Solo indica si el listado incluye los agotados: el badge "Agotado" se decide SIEMPRE con
`isAvailable` (el detalle devuelve también los agotados, y un producto puede quedar sin disponible entre que lo listás y
lo mostrás).

**No trae `tenantId`**: se quitó el 2026-08-11 (era un id interno) y este archivo lo siguió documentando hasta v2.14. La
API Key ya identifica al tenant.

---

### 2. `GET /products`

Listado paginado de productos activos **con disponible**: la existencia menos lo apartado por pedidos vigentes (desde v2.14). Si el comercio muestra los agotados (`showOutOfStockProducts` de `/store/info`), también trae los que no tienen, con `isAvailable: false`. Un servicio siempre tiene disponible; un combo, cuando cada componente alcanza para al menos una unidad.

> **Bearer opcional para precios resueltos**: si además de la API Key enviás `Authorization: Bearer <jwt>` del cliente logueado, `salePrice` se devuelve según la lista de precios asignada a ese cliente (sección [Listas de precios](#listas-de-precios-para-clientes-logueados)). Sin bearer → precio base.

**Query params:**

| Parámetro    | Tipo     | Default | Descripción                                                |
|--------------|----------|---------|------------------------------------------------------------|
| `pageNumber` | `int`    | `1`     | Página (1-based).                                          |
| `pageSize`   | `int`    | `20`    | Items por página. Recomendado ≤ 50.                        |
| `search`     | `string` | —       | Busca en `name`, `description`, marca, categoría y `barcodes`. |
| `categoryId` | `guid`   | —       | Filtra productos pertenecientes a esa categoría.           |
| `brandId`    | `guid`   | —       | Filtra productos de esa marca (los `id` de `GET /brands`). |
| `minPrice` / `maxPrice` | `decimal` | — | Rango sobre el precio del catálogo con la oferta vigente. NO usa la lista de precios del cliente aunque mandes el bearer. |
| `sortBy`     | `string` | nombre  | `price_asc` o `price_desc` (precio del catálogo con la oferta vigente). Con `search`, primero la relevancia. |
| `onOffer`    | `bool`   | `false` | Solo productos con una oferta vigente.                     |

**Response 200 — `data` (paginado):**

```typescript
interface PaginatedResult<T> {
  items: T[];
  totalCount: number;
  pageNumber: number;
  pageSize: number;
  totalPages: number;
  hasPreviousPage: boolean;
  hasNextPage: boolean;
}

interface PublicProduct {
  id: string;                          // UUID
  name: string;
  description: string | null;
  salePrice: number;                   // Precio efectivo: el menor entre el regular y la oferta vigente. Si store.priceIncludesTax=true, ya incluye ISV.
  regularPrice: number;                // Precio de referencia (tachalo si isOnOffer). Sin oferta = salePrice.
  isOnOffer: boolean;                  // Hay una oferta vigente más barata que el precio regular
  offerEndDate: string | null;         // UTC. Fin de la oferta vigente; null sin oferta o si no tiene fecha de fin
  brandName: string | null;
  brandId: string | null;              // Sirve para ?brandId=
  categories: { id: string; name: string }[];
  taxName: string;                     // Ej: "ISV 15%"
  taxPercentage: number;               // Ej: 15
  unitOfMeasurementName: string | null;
  unitOfMeasurementSymbol: string | null;
  isActive: boolean;
  images: PublicProductImage[];        // Ordenadas: primary primero, luego por displayOrder
  barcodes: string[];                  // Solo barcodes activos
  isCombo: boolean;                    // true = combo (componentes en comboComponents)
  virtualStock: number | null;         // Solo combos: cuántos alcanzan con lo DISPONIBLE de sus componentes (v2.14). null en productos, servicios y combos solo de servicios
  isAvailable: boolean;                // Hay disponible (existencia − apartado por pedidos). false => mostrar "Agotado" (v2.14)
  comboComponents: PublicComboComponent[]; // [] si no es combo
}

interface PublicProductImage {
  url: string;                         // URL pública (Azure Blob)
  displayOrder: number;
  isPrimary: boolean;
}

interface PublicComboComponent {
  name: string;
  imageUrl: string | null;             // Imagen primaria del componente
  quantity: number;                    // Cantidad por combo
  unitOfMeasurementSymbol: string | null;
}
```

**`isAvailable`** (desde v2.14): hay unidades disponibles en el comercio (existencia menos lo apartado por pedidos). Es la misma cuenta con la que el carrito valida al agregar, así que un producto con `false` no se puede agregar. Es orientativo: la validación final es la del checkout en la sucursal elegida. No trae cantidades. Sin `showOutOfStockProducts`, el listado, la búsqueda y las secciones no traen productos sin disponible; con `true` los traen con `false`, y `/products/{id}` los devuelve siempre. **No los filtres en el cliente** (rompe la paginación): mostralos como "Agotado", con el botón de compra deshabilitado.

**Combos:** `isCombo: true`, sus componentes en `comboComponents` (nombre, imagen, cantidad por combo y unidad) y `virtualStock` = cuántos combos alcanzan con lo disponible de sus componentes (desde v2.14 resta lo apartado; antes usaba la existencia). Es `null` en productos y servicios, y en un combo solo de servicios, que no tiene límite. Para mostrar "Agotado" usá `isAvailable`.

**IMPORTANTE — campos NO expuestos por seguridad:** `costPrice`, `stock` (global), `minStock`, `maxStock`, `tenantId`, `createdBy`, datos de auditoría. Para saber si se puede vender usá `isAvailable` (sin cantidades); si necesitás números, `/inventory/products/{id}` da el **disponible** por sucursal (sin números de costo). La única cantidad del producto es `virtualStock`, y solo en combos.

---

### 3. `GET /products/{id}`

Detalle de un producto. Mismo shape que un item de `/products`. Devuelve `404` si:
- El ID no existe.
- El producto pertenece a otro tenant (aislamiento automático).
- El producto está inactivo (`isActive = false`).
- Es un producto oculto de extras del restaurante (modificador con precio, desde v2.19): esos productos no se listan en `/products`, `/products/search` ni las secciones (ni cuentan en `totalCount`), y por id responden este mismo `404`. Tampoco se pueden comprar: `POST /ecommerce-cart/me/items` (y subir su cantidad) responde `400` «Producto no encontrado.» y cerrar el pedido con uno en el carrito responde `400` «El producto '…' ya no está disponible.».

Un producto **sin disponible no da `404`**: este endpoint nunca filtró por stock, y desde v2.14 trae `isAvailable: false`, tenga o no el comercio `showOutOfStockProducts`. Así los enlaces de anuncios, del feed o de WhatsApp siguen funcionando: mostralo como "Agotado".

> **Bearer opcional para precios resueltos**: idéntico comportamiento que `/products` — si mandás bearer del cliente, `salePrice` se resuelve por su lista de precios.

---

### 4. `GET /products/search`

Buscador dedicado, equivalente a `/products?search=...` pero con UX de autocomplete.

**Query params:**

| Parámetro    | Tipo     | Default     | Descripción                |
|--------------|----------|-------------|----------------------------|
| `q`          | `string` | **requerido** | Texto a buscar.          |
| `pageNumber` | `int`    | `1`         | Página.                    |
| `pageSize`   | `int`    | `20`        | Items por página.          |

**Response**: idéntico a `/products` (paginado de `PublicProduct`, con el mismo filtro de disponible e `isAvailable`).

**Uso típico:** input de búsqueda con debounce de 300ms en el front.

---

### 5. `GET /categories`

Listado plano de categorías (familias de producto). **No paginado** — el universo es chico (~10-100 categorías por tenant típicamente).

**Sin query params.**

**Response 200 — `data`:**

```typescript
type PublicCategory = {
  id: string;     // UUID
  name: string;
}[];
```

**Uso típico:** dropdown/sidebar de categorías. Cachear por horas.

---

### 6. `GET /branches`

Listado de sucursales activas del tenant. **No paginado**.

**Response 200 — `data`:**

```typescript
type PublicBranch = {
  id: string;
  name: string;
  address: string | null;     // Direccion en texto libre escrita por el comercio
  phoneNumber: string | null;
  latitude: number | null;    // -90 a 90, 6 decimales. null si no se configuro
  longitude: number | null;   // -180 a 180, 6 decimales. null si no se configuro
  acceptsOnlineOrders: boolean; // tiene almacén por defecto activo: solo estas sirven para el checkout (v2.13)
}[];
```

**`acceptsOnlineOrders`** (desde v2.13): los pedidos en línea salen (y apartan stock) del almacén por defecto de la
sucursal. Con `false`, `POST /ecommerce-orders` con esa sucursal responde `400`: en el selector del checkout ofrecé
solo las sucursales con `true` (el listado completo sigue sirviendo para "Nuestras sucursales").

**Ubicacion GPS:** `latitude` y `longitude` vienen **siempre juntas** (o ambas con valor, o ambas `null`);
nunca una sola. Compara con `!= null` y NO por truthiness: `0` es una coordenada valida (Greenwich).

**Uso típico:** enlace "Como llegar" por sucursal, selector "Recoger en...", footer.

```typescript
// De mas preciso a menos: coordenadas -> busqueda por direccion -> sin enlace.
function branchMapLink(b: PublicBranch): string | null {
  if (b.latitude != null && b.longitude != null) {
    // dir/?api=1&destination= abre la app nativa de mapas con la ruta lista en movil
    return `https://www.google.com/maps/dir/?api=1&destination=${b.latitude},${b.longitude}`;
  }
  if (b.address) {
    return `https://www.google.com/maps/search/?api=1&query=${encodeURIComponent(b.address)}`;
  }
  return null;
}
```

---

### 7. `GET /inventory/products/{id}`

**Disponible** de un producto por sucursal (desde v2.14): la existencia de los almacenes **activos** de cada sucursal activa, menos lo apartado por pedidos en ese almacén, recortado en cero por almacén (el faltante de uno no tapa lo disponible en otro). `totalStock` es la suma. Los almacenes inactivos o dados de baja y las sucursales dadas de baja no cuentan. No muestra existencia física: antes de v2.14, `stock` era la existencia de todos los almacenes de las sucursales activas.

**Response 200 — `data`:**

```typescript
interface PublicProductInventory {
  productId: string;
  productName: string;
  totalStock: number;                  // Suma del disponible de todas las sucursales. Entero, salvo en productos por peso o volumen: hasta 3 decimales (v2.21)
  branches: {
    branchId: string;
    branchName: string;
    stock: number;                     // DISPONIBLE en esa sucursal (existencia − apartado por pedidos), nunca negativo. Hasta 3 decimales en productos por peso o volumen (v2.21)
  }[];                                 // [] en combos y servicios
}
```

**Uso típico:** badge "Disponible en N sucursales", selector "Recoger en sucursal", indicador de disponible por ubicación.

**Ojo con el checkout:** los pedidos en línea salen **solo del almacén por defecto** de la sucursal (y solo de las sucursales con `acceptsOnlineOrders`), así que una sucursal puede mostrar disponible aquí, en otro almacén, y aun así no alcanzar en el checkout. Los combos y los servicios no tienen existencia por almacén: devuelven `totalStock: 0` y `branches: []`; para ellos usá `isAvailable` del producto. `isAvailable` mira todo el comercio (también los almacenes inactivos, y un
faltante en un almacén resta del total), así que puede no coincidir con la suma de este endpoint.

---

### 7a. `GET /sections`

Secciones especiales activas del tenant: agrupaciones **curadas a mano** de productos (p. ej. "Destacados", "Novedades"), ordenadas por el orden definido en el panel. Cada sección trae un **preview** de sus productos visibles más el total. Bearer opcional → precios por lista del cliente.

**Query params:** `previewSize` (int, default 12, **máximo 48**: un valor mayor se toma como 48) — productos del preview por sección.

**Response 200 — `data`:**

```typescript
type PublicSection = {
  id: string;
  title: string;
  subtitle: string | null;
  description: string | null;
  bannerImageUrl: string | null;        // banner de ESCRITORIO
  mobileBannerImageUrl: string | null;  // alterno para pantallas angostas; null => usar bannerImageUrl
  bannerFocalX: number;                 // 0-100 => object-position del recorte de escritorio (50 = centro)
  bannerFocalY: number;
  totalProducts: number;          // productos VISIBLES de la sección (no el tamaño del preview)
  products: PublicProduct[];      // preview acotado, mismo shape que /products (con isAvailable)
}[];
```

**Uso típico:** rieles/carruseles curados en la home ("Destacados", "Novedades"). Solo aparecen secciones activas y productos visibles: activos y con disponible (existencia menos lo apartado por pedidos), salvo que el comercio muestre los agotados (`showOutOfStockProducts`), que llegan con `isAvailable: false`.

**Banner responsive:** mismo patrón que los slides de carrusel (ver 7c) — `<picture>` con `<source media="(min-width: 640px)" srcset={bannerImageUrl}>` y `<img src={mobileBannerImageUrl ?? bannerImageUrl} style="object-position: {bannerFocalX}% {bannerFocalY}%">`.

---

### 7c. `GET /carousels` · `GET /carousels/{id}`

Carruseles **activos** del tenant con sus slides ya ordenados por `displayOrder`. Para el hero de la portada y banners rotativos. `GET /carousels` devuelve un array; `GET /carousels/{id}` devuelve uno solo (404 si no existe, no es del tenant, o está inactivo).

**Response 200 — `data`:**

```typescript
type PublicCarousel = {
  id: string;
  name: string;
  images: {
    imageUrl: string;                 // arte de ESCRITORIO, siempre presente
    mobileImageUrl: string | null;    // alterno para pantallas angostas; null => usar imageUrl
    focalX: number;                   // 0-100 => object-position del recorte de escritorio (50 = centro)
    focalY: number;
    title: string | null;
    description: string | null;
    linkUrl: string | null;
    displayOrder: number;
  }[];
};
```

**Cómo renderizar un slide.** El arte de escritorio se recorta a **12:5 (1920 × 800 px recomendado)** con `object-fit: cover` y el punto focal; en móvil conviene mostrarlo a proporción natural, sin recortar. Poner el mismo `<picture>` en ambas ramas hace que cada viewport resuelva a una sola URL, así que no se descarga la imagen dos veces (`display:none` NO evita la descarga):

```html
<picture>
  <source media="(min-width: 640px)" srcset="{imageUrl}">
  <img src="{mobileImageUrl ?? imageUrl}" style="object-position: {focalX}% {focalY}%">
</picture>
```

---

### 7b. `GET /sections/{id}/products`

Listado **paginado** de los productos de una sección especial, en el orden curado. Para la página "ver todos" de una sección.

**Query params:** `pageNumber` (default 1), `pageSize` (default 20).

**Response 200 — `data`:** página estándar (`items: PublicProduct[]`, `totalCount`, `pageNumber`, `pageSize`, `totalPages`, `hasPreviousPage`, `hasNextPage`). Si la sección no existe o está inactiva → página vacía (`items: []`, `totalCount: 0`). Mismo filtro de visibilidad que el preview de `/sections` (activos y con disponible, salvo `showOutOfStockProducts`); cada item trae `isAvailable`.

---

### 8. `POST /ecommerce-auth/signup`

Crea una cuenta de cliente del ecommerce dentro del tenant y dispara el envío del PIN de confirmación al correo (con logo del tenant). **No** inicia sesión automáticamente: el cliente queda con `emailConfirmed = false` hasta que verifique el PIN.

**Body:**

```typescript
interface SignUpRequest {
  email: string;             // Único por tenant. Se normaliza a minúsculas.
  password: string;          // Mínimo 8 caracteres.
  firstName: string;         // Máx. 100.
  lastName?: string;         // Máx. 100.
  phoneNumber?: string;      // Máx. 20.
  gender?: "Male" | "Female" | "Other" | "Unspecified";
  departmentId?: string;     // GUID de /geography/departments.
  cityId?: string;           // GUID de /geography/departments/{id}/cities. Debe pertenecer al departmentId.
}
```

**Response 200:** `data` es `string` con mensaje legible (`"Cuenta creada. Revisa tu correo para confirmar tu cuenta."`).

**Errores comunes:**
- `400` `"Ya existe una cuenta registrada con este correo en esta tienda."`
- `400` con detalles de validación (password corta, email mal formado, etc.).

---

### 9. `POST /ecommerce-auth/verify-email`

Confirma el correo del cliente con el PIN de 6 dígitos enviado por mail. Una vez verificado, el cliente puede hacer `signin`.

**Body:**

```typescript
interface VerifyEmailRequest {
  email: string;
  pin: string;     // 6 dígitos. TTL 60 minutos. Máx. 5 intentos antes de invalidarse.
}
```

**Response 200:** `data` es `string` (`"Correo confirmado. Ya puedes iniciar sesion."`).

**Errores comunes:**
- `400` `"El codigo de verificacion expiro o no existe. Solicita uno nuevo."`
- `400` `"Codigo incorrecto. Te quedan N intento(s)."`

---

### 10. `POST /ecommerce-auth/resend-verification`

Reenvía un PIN nuevo si el cliente nunca recibió el primero o lo perdió. Siempre devuelve mensaje genérico (anti-enumeración).

**Body:**

```typescript
interface ResendVerificationRequest {
  email: string;
}
```

**Response 200:** `data` siempre es `"Si el correo existe y no esta confirmado, te enviaremos un nuevo codigo."`. **No** uses la respuesta para inferir si el email existe.

---

### 11. `POST /ecommerce-auth/signin`

Inicia sesión y devuelve un JWT que el cliente debe enviar en `Authorization: Bearer ...` para llamar a `/ecommerce-profile/me` y para obtener precios resueltos en `/products`.

**Body:**

```typescript
interface SignInRequest {
  email: string;
  password: string;
}
```

**Response 200 — `data`:**

```typescript
interface SignInResponse {
  accessToken: string;           // JWT firmado con HS256. Vida ~60 min.
  expiresAt: string;             // ISO-8601 UTC. Usalo para saber cuándo re-loguear.
  customer: EcommerceCustomer;   // Snapshot del perfil del cliente al momento del login.
}

interface EcommerceCustomer {
  id: string;
  firstName: string;
  lastName: string | null;
  email: string | null;
  phoneNumber: string | null;
  gender: "Male" | "Female" | "Other" | "Unspecified" | null;
  departmentId: string | null;
  departmentName: string | null;
  cityId: string | null;
  cityName: string | null;
  emailConfirmed: boolean;
  ecommerceRegisteredAt: string | null;   // ISO-8601 UTC
}
```

**Errores comunes:**
- `400` `"Credenciales incorrectas."` — email no existe o contraseña errónea (mensaje deliberadamente genérico).
- `400` `"EMAIL_NOT_CONFIRMED: Debes confirmar tu correo antes de iniciar sesion."` — manejar con redirect al flujo de PIN.
- `400` `"La cuenta se encuentra inactiva."` — el Tenant Admin la desactivó desde el panel.

**No hay refresh token.** Cuando llegue `expiresAt`, llamar `signin` de nuevo (puede ser silencioso si el front guardó las credenciales en una BFF).

---

### 12. `POST /ecommerce-auth/request-password-reset`

Envía al cliente un correo branded con un PIN de 6 dígitos para reiniciar la contraseña. Siempre devuelve `200` con mensaje genérico (anti-enumeración).

**Body:**

```typescript
interface RequestPasswordResetRequest {
  email: string;
}
```

**Response 200:** `data` siempre es `"Si el correo existe, recibiras un codigo de recuperacion."`.

---

### 13. `POST /ecommerce-auth/reset-password`

Verifica el PIN y setea una nueva contraseña.

**Body:**

```typescript
interface ResetPasswordRequest {
  email: string;
  pin: string;          // 6 dígitos. TTL 60 min. Máx. 5 intentos.
  newPassword: string;  // Mínimo 8 caracteres.
}
```

**Response 200:** `data` es `"Contrasena actualizada correctamente."`.

**Errores comunes:**
- `400` `"El codigo expiro o no existe. Solicita uno nuevo."`
- `400` `"Codigo incorrecto. Te quedan N intento(s)."`

---

### 14. `GET /ecommerce-profile/me`

Devuelve el perfil del cliente logueado. **Requiere `X-API-Key` Y `Authorization: Bearer`**.

**Response 200 — `data`:** mismo shape que `EcommerceCustomer` del signin response.

---

### 15. `PUT /ecommerce-profile/me`

Actualiza los datos del cliente logueado.

**Body:**

```typescript
interface UpdateProfileRequest {
  firstName: string;                                                   // Requerido. Máx. 100.
  lastName?: string;                                                   // Máx. 100.
  email?: string;                                                      // Si cambia, dispara nuevo PIN de verificación.
  phoneNumber?: string;                                                // Máx. 20.
  gender?: "Male" | "Female" | "Other" | "Unspecified";
  departmentId?: string;
  cityId?: string;
}
```

**Response 200 — `data`:** perfil actualizado (`EcommerceCustomer`).

**⚠ Cambio de correo:** si el cliente envía un `email` distinto al actual:
1. El backend marca `emailConfirmed = false`.
2. Envía un nuevo PIN al **nuevo** correo.
3. El próximo `signin` fallará con `EMAIL_NOT_CONFIRMED` hasta que el cliente verifique con `POST /ecommerce-auth/verify-email` usando el nuevo email + nuevo PIN.

Manejá esto en tu UI: tras un cambio de email exitoso, llevá al cliente a la pantalla de "Verificá tu nuevo correo".

---

## Direcciones de envío del cliente

Los siguientes 6 endpoints permiten al cliente logueado gestionar sus **direcciones de envío** (CRUD completo + set-default explícito). Todos requieren `X-API-Key` **y** `Authorization: Bearer <jwt>`.

**Reglas de negocio importantes:**

- Si el cliente no tiene direcciones aún, la primera que cree queda con `isDefault = true` automáticamente — el `isDefault` del body se ignora cuando es la primera.
- Al crear o actualizar una dirección con `isDefault: true`, las demás direcciones del cliente pasan a `isDefault: false` en la misma transacción (la DB tiene un índice único filtrado que garantiza una sola default por cliente).
- Al **eliminar** la dirección default cuando hay otras, la dirección más reciente (por `updatedAt`/`createdAt`) queda como nueva default automáticamente.
- En `PUT`, enviar `isDefault: false` **no** quita el flag a la dirección actual si ya era la default — para cambiar la default, usá `set-default` sobre **otra** dirección.
- `cityId` debe pertenecer al `departmentId` enviado (validado server-side; idealmente también client-side).
- Cuando el cliente del ecommerce se elimina desde el panel admin, sus direcciones se borran en cascada (FK con cascade delete).

**Tipo `CustomerAddress`** (response shape):

```typescript
interface CustomerAddress {
  id: string;
  label: string | null;             // "Casa", "Oficina", etc. Opcional
  recipientName: string;            // Persona que recibe en esa dirección
  phoneNumber: string;              // Contacto local (puede diferir del perfil)
  departmentId: string;
  departmentName: string;
  cityId: string;
  cityName: string;
  addressLine1: string;             // Calle / colonia
  addressLine2: string | null;      // Apto / piso
  reference: string | null;         // Punto de referencia ("frente al parque")
  isDefault: boolean;
  createdAt: string;                // ISO-8601 UTC
  updatedAt: string | null;
}
```

**Body compartido por `POST` y `PUT`** (`AddressBody`):

```typescript
interface AddressBody {
  label?: string;          // Máx 50
  recipientName: string;   // Requerido. Máx 150
  phoneNumber: string;     // Requerido. Máx 20
  departmentId: string;    // Requerido. De /geography/departments
  cityId: string;          // Requerido. Debe pertenecer al departmentId
  addressLine1: string;    // Requerido. Máx 250
  addressLine2?: string;   // Máx 250
  reference?: string;      // Máx 300
  isDefault: boolean;
}
```

---

### 18. `GET /ecommerce-profile/addresses`

Listado de las direcciones del cliente logueado. **No paginado** (un cliente típico tiene 1–5 direcciones).

**Sin query params.**

**Response 200 — `data`:** `CustomerAddress[]` ordenado con la default primero, luego por `updatedAt ?? createdAt` descendente.

**Uso típico:** dropdown "Seleccionar dirección de envío" en el checkout del storefront. Pre-seleccionar la que tenga `isDefault: true`.

---

### 19. `GET /ecommerce-profile/addresses/{id}`

Detalle de una dirección específica del cliente.

**Response 200 — `data`:** `CustomerAddress`.

**Errores comunes:**
- `400` `"Direccion no encontrada."` — el `id` no existe o pertenece a otro cliente (mismo mensaje para no exponer existencia ajena).

---

### 20. `POST /ecommerce-profile/addresses`

Crea una dirección nueva.

**Body:** `AddressBody`.

**Response 200 — `data`:** `CustomerAddress` recién creada (con `id`, `createdAt`, y `isDefault` resuelto según las reglas).

**Notas de UX:**
- Si es la **primera** dirección del cliente → `isDefault` queda en `true` aunque hayas mandado `false`.
- Si mandás `isDefault: true` y el cliente ya tiene una default, la anterior pasa a `false` automáticamente.
- Documentá en tu front "Esta dirección será tu predeterminada" cuando es la primera.

**Errores comunes:**
- `400` `"El municipio no pertenece al departamento seleccionado."` — `cityId.departmentId` ≠ body.departmentId.
- `400` con detalles de validación (campos requeridos, longitudes, etc.).

---

### 21. `PUT /ecommerce-profile/addresses/{id}`

Actualiza una dirección existente.

**Body:** `AddressBody` (todos los campos requeridos van completos; los opcionales pueden omitirse para limpiarlos a `null`).

**Response 200 — `data`:** `CustomerAddress` actualizada.

**⚠ Importante:** enviar `isDefault: false` cuando la dirección **ya era la default** **no la desmarca** — para cambiar la default, llamá a `set-default` sobre otra dirección. Esto evita dejar al cliente sin default por accidente.

**Errores comunes:** mismos que `POST`, más `"Direccion no encontrada."` si el `id` es ajeno.

---

### 22. `DELETE /ecommerce-profile/addresses/{id}`

Elimina una dirección (hard delete).

**Sin body.**

**Response 200 — `data`:** `true`.

**Comportamiento especial:** si la dirección eliminada era la default y al cliente le quedan otras, la **más reciente** (`updatedAt ?? createdAt` desc) queda automáticamente como nueva default. El cliente nunca queda con direcciones pero sin default.

**Errores comunes:** `400` `"Direccion no encontrada."` si el `id` es ajeno o no existe.

---

### 23. `POST /ecommerce-profile/addresses/{id}/set-default`

Marca una dirección como predeterminada sin tocar ningún otro campo.

**Sin body.**

**Response 200 — `data`:** `CustomerAddress` (la que ahora es default).

**Comportamiento:** desmarca la default anterior (si había) y marca esta. Si la dirección ya era la default, devuelve `200` con mensaje `"Esta direccion ya es la predeterminada."` (idempotente).

**Errores comunes:** `400` `"Direccion no encontrada."` si el `id` es ajeno.

---

## Carrito persistente cross-device del cliente

Los siguientes 5 endpoints permiten al cliente logueado mantener un **carrito persistente server-side** que sigue al usuario entre dispositivos (móvil, desktop, tablet) y entre sesiones. Todos requieren `X-API-Key` **y** `Authorization: Bearer <jwt>`.

**Reglas de negocio importantes:**

- **Solo clientes autenticados.** No hay carritos anónimos. La integración debe pedir login antes de habilitar "Agregar al carrito".
- **Precios siempre frescos.** Cada `GET /ecommerce-cart/me` recalcula `unitPrice` usando la lista de precios actual del cliente. NO hay snapshot. Si el tenant cambia la lista, el carrito refleja el nuevo precio en la próxima lectura.
- **El carrito valida el DISPONIBLE** (existencia del comercio menos lo apartado por otros pedidos vigentes). Agregar o **subir** la cantidad responde `400` si no alcanza (sin cantidades); **bajar** o quitar nunca se bloquea. Es orientativo sobre todo el comercio: la validación definitiva es la del checkout, en la sucursal elegida. Cada línea trae `isAvailable`.
- **Un carrito por cliente.** Indexado por `CustomerId UNIQUE` en la base. Si el cliente nunca agregó nada, `GET` devuelve un carrito vacío implícito con `items: []` e `id: "00000000-0000-0000-0000-000000000000"` (Guid.Empty).
- **TTL de 30 días.** Un background job borra carritos con `updatedAt < hoy - 30 días`. Mensaje para tus clientes: "los carritos abandonados expiran a los 30 días de inactividad".
- **Cantidad máxima por item: 9999.** Validado server-side. Cap también en el front para mejor UX.
- **Endpoints admin internos** (panel del tenant: `/api/v1/customer/{id}/cart`) **NO** son parte de esta API pública.

**Tipo `CartDto`** (response shape):

```typescript
interface CartDto {
  id: string;                          // GUID. Vacío implícito = "00000000-0000-0000-0000-000000000000"
  items: CartItemDto[];
  itemCount: number;                   // Suma de quantity de todos los items (badge del header)
  subtotal: number;                    // Suma de lineTotal (sin desglose de impuestos)
  priceListId: string | null;          // Lista usada para resolver precios. null = precio base.
  priceListName: string | null;        // Nombre legible: "Mayorista", "VIP", etc.
  isDefaultPriceList: boolean;         // true si la lista usada es la default del tenant
  updatedAt: string;                   // ISO-8601 UTC. Marca el inicio del TTL de 30 días.
}

interface CartItemDto {
  id: string;                          // GUID del item del carrito
  productId: string;
  productName: string;
  productImageUrl: string | null;      // URL de la imagen primaria del producto
  quantity: number;                    // Entero: el carrito se maneja por unidades
  unitPrice: number;                   // Precio resuelto al instante (lista del cliente o base)
  lineTotal: number;                   // unitPrice * quantity
  isActive: boolean;                   // false si el producto fue desactivado después de agregarlo
  isAvailable: boolean;                // false si ya no hay unidades disponibles para quantity (vendidas o apartadas) o si el producto está inactivo: mirá isActive primero
  taxName: string | null;              // Ej: "ISV 15%"
  taxPercentage: number;               // Ej: 15.0
  unitOfMeasurementSymbol: string | null;  // Ej: "und"
}
```

> Si `isActive` viene en `false`, mostrá el item en gris en la UI con el mensaje "este producto ya no está disponible". El backend permite el item en el carrito (no lo borra al desactivarse el producto), pero el checkout lo va a rechazar.
>
> Si `isAvailable` viene en `false`, no alcanzan las unidades para esa cantidad (se vendieron o las apartaron otros pedidos): mostralo como "Agotado" y pedí bajar la cantidad o quitarlo, o el checkout responderá `400`. Un producto inactivo también trae `isAvailable: false`: mirá `isActive` primero.

---

### 24. `GET /ecommerce-cart/me`

Obtiene el carrito del cliente logueado. **Recalcula precios al instante** contra la lista de precios actual.

**Sin query params, sin body.**

**Response 200 — `data`:** `CartDto`. Si el cliente nunca agregó nada, devuelve un carrito vacío implícito:

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "items": [],
  "itemCount": 0,
  "subtotal": 0,
  "priceListId": null,
  "priceListName": null,
  "isDefaultPriceList": false,
  "updatedAt": "0001-01-01T00:00:00Z"
}
```

**Uso típico:** badge "carrito (N)" en el header del storefront, vista del carrito antes del checkout.

---

### 25. `POST /ecommerce-cart/me/items`

Agrega un producto al carrito. **Si el producto ya está en el carrito, suma la cantidad** al item existente (no lo duplica).

**Body:**

```typescript
interface AddCartItemRequest {
  productId: string;     // GUID. Debe existir y pertenecer al tenant.
  quantity: number;      // Entero > 0 (un decimal responde 400). Si el item ya existe, la cantidad nueva = vieja + esta.
}
```

**Response 200 — `data`:** `CartDto` actualizado.

**Errores comunes:**
- `400` `"Producto no encontrado."` — `productId` no existe o pertenece a otro tenant.
- `400` `"El producto no esta disponible."` — el producto está marcado como `isActive = false`.
- `400` `"El producto '{nombre}' no tiene unidades disponibles en este momento."` — todo está vendido o apartado.
- `400` `"No hay suficientes unidades disponibles de '{nombre}' para la cantidad solicitada."` — la cantidad total supera lo disponible.
- `400` `"La cantidad debe ser mayor a 0."`
- `400` `"La cantidad maxima por item es 9999."` — la suma (existente + nuevo) excede el máximo.

---

### 26. `PUT /ecommerce-cart/me/items/{productId}`

Setea la cantidad **exacta** de un producto en el carrito. **Si `quantity = 0`, elimina el item** (atajo conveniente para que el front no tenga que distinguir entre "actualizar" y "borrar").

**Body:**

```typescript
interface UpdateCartItemRequest {
  quantity: number;      // Entero >= 0 (un decimal responde 400). 0 elimina el item.
}
```

**Response 200 — `data`:** `CartDto` actualizado.

**Errores comunes:**
- `400` `"Carrito vacio."` — el cliente no tiene un cart todavía (nunca agregó nada).
- `400` `"El producto no esta en el carrito."` — el `productId` no figura entre los items.
- `400` `"No hay suficientes unidades disponibles de '{nombre}' para la cantidad solicitada."` — solo al **subir** la cantidad.
- `400` `"La cantidad no puede ser negativa."`
- `400` `"La cantidad maxima por item es 9999."`

---

### 27. `DELETE /ecommerce-cart/me/items/{productId}`

Elimina un item del carrito. Sin body.

**Response 200 — `data`:** `CartDto` actualizado.

**Errores comunes:**
- `400` `"Carrito vacio."`
- `400` `"El producto no esta en el carrito."`

---

### 28. `DELETE /ecommerce-cart/me`

Vacía el carrito completo (borra todos los items, conserva el carrito en sí). Sin body.

**Response 200 — `data`:** `CartDto` vacío.

**Idempotente:** llamar este endpoint sobre un carrito ya vacío devuelve `200` igual.

---

## Pedidos del ecommerce (checkout)

El carrito se convierte en un **pedido**. `/ecommerce-orders` exige el bearer del cliente;
`/ecommerce-payment-types` solo la API Key.

**REGLA DURA: los totales los calcula el servidor.** El pedido se arma desde el carrito guardado, no
desde un body con precios. NO inventes campos de importe en el request de creación.

```typescript
enum OrderStatus { Pending = 0, Accepted = 1, Processing = 2, Shipped = 3, Delivered = 4, Cancelled = 5 }
enum PaymentTypeEcommerceBehavior { None = 0, RequiresProof = 1, RequiresLink = 2 }
enum OrderReservationState { None = 0, Active = 1, Expired = 2, Released = 3, Consumed = 4 }
```

**RESERVA DE STOCK (desde v2.13).** El checkout **aparta** los productos en el almacén por defecto de la sucursal
elegida, todo o nada: mientras dura, esas unidades no se ofrecen a otros pedidos ni se venden en las cajas (salvo que
el comercio facture sin stock, o en ventas de PedidosYa ya avisadas). Combos = sus componentes; servicios no apartan.
- Vence a las horas que configura el comercio (48 por defecto, o "no vence"): en `Pending`, si el comercio no lo acepta
  a tiempo; después, si no llega el pago. **Vencer solo libera las unidades: el pedido sigue abierto**
  (`reservationState: 2`); si después se acepta o se confirma el pago, vuelve a apartar si hay disponible.
- Aceptar reinicia el plazo si el pago requiere comprobante/link; con pago contra entrega o sin forma de pago elegida
  ya no vence. Subir el comprobante, que el comercio confirme el pago o pasar a Processing → sin vencimiento.
- Cancelar libera; facturar consume (`reservationState: 4`). Desde v2.14 el comercio también puede liberar la reserva a
  mano sin cambiar el pedido: si sigue abierto, vuelve a apartar cuando avanza o cuando el cliente sube el comprobante.
- `reservationExpiresAt` (UTC) con `reservationState === 1`: si el pedido está `Pending` (status 0), es hasta cuándo
  queda apartado mientras el comercio lo acepta (mostralo como "reservado hasta", el cliente todavía no puede pagar
  por el sistema); con status 1 y `preferredPaymentTypeBehavior` 1 o 2, es la hora límite para pagar.
- `reservationState`: `0` nada apartado (solo servicios, pedido anterior sin disponible, o su factura se anuló), `1`
  apartado, `2` vencido (pedido abierto), `3` liberado sin facturar (el pedido se canceló o se envió, o el comercio
  liberó la reserva a mano: mirá `status`, con `5` está cancelado y con `0`–`2` sigue abierto), `4` facturado (factura
  vigente).

---

### 29. `GET /ecommerce-payment-types`

Tipos de pago activos del tenant para el selector del checkout. **Solo API Key**, sin bearer. No paginado.

**Response 200 — `data`:**

```typescript
type PublicPaymentType = {
  id: string;
  name: string;
  // 0 None: nada extra | 1 RequiresProof: subir comprobante | 2 RequiresLink: el comercio manda paymentLink
  ecommerceBehavior: 0 | 1 | 2;
}[];
```

---

### 30. `POST /ecommerce-orders`

Crea un pedido desde el carrito del cliente autenticado. Vacía el carrito al terminar.

**Body:**

```typescript
type CreatePublicOrder = {
  branchOfficeId: string;            // requerido, de GET /branches
  shippingAddressId?: string | null; // omitir = retiro en sucursal
  preferredPaymentTypeId?: string | null;
  notes?: string | null;
};
```

**Response 200 — `data`:**

```typescript
type PublicOrder = {
  id: string;
  orderCode: string;                 // correlativo con prefijo "PE"
  branchOfficeId: string;
  branchOfficeName: string;
  shippingAddressId: string | null;
  shippingAddress: CustomerAddress | null;
  preferredPaymentTypeId: string | null;
  preferredPaymentTypeName: string | null;
  preferredPaymentTypeBehavior: 0 | 1 | 2;
  paymentLink: string | null;        // lo carga el comercio cuando el behavior es RequiresLink
  paymentProofUrl: string | null;
  paymentProofUploadedAt: string | null;
  paymentConfirmedAt: string | null; // el comercio confirmó el pago
  // Totales fiscales calculados por el backend (ISV Honduras)
  exempt: number; exonerated: number;
  taxableAmount15: number; taxableAmount18: number;
  tax15: number; tax18: number;
  subTotal: number; total: number;
  notes: string | null;
  status: OrderStatus;
  reservationState: OrderReservationState;
  reservationExpiresAt: string | null; // UTC; con Active = hasta cuándo están apartados (null = no vence)
  invoiceId: string | null;          // se llena cuando el comercio factura el pedido
  invoiceNumber: string | null;
  items: { id: string; productId: string | null; productName: string; quantity: number; unitPrice: number }[];
  itemCount: number;
  createdAt: string;
  updatedAt: string | null;
};
```

**Errores (`400`):**
- carrito vacío, o sucursal/dirección/tipo de pago de otro tenant.
- `"No hay unidades disponibles de '{producto}' en la sucursal {sucursal}. Disponible en: {A}, {B}."` — no alcanza en la
  sucursal elegida. **Nunca trae cantidades**; "Disponible en" (opcional) lista otras sucursales donde alcanza toda la
  línea. Si hay algunas pero no las suficientes: `"No hay suficientes unidades disponibles de '{producto}' en la sucursal {sucursal} para la cantidad solicitada."`
  Con varios productos: `"No hay unidades disponibles en la sucursal {sucursal} de: '{A}' (disponible en: …), '{B}' (no alcanza la cantidad). Quite esos productos del carrito, baje la cantidad o elija otra sucursal."`
  El carrito queda intacto y no se crea nada: mostrá el mensaje y dejá que el cliente cambie de sucursal o ajuste el carrito.
- `"La sucursal {sucursal} no tiene un almacén por defecto para despachar pedidos en línea. Elija otra sucursal."`
- `"El producto '{producto}' ya no está disponible."` — desactivado o eliminado después de agregarlo al carrito: quitá la
  línea con `isActive: false`; si ya no aparece en el carrito (eliminado), vaciá el carrito con `DELETE /ecommerce-cart/me`.
- transitorio: `"El inventario de uno de los productos se está actualizando en otra operación. Intente de nuevo en unos segundos."` → reintentar 1–2 veces.

---

### 31. `GET /ecommerce-orders`

Historial paginado del cliente autenticado, del más reciente al más viejo.
Params: `pageNumber` (default 1), `pageSize` (default 10, tope 200).

**Response 200 — `data`:** `Paginated<PublicOrder>`.

---

### 32. `GET /ecommerce-orders/{id}`

Detalle de un pedido del cliente autenticado. La query combina el id de la ruta con el `customerId` del
token → pedir el pedido de otro cliente no devuelve datos.

---

### 33. `PATCH /ecommerce-orders/{id}/cancel`

Cancela el pedido. **Solo si `status === 0` (Pending)**; una vez aceptado ya no lo cancela el cliente.
Libera la reserva de stock. Devuelve `data: true`: para mostrar el pedido actualizado (`status: 5`,
`reservationState: 3`) volvé a pedir `GET /ecommerce-orders/{id}`.

---

### 34. `POST /ecommerce-orders/{id}/payment-proof`

Adjunta o reemplaza el comprobante de pago. **`multipart/form-data`**, campo `file`.

Aplica solo si el tipo de pago preferido es `RequiresProof` (1) o `RequiresLink` (2) y el pedido está en
`Accepted`/`Processing`/`Shipped`. Devuelve el pedido con `paymentProofUrl` y `paymentProofUploadedAt`. Con el
comprobante la reserva deja de vencer (si ya había vencido, vuelve a apartar si queda disponible; el comprobante se
guarda igual).
El content-type del blob se deriva de la extensión validada, no del header que mandes.

---

### 35. `GET /geography/departments`

Listado completo de departamentos de Honduras. No paginado, no cambia frecuentemente — **cacheá agresivamente (24h+)**.

**Response 200 — `data`:**

```typescript
type Department = {
  id: string;
  name: string;
}[];
```

---

### 36. `GET /geography/departments/{departmentId}/cities`

Municipios/ciudades de un departamento. Usalo para selectores en cascada en los formularios de registro/perfil.

**Response 200 — `data`:**

```typescript
type City = {
  id: string;
  name: string;
  departmentId: string;
}[];
```

---

## Listas de precios para clientes logueados

Cuando un cliente está logueado y consume `/products` o `/products/{id}` enviando su `Authorization: Bearer`, el `salePrice` se resuelve contra la **lista de precios** que el tenant le tenga asignada desde el panel admin (CRM → Clientes).

**Reglas de resolución:**

1. **Sin bearer** → `salePrice` base del producto (catálogo público anónimo, sin cambios).
2. **Bearer + cliente con `priceListId` asignado** → precio de esa lista. Si el producto **no figura** en la lista, fallback al precio base.
3. **Bearer + cliente sin `priceListId`** → precio de la lista marcada como **default** del tenant. Si no hay default, precio base.
4. **`tenantId` del JWT ≠ `tenantId` de la API Key** → `403 Forbidden`.

**Implicancia para el cliente del API:**

- Cacheá las dos respuestas por separado: clave `products:anon` y clave `products:customer:<customerId>`.
- En el front: re-fetch del catálogo al hacer login y al hacer logout, para reflejar el cambio de precios.
- No expongas datos del costo/margen — la API nunca devuelve `costPrice` ni la lista interna.

---

## ARQUITECTURA RECOMENDADA PARA EL CONSUMIDOR

```
┌─────────────────┐    public requests    ┌──────────────────┐    private (with X-API-Key)    ┌─────────────────┐
│   Browser SPA   │──────────────────────▶│  Cliente backend │───────────────────────────────▶│   Ventix API    │
│  (Next.js, etc) │◀──────────────────────│   (BFF / proxy)  │◀──────────────────────────────│                 │
└─────────────────┘   JSON sin la key      └──────────────────┘     JSON con envelope         └─────────────────┘
                                                    │
                                                    ▼
                                           ┌──────────────────┐
                                           │   Cache (Redis,  │
                                           │   Memcached, in- │
                                           │   memory, etc)   │
                                           └──────────────────┘
```

**Por qué este patrón:**
1. **Seguridad**: la key vive en variables de entorno del backend del cliente, jamás llega al navegador.
2. **Caching**: el cliente puede cachear agresivamente y reducir latencia + carga.
3. **Rate limit**: 600 req/min se reparten entre todos los visitantes del cliente, no se queman desde una IP popular.
4. **Versionado**: si Ventix saca v2, el cliente cambia solo su backend, no toca el front.

---

## CLIENTE TIPO PARA COPIAR/ADAPTAR

### Node.js / TypeScript (catálogo + auth + perfil, con retry)

```typescript
// ventix-client.ts
const BASE = "https://ventix-api.smartbusiness.site/api/public/v1";
const KEY  = process.env.VENTIX_API_KEY!;

interface ApiEnvelope<T> {
  succeeded: boolean;
  message: string;
  data: T | null;
  errors: string[];
}

class RateLimitError extends Error {
  constructor(public retryAfter: number) {
    super(`Rate limited. Retry in ${retryAfter}s`);
  }
}

export class EmailNotConfirmedError extends Error {
  constructor() { super("EMAIL_NOT_CONFIRMED"); }
}

interface CallOptions {
  method?: "GET" | "POST" | "PUT";
  body?: unknown;
  bearer?: string;          // JWT del cliente del ecommerce
  params?: Record<string, string | number | undefined>;
  retries?: number;
}

async function ventix<T>(path: string, opts: CallOptions = {}): Promise<T> {
  const { method = "GET", body, bearer, params = {}, retries = 3 } = opts;

  const url = new URL(BASE + path);
  for (const [k, v] of Object.entries(params)) {
    if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
  }

  const headers: Record<string, string> = {
    "X-API-Key": KEY,
    "Accept": "application/json"
  };
  if (bearer) headers["Authorization"] = `Bearer ${bearer}`;
  if (body !== undefined) headers["Content-Type"] = "application/json";

  const res = await fetch(url, {
    method,
    headers,
    body: body !== undefined ? JSON.stringify(body) : undefined
  });

  if (res.status === 429) {
    const retry = Number(res.headers.get("Retry-After") || 5);
    if (retries > 0) {
      await new Promise(r => setTimeout(r, retry * 1000));
      return ventix<T>(path, { ...opts, retries: retries - 1 });
    }
    throw new RateLimitError(retry);
  }

  if (res.status >= 500 && retries > 0) {
    await new Promise(r => setTimeout(r, (4 - retries) * 1000));
    return ventix<T>(path, { ...opts, retries: retries - 1 });
  }

  const envelope: ApiEnvelope<T> = await res.json();
  if (!res.ok || !envelope.succeeded) {
    const msg = envelope.message || `HTTP ${res.status}`;
    if (msg.includes("EMAIL_NOT_CONFIRMED")) throw new EmailNotConfirmedError();
    throw new Error(msg);
  }
  return envelope.data as T;
}

// Tipos del dominio (copiá los que estén en el archivo)
export interface PublicStoreInfo        { /* ... */ }
export interface PublicProduct          { /* ... */ }
export interface PublicCategory         { id: string; name: string; }
export interface PublicBranch           { /* ... */ }
export interface PublicProductInventory { /* ... */ }
export interface PaginatedResult<T>     { items: T[]; /* ... */ }

export interface EcommerceCustomer {
  id: string;
  firstName: string;
  lastName: string | null;
  email: string | null;
  phoneNumber: string | null;
  gender: "Male" | "Female" | "Other" | "Unspecified" | null;
  departmentId: string | null;
  departmentName: string | null;
  cityId: string | null;
  cityName: string | null;
  emailConfirmed: boolean;
  ecommerceRegisteredAt: string | null;
}

export interface SignInResponse {
  accessToken: string;
  expiresAt: string;
  customer: EcommerceCustomer;
}

export interface Department { id: string; name: string; }
export interface City       { id: string; name: string; departmentId: string; }

export interface CustomerAddress {
  id: string;
  label: string | null;
  recipientName: string;
  phoneNumber: string;
  departmentId: string;
  departmentName: string;
  cityId: string;
  cityName: string;
  addressLine1: string;
  addressLine2: string | null;
  reference: string | null;
  isDefault: boolean;
  createdAt: string;
  updatedAt: string | null;
}

export interface AddressBody {
  label?: string;
  recipientName: string;
  phoneNumber: string;
  departmentId: string;
  cityId: string;
  addressLine1: string;
  addressLine2?: string;
  reference?: string;
  isDefault: boolean;
}

export interface CartItemDto {
  id: string;
  productId: string;
  productName: string;
  productImageUrl: string | null;
  quantity: number;
  unitPrice: number;
  lineTotal: number;
  isActive: boolean;
  taxName: string | null;
  taxPercentage: number;
  unitOfMeasurementSymbol: string | null;
}

export interface CartDto {
  id: string;
  items: CartItemDto[];
  itemCount: number;
  subtotal: number;
  priceListId: string | null;
  priceListName: string | null;
  isDefaultPriceList: boolean;
  updatedAt: string;
}

// API agrupada por área
export const Ventix = {
  // — Catálogo —
  store:      () => ventix<PublicStoreInfo>("/store/info"),
  products:   (q: { pageNumber?: number; pageSize?: number; search?: string; categoryId?: string } = {}, bearer?: string) =>
              ventix<PaginatedResult<PublicProduct>>("/products", { params: q, bearer }),
  product:    (id: string, bearer?: string) =>
              ventix<PublicProduct>(`/products/${id}`, { bearer }),
  search:     (q: string, page = 1, bearer?: string) =>
              ventix<PaginatedResult<PublicProduct>>("/products/search", { params: { q, pageNumber: page }, bearer }),
  categories: () => ventix<PublicCategory[]>("/categories"),
  branches:   () => ventix<PublicBranch[]>("/branches"),
  inventory:  (productId: string) => ventix<PublicProductInventory>(`/inventory/products/${productId}`),

  // — Auth del cliente del ecommerce —
  auth: {
    signUp:                 (body: { email: string; password: string; firstName: string; lastName?: string; phoneNumber?: string; gender?: string; departmentId?: string; cityId?: string }) =>
                            ventix<string>("/ecommerce-auth/signup", { method: "POST", body }),
    verifyEmail:            (body: { email: string; pin: string }) =>
                            ventix<string>("/ecommerce-auth/verify-email", { method: "POST", body }),
    resendVerification:     (body: { email: string }) =>
                            ventix<string>("/ecommerce-auth/resend-verification", { method: "POST", body }),
    signIn:                 (body: { email: string; password: string }) =>
                            ventix<SignInResponse>("/ecommerce-auth/signin", { method: "POST", body }),
    requestPasswordReset:   (body: { email: string }) =>
                            ventix<string>("/ecommerce-auth/request-password-reset", { method: "POST", body }),
    resetPassword:          (body: { email: string; pin: string; newPassword: string }) =>
                            ventix<string>("/ecommerce-auth/reset-password", { method: "POST", body })
  },

  // — Perfil del cliente logueado —
  profile: {
    me:     (bearer: string) =>
            ventix<EcommerceCustomer>("/ecommerce-profile/me", { bearer }),
    update: (bearer: string, body: { firstName: string; lastName?: string; email?: string; phoneNumber?: string; gender?: string; departmentId?: string; cityId?: string }) =>
            ventix<EcommerceCustomer>("/ecommerce-profile/me", { method: "PUT", bearer, body }),

    // — Direcciones de envío del cliente logueado —
    addresses: {
      list:       (bearer: string) =>
                  ventix<CustomerAddress[]>("/ecommerce-profile/addresses", { bearer }),
      byId:       (bearer: string, id: string) =>
                  ventix<CustomerAddress>(`/ecommerce-profile/addresses/${id}`, { bearer }),
      create:     (bearer: string, body: AddressBody) =>
                  ventix<CustomerAddress>("/ecommerce-profile/addresses", { method: "POST", bearer, body }),
      update:     (bearer: string, id: string, body: AddressBody) =>
                  ventix<CustomerAddress>(`/ecommerce-profile/addresses/${id}`, { method: "PUT", bearer, body }),
      remove:     (bearer: string, id: string) =>
                  ventix<boolean>(`/ecommerce-profile/addresses/${id}`, { method: "DELETE", bearer }),
      setDefault: (bearer: string, id: string) =>
                  ventix<CustomerAddress>(`/ecommerce-profile/addresses/${id}/set-default`, { method: "POST", bearer })
    }
  },

  // — Carrito persistente cross-device —
  cart: {
    me:           (bearer: string) =>
                  ventix<CartDto>("/ecommerce-cart/me", { bearer }),
    addItem:      (bearer: string, body: { productId: string; quantity: number }) =>
                  ventix<CartDto>("/ecommerce-cart/me/items", { method: "POST", bearer, body }),
    setQuantity:  (bearer: string, productId: string, quantity: number) =>
                  ventix<CartDto>(`/ecommerce-cart/me/items/${productId}`, { method: "PUT", bearer, body: { quantity } }),
    removeItem:   (bearer: string, productId: string) =>
                  ventix<CartDto>(`/ecommerce-cart/me/items/${productId}`, { method: "DELETE", bearer }),
    clear:        (bearer: string) =>
                  ventix<CartDto>("/ecommerce-cart/me", { method: "DELETE", bearer })
  },

  // — Geografía (Honduras) —
  geography: {
    departments:           () => ventix<Department[]>("/geography/departments"),
    citiesByDepartment:    (departmentId: string) =>
                          ventix<City[]>(`/geography/departments/${departmentId}/cities`)
  }
};
```

### Python (con `requests` + retry/backoff)

```python
import os, time, requests
from typing import Any, Optional

BASE = "https://ventix-api.smartbusiness.site/api/public/v1"
KEY  = os.environ["VENTIX_API_KEY"]


def ventix(path: str, retries: int = 3, **params) -> Any:
    res = requests.get(
        BASE + path,
        params={k: v for k, v in params.items() if v is not None},
        headers={"X-API-Key": KEY, "Accept": "application/json"},
        timeout=10,
    )

    if res.status_code == 429 and retries > 0:
        retry_after = int(res.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return ventix(path, retries - 1, **params)

    if res.status_code >= 500 and retries > 0:
        time.sleep(2 ** (3 - retries))
        return ventix(path, retries - 1, **params)

    body = res.json()
    if not res.ok or not body.get("succeeded"):
        raise RuntimeError(body.get("message") or f"HTTP {res.status_code}")
    return body["data"]


# Convenience wrappers
def store():                           return ventix("/store/info")
def products(**kw):                    return ventix("/products", **kw)
def product(pid: str):                 return ventix(f"/products/{pid}")
def search(q: str, page: int = 1):     return ventix("/products/search", q=q, pageNumber=page)
def categories():                      return ventix("/categories")
def branches():                        return ventix("/branches")
def inventory(pid: str):               return ventix(f"/inventory/products/{pid}")
```

---

## RECETAS COMUNES

### Receta 1: Listado de productos con filtro por categoría y paginación

```typescript
// Next.js Route Handler — proxy con cache de 60s
import { Ventix } from "@/lib/ventix-client";
import { NextResponse } from "next/server";

export const revalidate = 60;  // ISR: cache 60s

export async function GET(req: Request) {
  const url = new URL(req.url);
  const params = {
    pageNumber: Number(url.searchParams.get("page") || 1),
    pageSize:   20,
    search:     url.searchParams.get("q") || undefined,
    categoryId: url.searchParams.get("category") || undefined,
  };

  const data = await Ventix.products(params);
  return NextResponse.json(data);
}
```

### Receta 2: Detalle de producto con stock por sucursal en paralelo

```typescript
// Aprovechamos Promise.all para ahorrar latencia
const [product, inventory] = await Promise.all([
  Ventix.product(id),          // sin disponible NO da 404: llega con isAvailable = false
  Ventix.inventory(id)
]);

return {
  ...product,
  soldOut: !product.isAvailable,   // badge "Agotado" + botón de compra deshabilitado
  // stock por sucursal = DISPONIBLE (existencia − apartado por pedidos). Combos y servicios traen branches: []
  availability: inventory.branches.filter(b => b.stock > 0)
};
```

### Receta 3: Buscador con autocomplete (debounced)

```typescript
import { useEffect, useState } from "react";
import { useDebouncedCallback } from "use-debounce";

export function useProductSearch() {
  const [results, setResults] = useState<PublicProduct[]>([]);
  const [loading, setLoading] = useState(false);

  const search = useDebouncedCallback(async (q: string) => {
    if (q.length < 2) { setResults([]); return; }
    setLoading(true);
    try {
      const res = await fetch(`/api/catalog/search?q=${encodeURIComponent(q)}`);
      const data = await res.json();
      setResults(data.items);
    } finally {
      setLoading(false);
    }
  }, 300);

  return { results, loading, search };
}
```

### Receta 4: Mostrar precio respetando `priceIncludesTax`

```typescript
function displayPrice(product: PublicProduct, store: PublicStoreInfo): {
  price: number;
  taxBreakdown: string;
} {
  if (store.priceIncludesTax) {
    // El salePrice ya incluye ISV
    return { price: product.salePrice, taxBreakdown: `Incluye ${product.taxName}` };
  } else {
    // Sumar ISV
    const tax    = product.salePrice * (product.taxPercentage / 100);
    const total  = product.salePrice + tax;
    return { price: total, taxBreakdown: `+ ${product.taxName} (L. ${tax.toFixed(2)})` };
  }
}
```

### Receta 5: Cache layer con TTL diferenciado

```typescript
// Pseudo-código con un KV store cualquiera (Redis, Vercel KV, Cloudflare KV, etc.)
const TTL = {
  store:      3600,   // 1 hora
  categories: 3600,   // 1 hora
  branches:   3600,   // 1 hora
  products:   300,    // 5 min
  product:    300,    // 5 min
  inventory:  20,     // 20 segundos (más volátil: es el disponible, cambia con cada pedido)
};

async function cached<T>(key: string, ttl: number, fetcher: () => Promise<T>): Promise<T> {
  const hit = await kv.get<T>(key);
  if (hit) return hit;
  const fresh = await fetcher();
  await kv.set(key, fresh, { ex: ttl });
  return fresh;
}

// Uso
const products = await cached(
  `vtx:products:p${page}:c${categoryId ?? "all"}`,
  TTL.products,
  () => Ventix.products({ pageNumber: page, categoryId })
);
```

### Receta 6: Flujo de registro del cliente del ecommerce (signup + verify)

```typescript
// Paso 1 — el cliente envía el form del signup en tu storefront
async function registerCustomer(form: SignUpForm) {
  await Ventix.auth.signUp({
    email:        form.email,
    password:     form.password,
    firstName:    form.firstName,
    lastName:     form.lastName,
    phoneNumber:  form.phoneNumber,
    gender:       form.gender,
    departmentId: form.departmentId,
    cityId:       form.cityId
  });
  // Redirigir a la pantalla "Revisá tu correo e ingresá el PIN"
  router.push(`/verificar-correo?email=${encodeURIComponent(form.email)}`);
}

// Paso 2 — el cliente ingresa el PIN de 6 dígitos
async function confirmEmail(email: string, pin: string) {
  await Ventix.auth.verifyEmail({ email, pin });
  router.push("/login?confirmed=1");
}

// Si el cliente no recibió el correo
async function resendPin(email: string) {
  await Ventix.auth.resendVerification({ email });
  toast.success("Te enviamos un nuevo codigo.");
}
```

### Receta 7: Login + manejo de `EMAIL_NOT_CONFIRMED` + persistir sesión

```typescript
async function login(email: string, password: string) {
  try {
    const session = await Ventix.auth.signIn({ email, password });

    sessionStorage.setItem("ventix_jwt", session.accessToken);
    sessionStorage.setItem("ventix_jwt_exp", session.expiresAt);

    // Re-fetch del catálogo para que muestre los precios del cliente
    queryClient.invalidateQueries({ queryKey: ["products"] });

    return session.customer;
  } catch (err) {
    if (err instanceof EmailNotConfirmedError) {
      router.push(`/verificar-correo?email=${encodeURIComponent(email)}`);
      return null;
    }
    throw err;
  }
}

// Hook que devuelve el bearer si la sesión está vigente
export function useVentixBearer(): string | null {
  const token = sessionStorage.getItem("ventix_jwt");
  const exp   = sessionStorage.getItem("ventix_jwt_exp");
  if (!token || !exp) return null;
  if (new Date(exp).getTime() <= Date.now()) {
    sessionStorage.removeItem("ventix_jwt");
    sessionStorage.removeItem("ventix_jwt_exp");
    return null;
  }
  return token;
}
```

### Receta 8: Recuperación de contraseña (3 pasos)

```typescript
// 1. Pedir el PIN
await Ventix.auth.requestPasswordReset({ email });

// 2. Cliente ingresa el PIN del correo + la nueva contraseña
await Ventix.auth.resetPassword({
  email,
  pin: "874201",
  newPassword: "OtraClaveMejor456"
});

// 3. Ya puede loguearse con la nueva contraseña
await Ventix.auth.signIn({ email, password: "OtraClaveMejor456" });
```

### Receta 9: Catálogo con precios resueltos por cliente

```typescript
// React/Next.js: pasamos el bearer si hay sesión activa
export function useProducts(filters: Filters) {
  const bearer = useVentixBearer();   // null si no hay sesión

  return useQuery({
    // Importante: la key incluye el customerId implícito o "anon"
    queryKey: ["products", filters, bearer ? "customer" : "anon"],
    queryFn: () => Ventix.products(filters, bearer ?? undefined),
    staleTime: 5 * 60 * 1000   // 5 min
  });
}
```

### Receta 11: Gestión de direcciones de envío del cliente

```typescript
// Listar direcciones del cliente (default primero)
const addresses = await Ventix.profile.addresses.list(bearer);

// Crear una dirección nueva (si es la primera, queda default automáticamente)
const created = await Ventix.profile.addresses.create(bearer, {
  label:         "Casa",
  recipientName: "Ana Flores",
  phoneNumber:   "9999-0000",
  departmentId:  depto.id,
  cityId:        ciudad.id,
  addressLine1:  "Col. Trejo, 3a calle, casa 12",
  addressLine2:  null,
  reference:     "Frente al parque central",
  isDefault:     true   // ignorado si es la primera; será true igual
});

// Actualizar (cambio de teléfono)
const updated = await Ventix.profile.addresses.update(bearer, created.id, {
  ...created,
  phoneNumber: "9999-1234"
});

// Cambiar la default a OTRA dirección (no podés "desmarcar" via PUT)
await Ventix.profile.addresses.setDefault(bearer, otherAddress.id);

// Eliminar (si era la default, otra queda como default automáticamente)
await Ventix.profile.addresses.remove(bearer, addressId);
```

**UI tip — selector de envío en checkout:**

```typescript
const addresses = await Ventix.profile.addresses.list(bearer);
const defaultAddress = addresses.find(a => a.isDefault) ?? addresses[0];

// Pre-seleccionar la default. Si el cliente cambia, opcionalmente persistir
// el cambio con setDefault para futuras compras:
if (selectedId !== defaultAddress?.id) {
  await Ventix.profile.addresses.setDefault(bearer, selectedId);
}
```

### Receta 12: Carrito persistente cross-device

```typescript
// 1. Leer el carrito (recalcula precios contra la lista actual del cliente)
let cart = await Ventix.cart.me(bearer);
console.log(`${cart.itemCount} items, subtotal L. ${cart.subtotal}`);

// 2. Agregar producto. Si ya estaba, la cantidad SE SUMA al item existente.
cart = await Ventix.cart.addItem(bearer, { productId, quantity: 2 });

// 3. Cambiar la cantidad exacta. quantity:0 elimina el item.
cart = await Ventix.cart.setQuantity(bearer, productId, 5);

// 4. Eliminar un item explícitamente
cart = await Ventix.cart.removeItem(bearer, productId);

// 5. Vaciar el carrito completo
cart = await Ventix.cart.clear(bearer);
```

**UI tip — badge del header con item count (refresca al cambiar de ruta):**

```typescript
export function useCartBadge(bearer: string | null) {
  return useQuery({
    queryKey: ["cart", bearer ? "customer" : "anon"],
    queryFn:  () => bearer ? Ventix.cart.me(bearer) : Promise.resolve({ itemCount: 0 } as CartDto),
    enabled:  !!bearer,
    staleTime: 30 * 1000   // 30 seg — los precios pueden cambiar
  });
}

// Componente
const { data: cart } = useCartBadge(bearer);
return <Badge>{cart?.itemCount || 0}</Badge>;
```

**UI tip — items inactivos en la vista del carrito:**

```typescript
const cart = await Ventix.cart.me(bearer);

const activeItems   = cart.items.filter(i => i.isActive);
const inactiveItems = cart.items.filter(i => !i.isActive);

// Mostrá los inactivos en gris con mensaje "Este producto ya no está disponible"
// y bloqueá el botón de checkout hasta que el cliente los elimine.
const canCheckout = inactiveItems.length === 0 && activeItems.length > 0;
```

### Receta 10: Form de perfil con dropdowns en cascada Departamento → Municipio

```typescript
export function ProfileForm({ bearer }: { bearer: string }) {
  const { data: me } = useQuery({ queryKey: ["me"], queryFn: () => Ventix.profile.me(bearer) });
  const { data: departments } = useQuery({ queryKey: ["geography:departments"], queryFn: Ventix.geography.departments, staleTime: 24 * 3600_000 });

  const [departmentId, setDepartmentId] = useState(me?.departmentId ?? null);
  const { data: cities } = useQuery({
    queryKey: ["geography:cities", departmentId],
    queryFn:  () => departmentId ? Ventix.geography.citiesByDepartment(departmentId) : Promise.resolve([]),
    enabled:  !!departmentId,
    staleTime: 24 * 3600_000
  });

  async function onSubmit(form: FormValues) {
    const updated = await Ventix.profile.update(bearer, {
      firstName:    form.firstName,
      lastName:     form.lastName,
      email:        form.email,                // si cambió, dispara nuevo PIN
      phoneNumber:  form.phoneNumber,
      gender:       form.gender,
      departmentId: form.departmentId,
      cityId:       form.cityId
    });

    if (form.email !== me?.email) {
      router.push(`/verificar-correo?email=${encodeURIComponent(updated.email!)}`);
    }
  }

  // ...form JSX con <select> alimentados por departments y cities
}
```

---

## CHECKLIST DE PRODUCCIÓN

Antes de salir a prod con tu integración, validá:

- [ ] La API Key vive en una variable de entorno del backend, no en código fuente ni en bundles del cliente.
- [ ] Tenés una segunda key para staging/dev separada de prod.
- [ ] Implementaste retry con backoff exponencial para `5xx` y `429`.
- [ ] **No** hacés retry automático para `4xx`.
- [ ] Cacheás `/products`, `/categories`, `/branches` con TTL mínimo 1 minuto.
- [ ] Cacheás `/store/info` por al menos 1 hora.
- [ ] Cacheás `/inventory/products/{id}` con TTL corto (10-30s): es el disponible y cambia con cada pedido.
- [ ] Cacheás `/geography/departments` y `/geography/.../cities` por 24h+ (no cambian).
- [ ] El cache de `/products` distingue entre **anónimo** y **por customerId** (claves separadas) — los precios resueltos son por cliente.
- [ ] Re-fetcheás el catálogo al hacer login y logout para que reflejen los precios correctos.
- [ ] Manejás `EMAIL_NOT_CONFIRMED` con redirect al flujo de verificación, no como "credenciales inválidas".
- [ ] El JWT del cliente se guarda en `sessionStorage`/`localStorage` (ok que esté en el navegador) y se respeta `expiresAt`.
- [ ] Cuando el cliente cambia su `email` desde `PUT /me`, lo llevás a verificar el nuevo correo.
- [ ] Manejás `403` con un mensaje útil ("Tu plan no incluye esta funcionalidad" — pasarle el mensaje al admin del cliente).
- [ ] Manejás `404` sin mostrar errores rojos al usuario final (producto removido del catálogo).
- [ ] Usás `hasNextPage` para paginar, no `totalCount`.
- [ ] Respetás `priceIncludesTax` al mostrar precios.
- [ ] Mostrás los productos con `isAvailable: false` como "Agotado" (botón de compra deshabilitado) y **no** los filtrás en el cliente: rompe la paginación.
- [ ] No mandás la API Key como query string nunca.
- [ ] El backend tiene logging que NO loguea el header `X-API-Key` ni el `Authorization`.
- [ ] Tenés un plan para revocar la API Key si se compromete (acceso al panel de Ventix del cliente).
- [ ] Al crear direcciones desde el storefront, validás client-side que `cityId` pertenezca al `departmentId` seleccionado (la API lo valida también, pero el feedback inmediato es mejor UX).
- [ ] En el checkout, pre-seleccionás la dirección con `isDefault: true` y permitís al cliente cambiarla. Opcionalmente llamás `set-default` para persistir el cambio.
- [ ] El botón "Agregar al carrito" solo se habilita si el cliente está logueado (no hay carritos anónimos en esta API).
- [ ] Refrescás el badge del carrito cuando el cliente cambia de página (los precios se recalculan al instante en cada `GET /ecommerce-cart/me`).
- [ ] En la vista del carrito, mostrás items con `isActive: false` en gris y bloqueás el checkout hasta que el cliente los elimine.
- [ ] Capeás la cantidad por item a 9999 desde el front (la API valida pero el feedback inmediato es mejor UX).
- [ ] Documentás a tus clientes que los carritos abandonados expiran a los 30 días de inactividad.

---

## REGLAS DURAS PARA EL LLM

Cuando generés código:

1. **NO inventes endpoints**. Estas reglas aplican al **storefront** (30 endpoints): 9 de catálogo (`/store/info`, `/products`, `/products/{id}`, `/products/search`, `/categories`, `/branches`, `/inventory/products/{id}`, `/sections`, `/sections/{id}/products`), 6 de auth (`/ecommerce-auth/{signup,verify-email,resend-verification,signin,request-password-reset,reset-password}`), 2 de perfil (`GET/PUT /ecommerce-profile/me`), 6 de direcciones (`GET/POST /ecommerce-profile/addresses`, `GET/PUT/DELETE /.../{id}`, `POST /.../{id}/set-default`), 5 de carrito (`GET /ecommerce-cart/me`, `POST /ecommerce-cart/me/items`, `PUT/DELETE /ecommerce-cart/me/items/{productId}`, `DELETE /ecommerce-cart/me`), 2 de geografía (`/geography/departments`, `/geography/departments/{id}/cities`). **La API de INTEGRACIÓN (`/api/public/v1/integration/…`) es aparte y SÍ existe**: expone CRUD completo (`GET/POST/PUT/PATCH/DELETE`) + multipart + bulk-import sobre catálogos, inventario, CRM, ventas, facturación, compras, contabilidad y settings — sus endpoints están en la sección **INTEGRACIÓN — ENDPOINTS**. No niegues su existencia.
2. **NO inventes campos en los DTOs**. Si el dev pide un campo que no está en el schema del **storefront** (ej: "muéstrame el costo" en `/products`), explicá que el storefront no expone ese dato. (En la API de **INTEGRACIÓN** el costo/valuación sí se expone con los scopes `inventory:cost:read`/`purchasing:read`/`reports:financial:read`.)
3. **NO sugieras `POST`/`PUT`/`PATCH`/`DELETE` para el catálogo o la geografía del STOREFRONT**. Esos endpoints del storefront son **read-only** (solo auth y perfil aceptan escritura). ⚠️ Esto NO aplica a la API de **INTEGRACIÓN**: ahí el catálogo (products/brands/productfamilies), inventario, ventas, facturación, compras, contabilidad y settings **sí** aceptan `POST`/`PUT`/`PATCH`/`DELETE` (según el scope de la key) + multipart/bulk-import.
4. **NO sugieras pasar la API Key por query string ni por cookie**. Solo header `X-API-Key`.
5. **NO sugieras llamar la API desde código que corre en el navegador con la API Key embedded**. Siempre usá el patrón "BFF/proxy en el backend del cliente". El **JWT del cliente** sí puede vivir en el navegador.
6. **NO hardcodees la API Key** en los ejemplos — usá variable de entorno (`process.env.VENTIX_API_KEY` o equivalente).
7. **NO uses la API Key del tenant para identificar a un cliente final** del ecommerce. Para eso está el JWT (`/ecommerce-auth/signin`).
8. **NO ignores `EMAIL_NOT_CONFIRMED`**. Si el `signin` falla con ese código en el `message`, hay que redirigir al flujo de PIN, no mostrar "contraseña incorrecta".
9. **NO asumas que existe un refresh token**. No hay. Cuando `expiresAt` del JWT pase, el cliente vuelve a llamar `signin`.
10. **SÍ recordá manejar `429`** con `Retry-After` y backoff exponencial.
11. **SÍ recordá** que la API devuelve un envelope `{ succeeded, message, data, errors }` — siempre extraé `data` antes de pasar al UI.
12. **SÍ recordá** la regla de `priceIncludesTax` cuando estés mostrando precios.
13. **SÍ recordá** que el catálogo está aislado por tenant automáticamente — si el dev intenta filtrar por `tenantId` desde el cliente, ese parámetro **no existe** y es innecesario.
14. **SÍ recordá** que `/products` y `/products/{id}` aceptan `Authorization: Bearer` **opcional** para resolver precios por cliente. Sin bearer = precio base.
15. **SÍ recordá** que cambiar `email` en `PUT /ecommerce-profile/me` invalida `emailConfirmed` y dispara un nuevo PIN al **nuevo** correo.
16. **SÍ recordá** que `cityId` requiere un `departmentId` consistente (el municipio debe pertenecer al departamento). Implementá selectores en cascada.
17. **SÍ recordá** que las direcciones de envío (`/ecommerce-profile/addresses/*`) requieren bearer y son CRUD completo. La primera dirección queda default automáticamente; al marcar otra como default, las demás se desmarcan en la misma transacción. `PUT` con `isDefault: false` **no** quita el flag si ya era default — usá `set-default` sobre otra dirección.
18. **NO sugieras "promover" una dirección manualmente al borrar la default**. El backend ya lo hace automáticamente: al eliminar la default cuando hay otras, la más reciente queda como nueva default.
19. **NO sugieras carritos anónimos** ni guardar el carrito en `localStorage` del navegador. El carrito vive en el server e identifica al cliente por su JWT — sin login no hay carrito. Si el dev necesita "carrito antes del login", la única forma es pedir login primero.
20. **NO snapshotees precios del carrito en el front**. El backend ya recalcula `unitPrice` y `lineTotal` en cada `GET /ecommerce-cart/me` contra la lista actual del cliente. Mostrá el resultado del backend tal cual.
21. **El carrito valida el DISPONIBLE** (desde v2.13): `POST /ecommerce-cart/me/items` y subir la cantidad con `PUT` responden `400` si no alcanzan las unidades disponibles (existencia menos lo apartado por otros pedidos); bajar nunca se bloquea. Es orientativo: el checkout valida otra vez en la sucursal y aparta las unidades. Manejá ese `400` mostrando el mensaje, y usá `isAvailable` de cada línea para marcar lo agotado.
22. **SÍ recordá que `PUT /ecommerce-cart/me/items/{productId}` con `quantity: 0` elimina el item** (atajo conveniente). No hay que llamar `DELETE` por separado para `quantity: 0`.
23. **SÍ recordá que `POST /ecommerce-cart/me/items` SUMA cantidad si el producto ya está**, no la sobrescribe. Para reemplazar la cantidad, usá `PUT`.
24. **NO inventes endpoints `/ecommerce-cart` admin**. Los endpoints internos del panel admin (`/api/v1/customer/{id}/cart`) NO son parte de esta API pública.
25. **NO filtres por `isAvailable` en el cliente** (desde v2.14): rompe la paginación (`totalCount`, `totalPages` y `hasNextPage` los calcula el servidor). Mostralo como "Agotado", con el botón de compra deshabilitado. El servidor ya decide qué se lista: sin `showOutOfStockProducts` no trae los productos sin disponible, y `/products/{id}` los devuelve siempre (no da 404).

---

## CASOS DE USO REALES (para inspirar al dev)

- **Tienda online B2C con cuentas de clientes**: catálogo + signup/login del comprador + perfil + direcciones + **carrito persistente cross-device** + redirección a WhatsApp para confirmar el pedido. Los clientes ven precios públicos antes de loguearse y precios "Mayorista"/"VIP" después de iniciar sesión, con su carrito siguiéndolos entre dispositivos (el POST de pedidos del storefront llegará en una versión futura; para crear/facturar desde un backend propio, usá la API de Integración).
- **Portal B2B con listas de precios diferenciadas**: cada cliente del negocio tiene su lista asignada desde el panel; en el storefront solo ven sus precios al iniciar sesión.
- **App móvil de catálogo**: vendedores externos consultan precios y stock por sucursal antes de visitar al cliente.
- **Kiosco/totem en local**: pantalla touch que muestra catálogo y disponibilidad.
- **Marketplace**: agregador de varios negocios; cada negocio configura su propia key.
- **Sincronización con ERP**: leer catálogo y reflejar cambios en otro sistema.
- **Bot de WhatsApp**: el cliente pregunta por un producto, el bot llama `/products/search` y responde con foto + precio + stock por sucursal.
- **Programa de fidelidad con auto-registro**: la marca quiere que sus clientes se registren para acceder a precios preferenciales; usa `/ecommerce-auth/*` + listas de precios.

---

## CHANGELOG

- **v2.25 (2026-11-08)**: **`profit-margins` calcula la venta sin ISV**, igual que `profit-margins-by-invoice` y que el costo. `revenue`, `profit` y `marginPercent` bajan en los productos con impuesto.
- **v2.24 (2026-11-04)**: **`Idempotency-Key` al crear facturas** (`POST /integration/invoices`). Header opcional: reintentar con la misma clave devuelve la factura ya creada (`200`, mismo `id` y número) sin consumir otro correlativo ni descontar stock; la misma clave con otro cliente u otras líneas responde `400`. Sin el header, nada cambia.
- **v2.23 (2026-10-11)**: **El Kardex cuadra** (`/integration/kardex/{productId}`, con su PDF y Excel). Con `includeCancelled=false`, antes se ocultaba la reversa de un documento anulado pero la venta anulada seguía restando, y el saldo inicial más las entradas menos las salidas no daba el final; ahora se ocultan juntas (si la venta es anterior al período, la reversa se muestra porque explica el saldo). Sin `warehouseId`, `closingBalance` era el saldo de la bodega del último movimiento; ahora suma todas, igual que `openingBalance`. El saldo de cada movimiento sigue siendo el de su bodega.
- **v2.22 (2026-10-11)**: **Stock bajo sin servicios ni combos** (`/integration/reports/low-stock` y `/integration/reports/restock-recommendations`, con sus PDF y Excel). Los servicios y los combos nacen con existencia 0 y no llevan inventario: antes salían como agotados y con compra sugerida (en un restaurante, todos los platillos). Ahora los dos reportes traen solo productos.
- **v2.21 (2026-10-11)**: **Stock con decimales**. El stock es un número: en los productos que el comercio marca como «Se maneja por peso o volumen» (solo con unidades de peso o volumen) puede tener hasta 3 decimales; en los demás sigue saliendo entero, sin `.000`. Afecta al stock de productos, bodegas, secciones y `/inventory/products/{id}`, y a las cantidades de entradas, salidas y traslados de la integración, que aceptan decimales solo para esos productos (un producto entero sigue respondiendo `400` con una cantidad fraccionaria). En facturas, notas, cotizaciones y órdenes de compra esos productos admiten hasta 2 decimales por línea. `virtualStock` y el carrito siguen enteros. En el storefront, un producto por peso o volumen tiene `isAvailable: true` desde 0.001 de disponible, aunque el carrito pide como mínimo 1. Se corrigió la documentación del carrito: `quantity` es un entero. Las líneas de facturas, facturas manuales, cotizaciones, órdenes de compra y notas traen `allowsDecimals` (`true` si el producto se maneja por peso o volumen, para validar la cantidad con hasta 2 decimales) y el `product` de `/integration/kardex/{productId}` trae `allowsDecimalQuantities`; el kardex (JSON, PDF y Excel) muestra hasta 3 decimales solo en esos productos, y en los demás sigue con 2 (`10.00`).
- **v2.20 (2026-10-11)**: **Primer correlativo de un CAI nuevo** (`POST /integration/cai`). Sin `startingCorrelative`, el CAI nace con `currentCorrelative = initialCorrelative - 1` y su primer documento sale con `initialCorrelative`; antes nacía en `initialCorrelative` y el primer número del rango nunca se usaba. `startingCorrelative` sigue siendo el último número ya usado. Los CAI existentes no cambian.
- **v2.19 (2026-10-08)**: **Extras del restaurante ocultos**. Los productos de servicio que crea el módulo de restaurante para los extras con precio (modificadores) no se listan ni se pueden consultar por id, ni en el storefront (`/products`, `/products/{id}`, `/products/search`, secciones) ni en la integración (`/integration/products`, scope `inventory:read`). Sus ventas siguen en facturas y reportes.
- **v2.18 (2026-10-05)**: **Fecha del pago** (`POST`/`PUT /invoicepayments`). `paymentDate` se interpreta en hora de Honduras: una fecha calendario (`"2026-10-05"`) se toma tal cual y un instante UTC (`"2026-10-06T01:30:00Z"`) se convierte primero a UTC−6. Antes, un instante UTC enviado después de las 18:00 hondureñas quedaba fechado al día siguiente.
- **v2.17 (2026-10-03)**: **Propina y saldos** (integración). Las facturas traen `tipAmount` y `amountToCollect`; el estado de cuenta (`/accountsreceivable/{customerId}`) trae por factura `adjustments`, `tipAmount`, `amountToCollect` y un `paid` que es la suma de los pagos (antes `total − outstanding`, negativo con propina), y `totalOriginal` suma lo cargado. Una nota de crédito **total** sobre una factura con propina también devuelve la propina (perdona la no cobrada, devuelve la cobrada como saldo a favor: `tipForgivenAmount` / `tipRefundedAmount`); una NC parcial ya no se aplica contra la propina. `sales-by-payment-method` trae `tips` y `totalTips` aparte de `revenue`.
- **v2.16 (2026-10-03)**: **Forma de pago validada** (integración, `/integration/invoices`). El `paymentTypeId` de crear y editar una factura tiene que ser una forma de pago del comercio; si no, `400`. Antes se guardaba cualquier id.
- **v2.15 (2026-10-02)**: **Facturas de cuentas de restaurante** (integración, `/integration/invoices`). Nacen emitidas, sin borrador, y su propina no suma a `total` pero sí a `outstanding`. Anularlas (`PATCH /invoices/{id}/status` → Anulada, o `DELETE /invoices/{id}` sobre un borrador anterior) las desvincula y la cuenta vuelve a *Por cobrar* para refacturarla; antes el `DELETE` respondía `400` y la cuenta quedaba facturada para siempre. `PUT /invoices/{id}` sobre una factura de cuenta responde `400`, y emitir una ya emitida responde `200` sin cambios.
- **v2.14 (2026-10-02)**: **El catálogo muestra el disponible.** `/products`, `/products/search` y las secciones (`/sections`, `/sections/{id}/products`) listan solo los productos **con disponible** (existencia menos lo apartado por pedidos vigentes; un servicio siempre, un combo si cada componente alcanza para una unidad), salvo que el comercio muestre los agotados: `GET /store/info` trae el nuevo `showOutOfStockProducts` (y deja de documentarse `tenantId`, que no se envía desde 2026-08-11). Cada producto (listado, búsqueda, detalle y secciones) trae `isAvailable`, la misma cuenta con la que valida el carrito; `GET /products/{id}` (que nunca filtró por stock) trae `isAvailable: false` para un producto sin disponible. `virtualStock` de los combos resta lo apartado y es `null` en un combo solo de servicios. `GET /inventory/products/{id}` pasa a dar el **disponible**: solo almacenes activos de sucursales activas, menos lo apartado, recortado en cero por almacén; combos y servicios devuelven `branches: []`, y como los pedidos en línea salen solo del almacén por defecto, una sucursal puede tener disponible aquí y no alcanzar en el checkout. `/sections` limita `previewSize` a 48. Se documentan también campos y filtros de `/products` que ya existían (`regularPrice`, `isOnOffer`, `offerEndDate`, `brandId`, `isCombo`, `virtualStock`, `comboComponents`; `brandId`, `minPrice`, `maxPrice`, `sortBy`, `onOffer`). Integración: los productos traen `reservedStock` y `availableStock` (`stock` sigue siendo la existencia física); `/integration/warehouses/{id}/products` los trae por producto y `/integration/warehouses/product-availability/{productId}` por bodega, más `totalReserved`/`totalAvailable`; `combo-availability` resta lo apartado de cada componente y responde `400` si el `warehouseId` enviado no existe o no es del tenant. Pedidos: el comercio puede liberar a mano la reserva de un pedido sin cambiarlo, así que `reservationState: 3` ya no significa solo "cancelado" (mirá `status`). `minPrice`, `maxPrice` y `sortBy` usan el precio del catálogo, no la lista del cliente.
- **v2.13 (2026-10-01)**: **Reserva de stock de los pedidos del ecommerce.** Las sucursales (`/branches` y `/store/info`) traen `acceptsOnlineOrders`: el checkout solo funciona con las que tienen almacén por defecto. El checkout (`POST /ecommerce-orders`) aparta los productos en el almacén por defecto de la sucursal (todo o nada) y responde `400` sin cantidades + *"Disponible en: {sucursales}"* si no alcanza; la reserva vence a las horas configuradas por el comercio (48 por defecto) y vencer solo libera (el pedido sigue abierto). Pedidos con `reservationState`, `reservationExpiresAt` y `paymentConfirmedAt` (storefront e integración). El carrito valida el disponible al agregar o subir cantidades y cada línea trae `isAvailable`. Integración: nuevo `PATCH /integration/orders/{id}/confirm-payment`; cancelar un pedido con factura vigente y marcar Shipped sin factura (si tiene productos) responden `400`. El `400` transitorio de inventario ocupado también puede aparecer en el checkout y en los cambios de pedido.
- **v2.12 (2026-09-30)**: **Disponible y candado de inventario** (integración, `/integration/invoices`). Crear una factura valida contra el **disponible** (existencia menos lo apartado por otros documentos) y las operaciones que mueven el stock de un mismo producto (crear, anular, eliminar borrador) se serializan. Nuevo `400` **transitorio** *"El inventario de uno de los productos se está actualizando en otra operación. Intente de nuevo en unos segundos."* — la única excepción a "no reintentar 4xx". Facturar un pedido cancelado o facturado mientras tanto responde `400` *"El pedido cambió de estado mientras se facturaba"*. Base de las reservas de stock de los pedidos del ecommerce, que llegan después.
- **v2.11 (2026-09-30)**: **Borradores y anulación de facturas** (integración, `/integration/invoices` y `/integration/invoicepayments`). `DELETE /invoices/{id}` sobre un borrador ahora lo **anula** en lugar de borrarlo (el borrador ya consumió un correlativo del CAI): queda `Anulada` con su número, devuelve el stock con reverso en Kardex, revierte el asiento y se desvincula del pedido o la cotización de origen; antes respondía error. Las facturas de una cuenta de restaurante no se eliminan (`400`). Anular devuelve también el **saldo a favor** usado en los pagos (y un borrador anulado por `PATCH` también se desvincula) y responde `400` si hay notas de crédito o débito emitidas sobre la factura. Los pagos de una factura anulada no se editan (`400`), y los que la anulación ya devolvió (saldo a favor, o efectivo con caja abierta) no se eliminan (`400`). Además, el `PUT /integration/company` deja de resetear `thirdPartySalesEnabled`.
- **v2.9 (2026-09-14)**: **Documentados los pedidos del ecommerce** (`/ecommerce-orders`: crear desde el carrito, historial paginado, detalle, cancelar y subir comprobante multipart) y **`/ecommerce-payment-types`** con el enum `PaymentTypeEcommerceBehavior` (`None`/`RequiresProof`/`RequiresLink`), que le dice al storefront qué hacer después del checkout. Ya existían en la API; faltaban en la documentación. Sin cambios de contrato. Se agregó también el XML de Swagger que faltaba en `ecommerce-auth`, `ecommerce-cart`, `ecommerce-profile`, `ecommerce-profile/addresses` y `geography`.
- **v2.8 (2026-09-13)**: **Ubicación GPS de las sucursales.** `BranchOffice` gana `latitude`/`longitude` (`decimal(9,6)`, nullable). Storefront: `GET /branches` y el `branches[]` de `GET /store/info` las devuelven — sirven para armar el enlace "Cómo llegar" de cada sucursal (`https://www.google.com/maps/dir/?api=1&destination={lat},{lng}`). Integración (`/integration/branchoffices`): `POST` y `PUT` las aceptan y el DTO las expone. **Van siempre juntas**: enviar solo una responde `400`, igual que las coordenadas `(0, 0)`; rangos `-90..90` y `-180..180`. ⚠️ **El `PUT` trata la ubicación distinto al resto de los campos**: omitir `latitude`/`longitude` **PRESERVA** la ubicación guardada (el resto del PUT es reemplazo total) y solo `"clearCoordinates": true` la borra — así una integración escrita antes de que existieran estos campos no borra la ubicación en cada sincronización. Enviar `clearCoordinates: true` junto con coordenadas responde `400`. Al leerlas en JavaScript, compará con `!= null` y no por truthiness: `0` es una coordenada válida.
- **v2.7 (2026-08-14)**: **Precio de venta desde la entrada de inventario** (`/integration/inventoryentries`). Cada item del `POST`/`PUT` admite ahora `newSalePrice` (lista por defecto, en la convención del tenant), `newSaleMarginPercent` (solo en `pricingMode = MarginPercent`) y `listPrices[]` (`{priceListId, price?, marginPercent?}`) para las demás listas. Se guardan como **intención en el borrador** y se aplican **al confirmar**, en la misma transacción que stock/costo/Kardex y contra el costo ya recalculado. La respuesta suma `appliedPriceChanges[]` y `notRevertedPrices[]`, y los items exponen `previousSalePrice`, `appliedSalePrice`, `salePriceAppliedAt`, `costPrice`, `currentSalePrice`, `taxPercentage` y `listPrices[]`. `costPrice` y todos los `*marginPercent` requieren `inventory:cost:read`. **Corrección de cálculo (afecta también a `POST /pricelist/{id}/products` interno):** en `pricingMode = MarginPercent` con `priceIncludesTax = true` el precio derivado del margen ahora multiplica por `(1 + isv/100)` — antes el ISV se comía el margen (30% configurado con ISV 15% daba 13.04% real). Los precios ya guardados **no se recalculan**; el `ProductPrice` de listas expone `taxPercentage` y `realMarginPercent` para hacer visible la diferencia. Nuevo `409` por confirmación concurrente sobre la misma entrada.
- **v2.6 (2026-08-13)**: **Soft delete de productos** (integración, `/integration/products`). El `DELETE /{id}` pasó de hard-delete a **eliminación lógica** (tombstone restaurable) con `inventory:write`: el producto desaparece de listas, dropdowns y del storefront pero las facturas, cotizaciones, órdenes/facturas de compra, notas y movimientos de inventario históricos conservan la referencia. Nuevo param `includeDeleted` en el GET (los eliminados llegan con `isDeleted`/`deletedAt`, ahora expuestos por `PublicIntegrationProductDto`) y nuevo `PATCH /{id}/restore` (`inventory:write`) que restaura el producto "como estaba" (no cambia `isActive`) → `Result<PublicIntegrationProductDto>`.
- **v2.5 (2026-08-13)**: **Soft delete de los catálogos de configuración** (integración, Tanda 4). El `DELETE` de **descuentos** (`/integration/discounts`), **tipos de pago** (`/integration/paymenttypes`), **unidades** (`/integration/units`) y **prefijos de documento** (`/integration/documentprefixes`) pasó de hard-delete a **eliminación lógica** (tombstone restaurable) con `settings:write`: el registro desaparece de listas/dropdowns pero los documentos históricos conservan la referencia. En los cuatro: nuevo param `includeDeleted` en el GET (los eliminados llegan con `isDeleted`/`deletedAt`, ahora expuestos por los DTOs `Public*`) y nuevo `PATCH /{id}/restore` (`settings:write`), que responde `400` si hay conflicto de unicidad activo (nombre en descuentos/tipos de pago, código en unidades, tipo de documento en prefijos). En **prefijos de documento**, recrear (`POST`) un prefijo de un tipo con tombstone se **bloquea** (`400`) — hay que restaurarlo para no reiniciar el correlativo. **Impuestos** (`/integration/taxes`) siguen siendo solo lectura pero el `Tax` ahora expone `isDeleted`/`deletedAt` y el GET acepta `includeDeleted` (no expone DELETE ni restore: el delete de impuestos es SuperAdmin en la API interna).
- **v2.4 (2026-08-12)**: **Soft delete de proveedores y clientes** (integración). Proveedores (`/integration/suppliers`): nuevo param `includeDeleted` en el GET, `DELETE /{id}` pasa a eliminación lógica (tombstone; órdenes de compra, facturas de compra y entradas de inventario conservan la referencia) y nuevo `PATCH /{id}/restore` (`inventory:write`; 400 si ya existe un proveedor activo con el mismo nombre). Clientes (`/integration/customers`): nuevo param `includeDeleted`, el `DELETE /{id}` pasa de hard-delete a **soft delete** y ahora audita — para clientes de ecommerce **bloquea el login del storefront** (signin/signup/reset lo tratan como inexistente; el email queda reutilizable), y nuevo `PATCH /{id}/restore` (`crm:write`; 400 si ya existe un cliente activo con el mismo email o RTN). Los DTOs `Supplier` y `Customer` ahora exponen `isDeleted`/`deletedAt`.
- **v2.3 (2026-08-10)**: **Soft delete de CAIs** (`/integration/cai`): el `DELETE` pasa a eliminación lógica (facturas emitidas conservan la referencia fiscal, defaults de sucursal desasociados, código reutilizable), nuevo param `includeDeleted` en el GET y `PATCH /{id}/restore` (restaura desactivado; 400 si hay un CAI activo con el mismo código). Usuarios y almacenes también son soft delete a nivel interno; sus endpoints de integración (read-only) excluyen tombstones por defecto sin cambios de contrato.
- **v2.2 (2026-08-09)**: **Soft delete de catálogos** (marcas, familias de producto y sucursales): el `DELETE` pasa de hard-delete a **eliminación lógica** (tombstone) — el registro desaparece de listas/dropdowns pero productos y documentos históricos conservan la referencia. Nuevo param `includeDeleted` en los GET de lista (los eliminados llegan con `isDeleted`/`deletedAt`) y nuevos endpoints `PATCH /{id}/restore` (`catalog:write` para marcas/familias, `settings:write` para sucursales; 400 si ya existe un registro activo con el mismo nombre — el nombre de un eliminado puede reutilizarse al crear).
- **v2.1 (2026-08-09)**: **Sucursales en la API de integración** (`/integration/branchoffices`): GET(+`/{id}`), POST, PUT/{id}, DELETE/{id}, PATCH/{id}/toggle-status bajo `settings:read`/`settings:write`. Resuelven el `branchOfficeId` que ya referenciaban facturas, pedidos, bodegas y reportes (DTO sin `tenantId`).
- **v2.0 (2026-08-08)**: **API de Integración ERP/CRM completa.** Toda la superficie JSON del backend expuesta bajo `/api/public/v1/integration/…` (feature `api_access`, scope `modulo:verbo` por endpoint, API Key ligada a usuario): catálogos + inventario/Kardex, CRM, ventas/facturación (incl. manual), ecommerce, compras, contabilidad y configuración/perfil. Cierre con el tramo **multipart**: subida de medios (imágenes de producto, logo de marca, banner de sección, carruseles + slides, logo de documentos, avatar, adjuntos de pago venta/compra/abono) e **importación masiva** por Excel (productos, proveedores, clientes, catálogo de cuentas) con plantillas descargables. Imágenes optimizadas a WebP. Los DTOs de pago/abono exponen `attachmentUrl`.
- **v1.3 (2026-05-12)**: Carrito persistente cross-device para clientes del ecommerce (`GET /ecommerce-cart/me`, `POST /ecommerce-cart/me/items`, `PUT/DELETE /ecommerce-cart/me/items/{productId}`, `DELETE /ecommerce-cart/me`). Solo clientes autenticados (sin carritos anónimos). Precios recalculados al instante en cada `GET` contra la lista actual del cliente — no hay snapshot. Stock NO validado en el carrito (recién en checkout cuando llegue la feature de pedidos). Un carrito por cliente (UNIQUE), TTL 30 días vía background job, cantidad máxima 9999 por item. `POST` sobre item existente SUMA la cantidad; `PUT` con `quantity: 0` ELIMINA el item.
- **v1.2 (2026-05-11)**: Direcciones de envío para clientes del ecommerce (`GET/POST /ecommerce-profile/addresses`, `GET/PUT/DELETE /.../{id}`, `POST /.../{id}/set-default`). CRUD completo + set-default explícito. Validación de coherencia department/city. Auto-promoción de default al eliminar la actual.
- **v1.1 (2026-05-11)**: Auth de clientes del ecommerce (`/ecommerce-auth/*` — signup, verify-email, resend-verification, signin, request-password-reset, reset-password). Perfil del cliente logueado (`GET/PUT /ecommerce-profile/me`). Geografía pública (`/geography/departments`, `.../cities`). Bearer JWT opcional en `/products` y `/products/{id}` para resolución de precios por lista del cliente. Correos de verificación/recuperación con logo y nombre del tenant.
- **v1 (2026-04-26)**: Release inicial. 7 endpoints read-only, autenticación por API Key, rate limiting 600/100, feature gating a plan Enterprise.

---

**Última actualización de este archivo:** 2026-10-03  ·  **Versión del archivo:** 2.16
