API de Gestión de Listas de Precios

Descripción General

La API de Gestión de Listas de Precios proporciona un conjunto completo de endpoints para administrar listas de precios en la plataforma Nilo. Esta API permite crear, actualizar y gestionar listas de precios para productos en diferentes tiendas, permitiendo estrategias de precios flexibles y una gestión eficiente de precios.

Entendiendo las Listas de Precios

Estructura de Lista de Precios

• Código Interno: Identificador único para la lista de precios
• Nombre: Nombre descriptivo para la lista de precios
• Estado: Estado habilitado/deshabilitado de la lista de precios
• Productos: Lista de productos con sus precios específicos y unidades
• Tiendas: Lista de tiendas asociadas a la lista de precios

Consideraciones Importantes

• Cada lista de precios puede tener múltiples productos con diferentes precios
• Los productos pueden tener diferentes precios según las unidades (tamaños de paquete)
• Las listas de precios se pueden asignar a múltiples tiendas
• Las listas de precios se pueden habilitar o deshabilitar según sea necesario
• Operaciones por lotes disponibles para una gestión eficiente de precios

Operaciones Individuales de Lista de Precios

Crear una Lista de Precios

POST/pricelist

Crear una nueva lista de precios con información básica.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
internalCode	string	Sí	Identificador único para la lista de precios
name	string	No	Nombre descriptivo para la lista de precios

Ejemplo del Cuerpo de la Solicitud

{
  "internalCode": "7634",
  "name": "lista de precios alimentos"
}

Códigos de Respuesta

Código	Descripción
200	Lista de precios creada exitosamente
404	La lista de precios ya existe

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  internalCode: "7634",
  name: "lista de precios alimentos",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "internalCode": "7634",
    "name": "lista de precios alimentos"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Obtener Detalles de Lista de Precios

GET/pricelist/{code}

Obtener información detallada sobre una lista de precios específica.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la lista de precios

Ejemplo de Respuesta

{
  "internalCode": "7634",
  "name": "lista de precios encontrada",
  "enabled": true,
  "products": [
    {
      "priceListInternalCode": "124f",
      "productInternalCode": "22222.1",
      "units": 3,
      "price": 700.2
    }
  ],
  "stores": [
    {
      "priceListInternalCode": "124f",
      "storeInternalCode": "2345"
    }
  ]
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

Cambiar Estado de Lista de Precios

PUT/pricelist/{code}/status

Habilitar o deshabilitar una lista de precios.

Parámetros de Ruta

Parámetro	Tipo	Requerido	Descripción
code	string	Sí	Código interno de la lista de precios

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
enabled	boolean	Sí	Si la lista de precios debe estar habilitada

Ejemplo del Cuerpo de la Solicitud

{
  "enabled": true
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  enabled: true,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634/status",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634/status"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "enabled": True
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Operaciones por Lotes

Actualización por Lotes de Lista de Precios

POST/batch/pricelist

Actualizar múltiples listas de precios, productos y asociaciones de tiendas en una sola operación.

Parámetros del Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
upsert	objeto	No	Contiene productos y tiendas para agregar/actualizar
remove	objeto	No	Contiene productos y tiendas para eliminar

Ejemplo del Cuerpo de la Solicitud

{
  "upsert": {
    "products": [
      {
        "priceListInternalCode": "124f",
        "productInternalCode": "22222.1",
        "units": 3,
        "price": 700.2
      }
    ],
    "stores": [
      {
        "priceListInternalCode": "124f",
        "storeInternalCode": "2345"
      }
    ]
  },
  "remove": {
    "products": [],
    "stores": []
  }
}

Ejemplo de Uso

Javascript

const headers = {
  Authorization: "TU_TOKEN_DE_AUTORIZACION",
  "x-api-key": "TU_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  upsert: {
    products: [
      {
        priceListInternalCode: "124f",
        productInternalCode: "22222.1",
        units: 3,
        price: 700.2,
      },
    ],
    stores: [
      {
        priceListInternalCode: "124f",
        storeInternalCode: "2345",
      },
    ],
  },
  remove: {
    products: [],
    stores: [],
  },
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/pricelist",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/pricelist"

headers = {
    'Authorization': 'TU_TOKEN_DE_AUTORIZACION',
    'x-api-key': 'TU_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "upsert": {
        "products": [
            {
                "priceListInternalCode": "124f",
                "productInternalCode": "22222.1",
                "units": 3,
                "price": 700.2
            }
        ],
        "stores": [
            {
                "priceListInternalCode": "124f",
                "storeInternalCode": "2345"
            }
        ]
    },
    "remove": {
        "products": [],
        "stores": []
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Mejores Prácticas

1. Organización de Listas de Precios

   • Crear nombres significativos para las listas de precios
   • Agrupar productos relacionados en la misma lista de precios
   • Mantener estrategias de precios consistentes en todas las tiendas

2. Gestión de Precios

   • Revisar y actualizar precios regularmente
   • Usar operaciones por lotes para actualizaciones masivas
   • Mantener un registro de versiones y cambios de listas de precios

3. Asociación de Tiendas

   • Asignar listas de precios a grupos de tiendas apropiados
   • Verificar relaciones tienda-lista de precios
   • Monitorear efectividad de listas de precios por tienda

4. Optimización de Rendimiento

   • Usar operaciones por lotes para múltiples actualizaciones
   • Implementar manejo de errores adecuado
   • Monitorear tiempos de respuesta de la API

Casos de Uso Comunes

1. Configuración Inicial de Lista de Precios

   • Crear listas de precios base
   • Asignar tiendas a listas de precios
   • Configurar precios de productos

2. Actualizaciones de Precios

   • Actualizar precios de productos específicos
   • Modificar precios basados en unidades
   • Actualizaciones de precios por lotes

3. Gestión de Tiendas

   • Agregar tiendas a listas de precios
   • Eliminar tiendas de listas de precios
   • Gestionar grupos de tiendas

4. Escenarios de Integración

   • Sincronizar con sistemas externos
   • Importar datos de precios
   • Exportar información de precios

Guías de Implementación

Crear una Nueva Lista de Precios

1. Generar un código interno único
2. Proporcionar un nombre descriptivo
3. Definir precios iniciales de productos
4. Asociar tiendas relevantes
5. Habilitar la lista de precios

Gestionar Productos en Listas de Precios

1. Identificar productos objetivo
2. Establecer precios por unidad apropiados
3. Actualizar precios por lotes cuando sea necesario
4. Verificar actualizaciones de precios

Operaciones de Tienda

1. Identificar tiendas objetivo
2. Asociar tiendas con listas de precios
3. Verificar relaciones tienda-lista de precios
4. Monitorear efectividad de precios

Procesamiento por Lotes

1. Preparar datos en formato correcto
2. Usar endpoints de lotes apropiados
3. Manejar respuestas y errores
4. Verificar actualizaciones exitosas

Seguridad

Autenticación

• API Key requerida para todos los endpoints
• Token de autorización necesario para operaciones
• Permisos adecuados requeridos para diferentes operaciones

Permisos Requeridos

• supplier/pricelist.read: Para leer datos de listas de precios
• supplier/pricelist.write: Para crear y actualizar listas de precios
• supplier/pricelist.bulkwrite: Para operaciones por lotes

Manejo de Errores

Validación de Entrada

• Verificar campos requeridos
• Validar formatos de precios
• Comprobar códigos internos
• Asegurar relaciones adecuadas

Respuestas de Error

• 200: Operación exitosa
• 202: Proceso por lotes aceptado
• 404: Lista de precios no encontrada
• 402: Solicitud incorrecta en operaciones por lotes

Procedimientos de Recuperación

1. Registrar detalles de error
2. Implementar mecanismos de reintento
3. Manejar actualizaciones parciales
4. Mantener consistencia de datos

Monitoreo

• Rastrear tiempos de respuesta de API
• Monitorear estado de procesos por lotes
• Registrar frecuencias de error
• Alertar sobre fallos críticos