Gestionar Productos en tienda

Referencia de API

La API del Marketplace te permite administrar los productos de la tienda.

Puedes crear y actualizar los productos en la plataforma, recuperar los productos y revisar el estado de stock o disponibilidad de los mismos.

Las principales propiedades de los productos y los elementos creados a través de la API consisten en los siguientes elementos:

  • id_category_default : Es un valor que debe ir por defecto en 2.
  • reference : Es un valor que identifica el producto. (Generalmente el SKU)
  • price : Es el precio del producto. Decimal con dos números decimales.
  • name : Es el nombre del producto. Tiene un formato especial distinto al string, para su internalizacion, aunque no se use.
  • description : Es una descripción del producto. Al igual que name tiene un formato distinto.
  • active : Es un valor que indica si el producto es visible o no. En el portal, el valor por defecto es 1.

Solicitudes Permitidas.

  • GET (v1/products) Obtener todos los productos.
  • POST (v1/products): Crear un nuevo producto.
  • PUT (v1/products/{product_id}): Actualizar un proyecto.

Gestión de Opciones de Producto product_options y product_option_values

Introducción

Las opciones de producto se utilizan para gestionar variaciones como color, talla, material, etc., de los productos. Estas opciones se componen de:

  • product_options: Representan las características del producto, como "Color" o "Talla".
  • product_option_values: Son los valores específicos de esas características, como "Rojo" o "Grande".

1. product_options

Las product_options son los grupos de características que pueden variar entre las diferentes combinaciones de un producto.

Crear una Opción de Producto

Para crear un grupo de atributos (por ejemplo, "Color"):

  • Método: POST /api/product_options
  • Payload:
   {
    "product_options": {
        "is_color_group": "0", //opcional
        "group_type": "select", //puede ser select, radio o text
        "position": "0", //opcional
        "name": {
            "language": [
                {
                    "@id": "1",
                    "%": "Color"
                }
            ]
        },
        "public_name": {
            "language": [
                {
                    "@id": "1",
                    "%": "Color"
                }
            ]
        }
    }
}
  • Respuesta: Un objeto JSON con el ID del grupo de opción de producto creado.

Obtener una Opción de Producto

Para obtener la información de una opción de producto (por ejemplo, "Color"):

  • Método: GET /api/product_options/:id
  • Respuesta: Un objeto JSON con los detalles del grupo de opción de producto.

2. product_option_values

Los product_option_values son los valores específicos para un grupo de opciones de producto. Por ejemplo, si el grupo de opción es "Color", los valores podrían ser "Rojo", "Verde", "Azul", etc.

Crear un Valor de Opción de Producto

Para crear un valor de opción (por ejemplo, "Rojo") dentro de un grupo de opción de producto (como "Color"):

  • Método: POST /api/product_option_values
  • Payload:
     {
      "product_option_values": {
          "id_attribute_group": "6",
          "name": {
              "language": {
                  "@id": "1",
                  "%": "Rojo"
              }
          }
      }
    }
  • Respuesta: Un objeto JSON con el ID del valor de opción de producto creado.

Obtener un Valor de Opción de Producto

Para obtener la información de un valor de opción (por ejemplo, "Rojo"):

  • Método: GET /api/product_option_values/:id
  • Respuesta: Un objeto JSON con los detalles del valor de opción.

3. Relación entre product_options y product_option_values

  • product_options define un conjunto de características, como "Talla" o "Color".
  • product_option_values define los valores específicos para esas características, como "Grande" o "Pequeño" en el caso de "Talla", o "Rojo" y "Azul" en el caso de "Color".

Las combinaciones de producto se crean seleccionando diferentes valores de estas opciones.


Gestión de Combinaciones

Introducción

La API permite gestionar combinaciones de productos a través de su API REST, proporcionando una forma eficiente de crear, modificar, obtener y eliminar combinaciones de productos con atributos como colores, tallas u otras variaciones.

Endpoints Relevantes para Combinaciones

  1. Combinaciones: /api/combinations
  2. Atributos: /api/product_option_values
  3. Stock: /api/stock_availables

Flujo para Gestionar Combinaciones

1. Crear Combinaciones

Una vez que los atributos y valores de atributos ya están creados, puedes proceder a crear combinaciones para un producto.

  • Método: POST /api/combinations
  • Payload:
   {
     "combination": {
       "id_product": 1,  // ID del producto al que pertenece la combinación
       "minimal_quantity": 1,
       "price": 5.00,  // Impacto en el precio de la combinación
       "associations": {
          "product_option_values": {
              "product_option_values": [
                 {
                  "id": 9
                 }
              ]
          }
        }
     }
   }
  • Respuesta: Un objeto JSON con el ID de la combinación creada.

2. Gestionar el Stock de Combinaciones

El stock de cada combinación se gestiona a través del endpoint de stock disponible.

  • Método: GET /api/stock_availables?filter[id_product_attribute]=1

  • Payload:

   {
     "stock_available": {
       "id_product": 1,  // ID del producto
       "id_product_attribute": 1,  // ID de la combinación
       "quantity": 50  // Cantidad de stock
     }
   }
  • Respuesta: Un objeto JSON confirmando la cantidad de stock actualizada para la combinación.

Gestión de Combinaciones Existentes

Obtener Información de una Combinación

Para obtener los detalles de una combinación existente, como atributos, precio o stock, puedes usar una solicitud GET.

  • Método: GET /api/combinations/:id
  • Respuesta: Un objeto JSON con la información de la combinación.
  • NOTA: Para obtener el stock de una combinación, debes utilizar el endpoint GET /api/stock_availables?filter[id_product_attribute]=id, el dato de quantity no es el stock real.

Actualizar una Combinación

Si necesitas modificar detalles de una combinación, como el precio, puedes hacerlo mediante una solicitud PUT.

  • Método: PUT /api/combinations/:id

  • Payload:

   {
     "combination": {
       "price": 7.00  // Nuevo precio
     }
   }
  • Respuesta: Un objeto JSON confirmando la actualización de la combinación.

Gestión de Imágenes de Productos

La API de PrestaShop permite gestionar las imágenes asociadas a los productos. A continuación, se describen los endpoints y métodos disponibles para crear, actualizar y eliminar imágenes en las versiones 1.7 y 1.6.

1. Crear una Imagen de Producto

Para agregar una imagen a un producto:

  • Método: POST /api/images/products/:id_product
  • Headers:
  • Content-Type: multipart/form-data
  • Payload:
  • El archivo de la imagen debe enviarse como parte del cuerpo de la solicitud en formato multipart/form-data. La imagen debe ir acompañada del parametro image que contiene el archivo de imagen.
  • La imagen debe subirse desde la ruta local del servidor. Por el momento, no se admite URLs externas.
  • Los formatos admitidos son JPEG, PNG y GIF.

Ejemplo de Solicitud

curl -X POST "https://example.com/api/images/products/1" \
-H "Authorization: Basic <EncodedToken>" \
-F "image=@/ruta/a/la/imagen.jpg"

Respuesta: Un objeto XML con el ID de producto y el content en base64 de la imagen subida.


2. Actualizar una Imagen de Producto

  • Método: POST /api/images/products/:id_product/:id_image
  • Headers:
  • Content-Type: multipart/form-data
  • Payload:
  • El archivo de la imagen debe enviarse como parte del cuerpo de la solicitud en formato multipart/form-data. La imagen debe ir acompañada del parametro image que contiene el archivo de imagen.
  • La imagen debe subirse desde la ruta local del servidor. Por el momento, no se admite URLs externas.
  • Los formatos admitidos son JPEG, PNG y GIF.
  • Además debe ir el parametro ps_method con el valor PUT para indicar que se está actualizando una imagen existente.

Ejemplo de Solicitud

curl -X POST "https://example.com/api/images/products/1/2" \
-H "Authorization: Basic <EncodedToken>" \
-F "image=@/ruta/a/la/imagen.jpg"
-F "ps_method=PUT"

Respuesta: Un objeto XML con el ID de producto y el content en base64 de la imagen subida.

3. Eliminar una Imagen de Producto

Para eliminar una imagen de un producto:

  • Método: DELETE /api/images/products/:id_product/:id_image

  • Headers:

  • Payload: No se requiere un cuerpo de solicitud.

  • Ejemplo de Solicitud:

curl -X DELETE "https://example.com/api/images/products/1/2" \
  • Respuesta: Cuerpo vacío con un código de estado HTTP 200 OK si la eliminación fue exitosa.

4. Obtener Imágenes de un Producto

Para obtener todos los IDs de imágenes asociadas a un producto:

  • Método: GET /api/images/products/:id_product

  • Headers:

  • Content-Type: application/json

  • Respuesta: Un objeto JSON con una lista de ids de imágenes asociadas al producto.

  • Ejemplo de Solicitud:

    curl -X GET "https://example.com/api/images/products/1"
    -H "Authorization: Basic <EncodedToken>" \
    -H "Content-Type: application/json"
  • Ejemplo de respuesta:
{
  "": [
    {
      "id": "123"
    },
    {
      "id": "124"
    },
    {
      "id": "125"
    },
    {
      "id": "126"
    }
  ]
}

5. Ver una Imagen de Producto Específica

Para ver una imagen específica de un producto:

- Método: GET /api/images/products/:id_product/:id_image

  • Respuesta: La imagen en formato binario (generalmente JPEG o PNG).

Gestión de Stock

La API de PrestaShop permite gestionar el stock de los productos a través del endpoint /api/stock_availables. A continuación, se describen las operaciones más comunes para gestionar el stock de los productos.

1. Obtener Stock de un Producto

Para obtener el stock disponible de un producto específico, puedes utilizar el siguiente endpoint:

  • Método: GET /api/stock_availables?filter[id_product]=1

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>
  • Respuesta: Un objeto JSON con los detalles del stock disponible para el producto especificado.

  • Ejemplo de Solicitud:

curl -X GET "https://example.com/api/stock_availables?filter[id_product]=1" \
  • Ejemplo de Respuesta:
{
  "stock_availables": [
    {
      "id": "1",
      "id_product": "1",
      "id_product_attribute": "0",
      "quantity": "100",
      "depends_on_stock": "0",
      "out_of_stock": "2"
    }
  ]
}

2. Actualizar Stock de un Producto

Para actualizar la cantidad de stock disponible de un producto, puedes utilizar el siguiente endpoint:

  • Método: PUT /api/stock_availables/:id
  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>
  • Payload:

   {
     "stock_available": {
       "id": 321, // ID del stock disponible a actualizar
       "id_product": 1,  // ID del producto
       "id_product_attribute": 0,  // ID de la combinación (0 si no aplica)
       "quantity": 150  // Nueva cantidad de stock
       "depends_on_stock": 0, // 0 si no depende del stock avanzado
       "out_of_stock": 1, // 1 si se permite la compra cuando el stock está agotado, 2 si no se permite
       "id_shop": 1 
     }
   }
  • Ejemplo de Solicitud:
curl -X PUT "https://example.com/api/stock_availables/1" \
--data '{
  "stock_available": {
    "id": 321,
    "id_product": 1,
    "id_product_attribute": 0,
    "quantity": "150",
    "depends_on_stock": 0,
    "out_of_stock": 1,
    "id_shop": 1
  }
}'

Ejemplo de Respuesta:

{
  "stock_available": {
    "id": "1",
    "id_product": "1",
    "id_product_attribute": "0",
    "quantity": "150",
    "depends_on_stock": "0",
    "out_of_stock": "2"
  }
}

3. Crear Stock para un Producto

Para crear un nuevo registro de stock para un producto, puedes utilizar el siguiente endpoint:

  • Método: POST /api/stock_availables

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>
  • Payload:

   {
     "stock_available": {
       "id_product": 1,  // ID del producto
       "id_product_attribute": 0,  // ID de la combinación (0 si no aplica)
       "quantity": 150  // Nueva cantidad de stock
       "depends_on_stock": 0, // 0 si no depende del stock avanzado
       "out_of_stock": 1, // 1 si se permite la compra cuando el stock está agotado, 2 si no se permite
       "id_shop": 1 
     }
   }
  • Ejemplo de Solicitud:
curl -X POST "https://example.com/api/stock_availables" \
--data '{
  "stock_available": {
    "id": 321,
    "id_product": 1,
    "id_product_attribute": 0,
    "quantity": "150",
    "depends_on_stock": 0,
    "out_of_stock": 1,
    "id_shop": 1
  }
}'
  • Ejemplo de Respuesta:
{
  "stock_available": {
    "id": "321",
    "id_product": "1",
    "id_product_attribute": "0",
    "quantity": "200",
    "depends_on_stock": "0",
    "out_of_stock": "2"
  }
}

Gestión de Precios Específicos (Descuentos)

La API de PrestaShop permite gestionar precios específicos (descuentos) para productos a través del endpoint /api/specific_prices. Los precios específicos permiten aplicar descuentos por porcentaje o monto fijo, con restricciones opcionales por fecha, cantidad mínima, grupo de clientes, moneda, país, tienda, combinación de producto, etc.

Propiedades de los Precios Específicos

Los precios específicos incluyen las siguientes propiedades:

  • id_product: ID del producto al que se aplica el precio específico (requerido)
  • id_product_attribute: ID de la combinación de producto (0 si aplica al producto base)
  • price: Precio fijo del producto. Usar -1 para mantener el precio del producto y aplicar solo el descuento
  • from_quantity: Cantidad mínima requerida para aplicar el precio específico
  • reduction: Valor del descuento (puede ser porcentaje o monto)
  • reduction_type: Tipo de descuento. Puede ser "percentage" (porcentaje) o "amount" (monto fijo)
  • reduction_tax: Indica si la reducción incluye impuestos. 0 = sin impuestos, 1 = con impuestos
  • from: Fecha de inicio del precio específico (formato: YYYY-MM-DD)
  • to: Fecha de fin del precio específico (formato: YYYY-MM-DD)
  • id_shop_group: ID del grupo de tiendas (0 para todos)
  • id_shop: ID de la tienda (1 por defecto)
  • id_cart: ID del carrito específico (0 para todos)
  • id_currency: ID de la moneda (0 para todas)
  • id_country: ID del país (0 para todos)
  • id_group: ID del grupo de clientes (1 por defecto)
  • id_customer: ID del cliente específico (0 para todos)
  • id_specific_price_rule: ID de la regla de precio específico (0 si no aplica)

1. Obtener Precios Específicos

Para obtener todos los precios específicos o filtrar por producto:

  • Método: GET /api/specific_prices o GET /api/specific_prices?filter[id_product]=[id_product]

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>
  • Ejemplo de Solicitud:

curl -X GET "https://example.com/api/specific_prices?filter[id_product]=[104077816]" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json"
  • Ejemplo de Respuesta:
{
  "specific_prices": [
    {
      "id": "15205375"
    }
  ]
}

2. Crear un Precio Específico

Para crear un nuevo precio específico (descuento) para un producto:

  • Método: POST /api/specific_prices

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>

2.1. Crear Descuento por Porcentaje

  • Payload:
{
  "specific_price": {
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "0.05",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}
  • Ejemplo de Solicitud:
curl -X POST "https://example.com/api/specific_prices" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json" \
--data '{
  "specific_price": {
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "0.05",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}'
  • Ejemplo de Respuesta:
{
  "specific_price": {
    "id": "15205379",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": -1,
    "from_quantity": "1",
    "reduction": "0.05",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}

2.2. Crear Descuento por Monto Fijo

  • Payload:
{
  "specific_price": {
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "1000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}
  • Ejemplo de Solicitud:
curl -X POST "https://example.com/api/specific_prices" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json" \
--data '{
  "specific_price": {
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "1000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}'
  • Ejemplo de Respuesta:
{
  "specific_price": {
    "id": "15205380",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": -1,
    "from_quantity": "1",
    "reduction": "1000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}

Notas importantes: - Para descuentos por porcentaje, el valor de reduction debe ser un decimal entre 0 y 1 (ej: 0.05 = 5%, 0.20 = 20%) - Para descuentos por monto fijo, el valor de reduction debe ser el monto en la moneda base (ej: 1000 = 1000 unidades de la moneda) - El campo price con valor -1 mantiene el precio original del producto y aplica solo el descuento - Las fechas from y to definen el período de validez del precio específico

3. Actualizar un Precio Específico

Para actualizar un precio específico existente:

  • Método: PUT /api/specific_prices/:id

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>

3.1. Actualizar Descuento por Porcentaje

  • Payload:
{
  "specific_price": {
    "id": "15205375",
    "id_product": "104077816",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "0.1",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}
  • Ejemplo de Solicitud:
curl -X PUT "https://example.com/api/specific_prices/15205375" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json" \
--data '{
  "specific_price": {
    "id": "15205375",
    "id_product": "104077816",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "0.1",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}'
  • Ejemplo de Respuesta:
{
  "specific_price": {
    "id": "15205375",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": -1,
    "from_quantity": "1",
    "reduction": "0.1",
    "reduction_tax": "0",
    "reduction_type": "percentage",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}

3.2. Actualizar Descuento por Monto Fijo

  • Payload:
{
  "specific_price": {
    "id": "15205380",
    "id_product": "104077816",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "2000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}
  • Ejemplo de Solicitud:
curl -X PUT "https://example.com/api/specific_prices/15205380" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json" \
--data '{
  "specific_price": {
    "id": "15205380",
    "id_product": "104077816",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": "-1.000000",
    "from_quantity": "1",
    "reduction": "2000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}'
  • Ejemplo de Respuesta:
{
  "specific_price": {
    "id": "15205380",
    "id_shop_group": "0",
    "id_shop": "1",
    "id_cart": "0",
    "id_product": "104077816",
    "id_product_attribute": "0",
    "id_currency": "0",
    "id_country": "0",
    "id_group": "1",
    "id_customer": "0",
    "id_specific_price_rule": "0",
    "price": -1,
    "from_quantity": "1",
    "reduction": "2000",
    "reduction_tax": "0",
    "reduction_type": "amount",
    "from": "2025-11-26",
    "to": "2025-11-27"
  }
}

4. Eliminar un Precio Específico

Para eliminar un precio específico:

  • Método: DELETE /api/specific_prices/:id

  • Headers:

    • Content-Type: application/json
    • Authorization: Basic <EncodedToken>
  • Payload: No se requiere un cuerpo de solicitud.

  • Ejemplo de Solicitud:

curl -X DELETE "https://example.com/api/specific_prices/15205375" \
-H "Authorization: Basic <EncodedToken>" \
-H "Content-Type: application/json"
  • Respuesta: Cuerpo vacío con un código de estado HTTP 200 OK si la eliminación fue exitosa.