API Patagonia Gestion

Guia para terceros - Articulos, Stock y Ofertas

Esta guia describe como consumir los endpoints publicos relacionados con
catalogo de articulos, stock por sucursal y ofertas.
Todos los script son llamados desde el sitio de convergencia que usa actualmente el cliente.

1. Autenticacion

Todas las APIs de este modulo requieren un token habilitado con permiso
ARTICULOS.

Authorization: Bearer <TOKEN>

El token debe mantenerse confidencial. Si una llamada devuelve un error de
token, vencimiento o permiso, debe solicitarse a Sistemas Ceibo la revision
de la habilitacion.

2. Que API usar

Necesidad	Endpoint
Descargar o sincronizar el catalogo	API_ARTICULOS.ASP
Saber que articulos tienen oferta	API_ARTICULOS_CON_OFERTA.ASP
Conocer las ofertas de un articulo	API_OFERTAS.ASP?codigo=...
Calcular la oferta efectiva para una cantidad	API_OFERTAS.ASP?codigo=...&cantidad=...
Consultar stock del articulo por sucursal	API_STOCK_SUCURSALES.ASP?codigo=...

3. Catalogo de articulos

3.1 Descarga completa

API_ARTICULOS.ASP?modo=FULL&desde_id=0&cantidad=500

La descarga es paginada. El tercero debe conservar el valor
ultimo_id y continuar mientras hay_mas sea
true.

La cantidad maxima por llamada es de 500 registros.

3.2 Cambios posteriores

API_ARTICULOS.ASP?modo=CAMBIOS&fecha_desde=2026-09-01&ultimo_id=1000&desde_id=0&cantidad=500

fecha_desde representa la ultima fecha sincronizada.
ultimo_id representa el mayor ID conocido al comenzar esa
sincronizacion. desde_id se utiliza como cursor para paginar
la corrida actual.

Las fechas se evaluan de forma inclusiva, por lo que un articulo puede
repetirse. La integracion debe aceptar esas repeticiones y actualizar el
articulo existente en lugar de duplicarlo.

La sincronizacion detecta articulos nuevos mediante su ID y cambios
mediante las fechas informadas por Patagonia. Un salto de IDs no debe
interpretarse como una eliminacion.

En IMAGEN viaja solo el nombre y extensión del archivo Imagen de cada articulo, por lo tanto para su localización enrutarlo a la carpeta IMAGENES_DE_ARTICULOS/(nombre y extensión del archivo imagen). Ejemplo : http://DominioDelCLiente.com/CarpetaCliente/IMAGENES_DE_ARTICULOS/WK5416.JPG

4. Articulos con oferta

API_ARTICULOS_CON_OFERTA.ASP?desde_id=0&cantidad=500

Este endpoint devuelve solamente los CODIGO de los
articulos que poseen una oferta vigente o potencialmente aplicable segun
la configuracion actual.

Esta pensado como un indice liviano para construir una seccion de
promociones sin consultar todos los articulos uno por uno.

Ejemplo de respuesta:

{  "ok": true,
  "cliente": 15000,
  "key": "196_UVHR",
  "cantidad_devuelta": 3,
  "ultimo_id": 1000,
  "hay_mas": false,
  "codigos": [
    "CLI-28",
    "ABONO",
    "CASA-V-14"
  ]}

Para conocer el detalle de la promocion de cada codigo, debe consultarse
API_OFERTAS.ASP.

5. Consulta de ofertas

5.1 Ver las ofertas de un articulo

API_OFERTAS.ASP?codigo=ABONO

Sin enviar cantidad, la API devuelve las ofertas o configuraciones
disponibles para ese articulo.

Los tipos que pueden aparecer son:

• GRADUAL


• ARTICULO_DESCUENTO


• ARTICULO_REGALO


• RUBRO_DESCUENTO

Ejemplo de oferta gradual:

{  "tipo": "GRADUAL",
  "cantidad_desde": 2,
  "porcentaje": 6.64
}

Ejemplo de descuento de articulo:

{  "tipo": "ARTICULO_DESCUENTO",
  "cantidad_desde": 1,
  "porcentaje": 50
}

Ejemplo de articulo de regalo:

{  "tipo": "ARTICULO_REGALO",
  "cantidad_desde": 20,
  "codigo_regalo": "PH-212-1",
  "cantidad_regalo": 3
}

5.2 Obtener la oferta efectiva para una cantidad

API_OFERTAS.ASP?codigo=CASA-V-14&cantidad=20

Al enviar cantidad, la API devuelve una sola oferta: la que
Patagonia aplicaria para esa cantidad.

El tercero no debe reconstruir prioridades, combinar promociones ni
recalcular reglas comerciales por su cuenta. API_OFERTAS.ASP
debe considerarse la fuente de verdad de la oferta.

5.3 Vigencia del grupo

La respuesta puede incluir los siguientes campos:

• grupo


• grupo_habilitado


• detalle_grupo


• grupo_desde


• grupo_hasta

grupo_desde y grupo_hasta informan el rango
temporal del grupo.

El valor definitivo para saber si el grupo permite aplicar ofertas en ese
momento es grupo_habilitado, porque tambien pueden intervenir
otras condiciones como la activacion del grupo y el dia de la semana.

Si no existe una oferta aplicable para la cantidad consultada, la respuesta
puede contener:

"oferta": null

Esto es una respuesta valida y no debe interpretarse como un error.

6. Stock por sucursales

API_STOCK_SUCURSALES.ASP?codigo=780052

Devuelve la existencia del mismo CODIGO en la sucursal
actual y en las sucursales vinculadas.

Esta diseñado para consultas puntuales, por ejemplo al mostrar una ficha de
producto, disponibilidad o carrito. No debe utilizarse como mecanismo de
descarga masiva de stock.

Ejemplo de respuesta:

{  "ok": true,
  "codigo": "780052",
  "stock_sucursales": [
    {      "carpeta": "Carpeta_1",
      "local": "Sucursal Neuquen",
      "cantidad": 4
    },
    {      "carpeta": "Carpeta_2",
      "local": "Sucursal Roca",
      "cantidad": 0
    },
    {      "carpeta": "Carpeta_3",
      "local": "Sucursal Bariloche",
      "cantidad": 1
    }  ]}

7. Flujo recomendado para un e-commerce o aplicacion

1. 
   Sincronizar el catalogo mediante API_ARTICULOS.ASP.


2. 
   Obtener los codigos promocionados mediante
   API_ARTICULOS_CON_OFERTA.ASP.


3. 
   Consultar API_OFERTAS.ASP al mostrar un producto en oferta o
   cuando cambie la cantidad seleccionada.
   


4. 
   Consultar API_STOCK_SUCURSALES.ASP solamente cuando se
   necesite mostrar disponibilidad por sucursal.
   

8. Buenas practicas

• Respetar siempre la paginacion y el campo hay_mas.


• 
  Diseñar la sincronizacion de manera idempotente: recibir nuevamente un
  articulo no debe generar un duplicado.
  


• Tratar los CODIGO como texto.


• 
  No derivar reglas comerciales a partir del listado de articulos con
  oferta.
  


• 
  Utilizar API_OFERTAS.ASP como fuente de verdad de la
  promocion.
  


• 
  Utilizar el stock por sucursal unicamente para consultas puntuales.
  


• 
  Mantener el token fuera del codigo publico del navegador siempre que la
  arquitectura de la integracion lo permita.
  

9. Consideraciones sobre las respuestas JSON

Todas las respuestas se entregan en formato JSON. El integrador debe
verificar siempre el campo ok antes de procesar el resto de la
respuesta.

Los valores booleanos se expresan como true y
false.

Algunos importes grandes pueden aparecer en notacion cientifica. Esto sigue
siendo una representacion numerica JSON valida.

10. Resumen rapido

API_ARTICULOS.ASP sincroniza el catalogo.

API_ARTICULOS_CON_OFERTA.ASP indica que codigos poseen
promociones.

API_OFERTAS.ASP explica y calcula la promocion de un
codigo.

API_STOCK_SUCURSALES.ASP informa disponibilidad puntual
por sucursal.

Para altas o cambios de token, permisos, vencimientos o problemas de
habilitacion, el tercero debe contactar a Sistemas Ceibo.