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?criterio=zapatilla&limite=20   # 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)
`valorFinal1` a `valorFinal5`	Precio al público de cada lista de precios, con IVA incluido. Es el que cobra la caja.
`valorVentaBol1` a `valorVentaBol5`	Precio neto (sin IVA) de cada lista para boleta
`valorVentaFac1` a `valorVentaFac5`	Precio neto (sin IVA) de cada lista para factura
`inventariable`	Si mueve stock al vender
`web` / `movil`	Visibilidad en canales
`activo` / `vendible`	Estado del producto

Qué precio usar

Para publicar precios usa valorFinal1 a valorFinal5: traen el precio con IVA incluido, el mismo que cobra la caja, y es también el precio de las líneas de una boleta. Para las líneas de una factura o guía, que van en neto, usa valorVentaFac1 a valorVentaFac5. valorVentaBol es el neto que corresponde al precio de boleta, útil para cálculos y reportes. El número al final es la lista de precios (1 a 5).

La respuesta también trae valorVenta1 a valorVenta5. Son campos antiguos que se mantienen por compatibilidad: no los uses en integraciones nuevas.

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 disponible para publicar (atpPublicable):

GET /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 Reservar stock al tomar un pedido.

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.