> ## Documentation Index
> Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Productos

> Sube los datos maestros de tus productos, incluidos IDs, nombres, precios, costos y atributos, para alimentar la analítica de Retailgrid.

Especificación de los datos maestros de producto.

Consulta el archivo de ejemplo [**Sample\_products.csv**](https://drive.google.com/file/d/1Mj8DS0pTOdF747zNEAn4_5hCfxU10-Qo/view?usp=sharing).

> [!NOTE]
>
> 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](#10-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**](https://docs.retailgrid.io/es/data-requirements/sales.md):

| **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:**

```text theme={null}
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**

```text theme={null}
YYYY-MM-DD
```

Ejemplo:

```text theme={null}
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](#10-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:

```text theme={null}
item_id
product_name
price
unit_cost
```

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

```text theme={null}
item_id
product_name
price
unit_cost
brand
category 1–3
rrp
regular_price
vat_rate
currency
```

## 9. Ejemplo de esquema SQL

```text theme={null}
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.

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.