Productos

Especificación de los datos maestros de producto. Consulta el archivo de ejemplo Sample_products.csv.

También puedes cargar datos de producto de forma programática mediante la API REST de Retailgrid pública. Los payloads de la API usan nombres de campo y campos obligatorios ligeramente distintos. Consulta Carga mediante la API más abajo.

1. Objetivo

El conjunto de datos maestros de producto sirve para:

Vincular transacciones con productos
Calcular el margen (mediante unit_cost)
Analítica a nivel de categoría
Análisis de marca y surtido
Modelado de elasticidad
Análisis de corredor de precios

Cada fila representa:

Un ítem vendible (nivel de SKU)

2. Integridad referencial (crítico)

Los siguientes campos deben coincidir exactamente con el historial de transacciones:

Archivo de productos	Archivo de transacciones
item_id	item_id

Si item_id no coincide, las transacciones no se pueden vincular.

3. Datos maestros de producto - especificación unificada

Nombre del campo	Obligatorio	Tipo	Formato	Descripción	Ejemplo	Nombres alternativos
item_id	✅ Sí	string	Único	Identificador único a nivel de SKU. Vincula las transacciones, los datos de tienda y los datos de competidores con este ítem.	SKU-1001	item id, sku id, article id
product_id	⬜ Opcional	string	Texto	Código a nivel de producto que agrupa ítems / variantes relacionados bajo un mismo producto.	P001	product code, style code, product group code
product_name	✅ Sí	string	Texto	Nombre completo del producto	Cordless Drill 18V Blue	SKU Name, Product Title, Product Variant Name
price	✅ Sí	decimal(12,2)	Separador de punto	El precio de venta real. Precio actual	129.99	Current Price, Actual Price
unit_cost	✅ Sí	decimal(12,2)	2 decimales	Costo por unidad en el momento de la venta	80.00	Cost Price, Purchase Cost, Purchase Price
sku	⬜ Opcional	string	Texto	Unidad de mantenimiento de stock (SKU)	SKU-1001	SKU Code
barcode	⬜ Opcional	string	EAN/UPC	Valor del código de barras	5901234123457	EAN, UPC, GTIN
brand	⬜ Opcional	string	Texto	Nombre de la marca	Bosch	Brand Name, Label, Trademark
manufacturer	⬜ Opcional	string	Texto	Nombre del fabricante	Bosch	Producer, Mfg
long_description	⬜ Opcional	string	Texto	Descripción más larga del producto para contexto y matching. No sustituye a product_name.	18V cordless drill with 2 batteries, charger and case	Long desc, Detailed description, Full description
supplier	⬜ Opcional	string	Texto	Proveedor o vendedor del que procede el ítem	Northwind Supply	Supplier name, Vendor, Vendor name
manufacturer_code	⬜ Opcional	string	Texto (se conservan los ceros iniciales)	Código propio del fabricante para el ítem	001234	Manufacturer ID, Mfg code, Mfr code, MPN
supplier_code	⬜ Opcional	string	Texto (se conservan los ceros iniciales)	Código propio del proveedor para el ítem	000567	Supplier ID, Vendor code, Vendor ID
product_group	⬜ Opcional	string	Texto	Grupo lógico de producto	Drill-18V	Pricing group, Assortment Group, Product family
status	⬜ Opcional	string	active / inactive	Estado del ciclo de vida del producto	active	Lifecycle Status, Availability status
stock	⬜ Opcional	integer	≥ 0	Nivel de stock actual	125	Inventory level, Stock_on_hand, Available quantity
product_type	⬜ Opcional	string	Texto	Clasificación del producto	Power Tools	Item type
category1	⬜ Opcional	string	Texto	Categoría de nivel superior	Tools	Department
category2	⬜ Opcional	string	Texto	Subcategoría	Power Tools
category3	⬜ Opcional	string	Texto	Subcategoría de nivel 3	Drills
category4	⬜ Opcional	string	Texto	Subcategoría de nivel 4	Cordless
category5	⬜ Opcional	string	Texto	Subcategoría de nivel 5	18V
image_url	⬜ Opcional	string	URL	URL de la imagen del producto	https://…
product_url	⬜ Opcional	string	URL	URL de la página del producto	https://…
rrp	⬜ Opcional	decimal(12,2)	2 decimales	Precio de venta recomendado	129.99	MSRP, List Price, Recommended Price
regular_price	⬜ Opcional	decimal(12,2)	Separador de punto	El precio estándar, sin descuento, del producto	139.99	Base price, Normal price, Standard price
product_created_date	⬜ Opcional	date	YYYY-MM-DD	Fecha de creación del producto	2024-01-15	Product Launch date
price_effective_date	⬜ Opcional	date	YYYY-MM-DD	Fecha de vigencia del precio	2026-02-01	Price start date, Price valid from
cost_effective_date	⬜ Opcional	date	YYYY-MM-DD	Fecha de vigencia del costo	2026-01-15	Cost start date, Cost valid from
size	⬜ Opcional	decimal o string	Numérico o texto	Valor de talla o tamaño	12	Variant size
uom	⬜ Opcional	string	Código de unidad	Unidad de medida	pcs	Unit, Measurement unit
tax_rate	⬜ Opcional	decimal(5,4)	0-1	Tasa de IVA (0.20 = 20 %)	0.20	Tax rate, Vat percentage
currency	⬜ Opcional	string(3)	Código ISO	Moneda	EUR	Currency code, Iso currency

4. Alineación con el esquema de transacciones

4.1 Claves. Alineación obligatoria:

transaction.item_id = product.item_id

4.2 Consistencia de moneda. Si las transacciones incluyen currency, el archivo de productos debe incluir currency. 4.3 Consistencia del IVA. Si el IVA está incluido en los precios de las transacciones:

Proporciona vat_rate en el archivo de productos
Aclara si unit_price en las transacciones es bruto o neto

5. Requisitos de formato de datos

5.1 Fechas

YYYY-MM-DD

Ejemplo:

2026-02-18

5.2 Campos numéricos

Separador decimal: .
Sin símbolos de moneda
Sin separadores de miles

6. Atributos personalizados (modelo de extensibilidad)

Puedes añadir atributos adicionales como columnas extra. Ejemplos:

material
color
season
gender
warranty_months
competitor_reference
margin_group
elasticity_cluster

Reglas para los atributos personalizados

No deben sobrescribir los nombres de las columnas obligatorias
Deben seguir una nomenclatura consistente
Deben contener un único valor por fila
Sin JSON anidado dentro de las celdas de Excel
Solo para carga CSV / XLSX. La API JSON rechaza los campos desconocidos (consulta Carga mediante la API)

Ejemplo:

item_id	product_name	material	color
SKU-1001	Tent 3P	Polyester	Green

7. Formato de archivo

Se acepta:

CSV (preferiblemente UTF-8)
XLSX

Una fila por SKU. Sin tablas dinámicas.
Sin fórmulas.
Solo datos en bruto.

8. Conjunto de datos de producto mínimo (mínimo absoluto)

Si existen limitaciones del sistema:

item_id
product_name
price
unit_cost

Sin embargo, para la analítica de precios se recomienda encarecidamente incluir:

item_id
product_name
price
unit_cost
brand
category 1–3
rrp
regular_price
vat_rate
currency

9. Ejemplo de esquema SQL

CREATE TABLE product_master (
    item_id VARCHAR(64) PRIMARY KEY,
    product_id VARCHAR(64),
    product_name VARCHAR(255) NOT NULL,
    sku VARCHAR(64),
    barcode VARCHAR(64),
    brand VARCHAR(128),
    manufacturer VARCHAR(128),
    long_description TEXT,
    supplier VARCHAR(255),
    manufacturer_code VARCHAR(255),
    supplier_code VARCHAR(255),
    product_group VARCHAR(128),
    status VARCHAR(32),
    stock INT,
    product_type VARCHAR(128),
    category1 VARCHAR(128),
    category2 VARCHAR(128),
    category3 VARCHAR(128),
    category4 VARCHAR(128),
    category5 VARCHAR(128),
    image_url TEXT,
    product_url TEXT,
    size VARCHAR(64),
    uom VARCHAR(32),
    product_created_date DATE,
    rrp DECIMAL(12,2),
    regular_price DECIMAL(12,2),
    vat_rate DECIMAL(5,4),
    currency CHAR(3),
    price_effective_date DATE,
    cost_effective_date DATE
);

10. Carga mediante la API

La API REST pública acepta los mismos datos a través de POST /v1/products/bulk (registros JSON) o POST /v1/imports/products (importación CSV). Los payloads JSON usan nombres distintos para algunos campos y un conjunto de campos obligatorios diferente. Campos obligatorios en los payloads de la API: item_id, sku, sku_name, current_price, unit_cost.

Columna CSV	Campo de la API	Notas
price	`current_price`	Obligatorio. No existe un campo `price` en la API.
product_name	`sku_name`	Obligatorio. La API también tiene un `product_name` opcional para el nombre a nivel de producto.
sku	`sku`	Obligatorio en los payloads de la API (opcional en CSV).
stock	`stock_on_hand`
category1 - category5	`category_1` - `category_5`	Con guion bajo en la API.
-	`color`	Campo opcional disponible solo en la API.

Todos los demás campos conservan los mismos nombres que las columnas CSV anteriores, incluidos los campos opcionales long_description, supplier, manufacturer_code y supplier_code. Se devuelven en cada lectura de producto y se aceptan en la creación, en PATCH y en el upsert masivo. Cuando haces PATCH de un producto, un campo omitido conserva su valor actual. Envía un null explícito para borrarlo.

Los atributos personalizados como columnas extra solo se admiten en la carga CSV / XLSX. La API JSON rechaza los campos desconocidos: los payloads que contienen campos fuera del esquema no superan la validación.

Especificaciones de datos

Glosario

1. Objetivo

2. Integridad referencial (crítico)

3. Datos maestros de producto - especificación unificada

4. Alineación con el esquema de transacciones

5. Requisitos de formato de datos

6. Atributos personalizados (modelo de extensibilidad)

7. Formato de archivo

8. Conjunto de datos de producto mínimo (mínimo absoluto)

9. Ejemplo de esquema SQL

10. Carga mediante la API

​1. Objetivo

​2. Integridad referencial (crítico)

​3. Datos maestros de producto - especificación unificada

​4. Alineación con el esquema de transacciones

​5. Requisitos de formato de datos

​6. Atributos personalizados (modelo de extensibilidad)

​7. Formato de archivo

​8. Conjunto de datos de producto mínimo (mínimo absoluto)

​9. Ejemplo de esquema SQL

​10. Carga mediante la API

1. Objetivo

2. Integridad referencial (crítico)

3. Datos maestros de producto - especificación unificada

4. Alineación con el esquema de transacciones

5. Requisitos de formato de datos

6. Atributos personalizados (modelo de extensibilidad)

7. Formato de archivo

8. Conjunto de datos de producto mínimo (mínimo absoluto)

9. Ejemplo de esquema SQL

10. Carga mediante la API