Catálogo de productos y stock¶

Cómo sincronizar el catálogo de OpenTPV con un sistema externo: buscar y leer productos, crearlos o actualizarlos, y publicar la disponibilidad correcta en una tienda web.

Prerrequisitos: Primeros pasos.

Buscar productos¶

Búsqueda avanzada con paginación (la principal para sincronizar)¶

curl -X POST https://api.opentpv.cl/Productos/buscar-avanzado \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -d '{
    "textoBusqueda": "",
    "activo": true,
    "vendible": true,
    "web": true,
    "pagina": 1,
    "tamañoPagina": 100,
    "ordenarPor": "descripcion",
    "ordenAscendente": true
  }'

Filtros útiles para una tienda: web (marcados para publicar en web), conStock (solo con existencias), idCategoria/idSubCategoria, idMarca, inventariable, exento, kit. Para recorrer el catálogo completo, itera pagina hasta que venga vacío.

Búsquedas puntuales¶

GET /Productos/{codigo}                          # por código interno
GET /Productos/codigo-barras/{codigoBarra}       # por EAN/UPC
GET /Productos/codigo-alternativo/{codigoAlternativo}
GET /Productos/buscar?texto=zapatilla            # autocomplete por descripción
GET /Productos/existe/{codigo}                   # solo verificar existencia

Crear y actualizar productos¶

POST /Productos          # crear
PUT  /Productos/{codigo} # actualizar

El cuerpo es el objeto producto completo (el mismo que devuelve el GET). Para actualizar sin perder datos, el patrón seguro es leer, modificar y reenviar: haz GET /Productos/{codigo}, cambia los campos que necesitas y envía el objeto de vuelta con PUT. Los campos principales:

Campo	Descripción
`codigo`	Código interno, la llave del producto
`descripcion` / `descripcionLarga`	Nombre corto y descripción extendida
`codigosBarra`	Códigos de barra asociados
`idCategoria` / `idSubCategoria`	Clasificación (ver más abajo)
`valorVenta`	Precio de venta (según la empresa, con o sin IVA)
`inventariable`	Si mueve stock al vender
`web` / `movil`	Visibilidad en canales
`activo` / `vendible`	Estado del producto

El precio puede venir con o sin IVA

Cada empresa define en el ERP si sus valores de venta incluyen IVA (Opciones, sección Impuestos). Antes de publicar precios, confirma la modalidad de la empresa; no lo asumas.

Otros endpoints de mantención: POST /Productos/guardar-completo (cabecera, imágenes y extras en una llamada), PUT /Productos/modificar-codigo (renombrar el código primario) y DELETE /Productos/{codigo}.

Categorías¶

GET  /Categorias                                # listar
GET  /Categorias/{idCategoria}/subcategorias    # subcategorías de una categoría
POST /Categorias                                # crear

Para poblar los filtros de la tienda, basta listar categorías y subcategorías y mapearlas a los idCategoria/idSubCategoria de los productos.

Stock: qué número publicar¶

Un producto tiene existencia física por bodega, pero la tienda no debe publicar el stock físico: parte puede estar reservada por otros carros o retenida como colchón. El número correcto es el ATP publicable:

GET /api/Reservas/disponibilidad?codigos=A001,B002&bodega=1

[
  { "codigo": "A001", "stockFisico": 10, "reservado": 2,
    "buffer": 1, "atpFisico": 8, "atpPublicable": 7 }
]

Publica atpPublicable. El detalle completo del sistema de reservas está en Reserva de stock para e-commerce.

Las bodegas disponibles se consultan con GET /Bodegas (número y nombre de cada una; 1 a 20).

Estrategia de sincronización recomendada¶

Carga inicial: recorrer buscar-avanzado paginado con web: true y guardar codigo como identificador estable.
Refresco periódico: repetir la búsqueda cada cierto tiempo para captar precios, textos y altas/bajas (el catálogo cambia poco; cada 15 a 60 minutos suele bastar).
Disponibilidad: consultarla aparte con /Reservas/disponibilidad al pintar catálogo y carro, que es barata y refleja reservas al instante.