> ## 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.

# Ventas

> Sube datos de ventas a nivel de transacción para alimentar la analítica, el modelado de elasticidad y la optimización de precios en Retailgrid.

## Especificación de datos del historial de transacciones

Para analítica de ventas, modelado de elasticidad e inteligencia de retail.

Consulta el archivo de ejemplo [**sample\_transactions**](https://drive.google.com/file/d/1Q6ew53Np9Bj8WG_NzVOBNxYL9n1UCqM9/view?usp=sharing).

> [!NOTE]
>
> También puedes cargar datos de transacciones de forma programática mediante la **API REST de Retailgrid** pública. Las cargas por API usan nombres de campos y campos obligatorios ligeramente distintos. Consulta [Carga mediante la API](#11-carga-mediante-la-api) más abajo.

## 1. Objetivo

Usa este conjunto de datos para:

* Analítica del rendimiento de ventas
* Modelado de elasticidad de precios
* Estimación de la curva de demanda
* Optimización de precios
* Análisis del impacto de promociones
* Comparativa del rendimiento por tienda

Debes proporcionar los datos a **nivel de línea de transacción**.

## 2. Requisito de granularidad de los datos

Cada fila debe representar:

> **Un producto en una transacción**

Correcto:

| **transaction\_id** | **item\_id** | **quantity** |
| :- | :- | :- |
| TRX\_001 | SKU-1001 | 2 |
| TRX\_001 | SKU-1002 | 1 |

Incorrecto:

* Totales agregados por día
* Resúmenes a nivel de tienda
* Exportaciones pivotadas

## 3. Historial de transacciones: especificación de datos unificada

| **Nombre del campo** | **Obligatorio** | **Tipo** | **Formato** | **Descripción** | **Ejemplo** | **Nombres alternativos** |
| :- | :- | :- | :- | :- | :- | :- |
| transaction\_id | ✅ Sí | string | Único | Identificador único de la transacción. Debe ser estable y no reutilizarse. | TRX\_000123 | order id, receipt id, invoice id, ticket id |
| store\_id | ✅ Sí | string | Texto | Identificador de la tienda o punto de venta. | S001 | location id, branch id, outlet id |
| item\_id | ✅ Sí | string | Texto | Identificador único a nivel de SKU. Debe coincidir con `item_id` en el archivo maestro de productos. | SKU-1001 | product id, sku id, article id |
| transaction\_timestamp | ✅ Sí | datetime | YYYY-MM-DD HH:MM:SS | Fecha y hora de la transacción en formato ISO 8601. Preferiblemente en UTC. | 2026-02-18 14:22:05 | sale timestamp, order datetime, event time |
| quantity | ✅ Sí | decimal(12,2) o integer | Positivo para ventas, negativo para devoluciones | Unidades vendidas (positivo) o devueltas (negativo). No puede ser cero. | 3 / -1 | units, qty, quantity sold, units sold |
| selling\_price | ✅ Sí | decimal(12,2) | Separador de punto | Precio real pagado por unidad en esa transacción (tras el descuento). | 129.99 | unit price, final price, transaction price |
| regular\_price | ⬜ Opcional | decimal(12,2) | Separador de punto | Precio estándar del producto sin descuento en el momento de la venta. | 139.99 | base price, list price, shelf price |
| unit\_cost | ⬜ Opcional | decimal(12,2) | 2 decimales | Costo por unidad en el momento de la transacción (para el cálculo del margen). | 80.00 | cost price, cogs unit, purchase cost |
| discount\_rate | ⬜ Opcional | decimal(5,4) | 0 a 1 | Descuento aplicado como tasa (0.15 = 15%). | 0.15 | discount pct, promo rate |
| sales\_value | ⬜ Opcional | decimal(12,2) | Separador de punto | Valor total de la transacción por fila. Si se proporciona, debe ser igual a `quantity × selling_price`. | 389.97 | revenue, line revenue, gross sales |
| gross\_profit | ⬜ Opcional | decimal(12,2) | Separador de punto | Beneficio bruto por fila. Si se proporciona, debe ser igual a `(selling_price - unit_cost) × quantity`. | 149.97 | margin value, contribution margin |
| stock\_after\_sale | ⬜ Opcional | integer | ≥ 0 | Nivel de inventario después de la transacción. | 37 | stock on\_hand, inventory after |
| currency | ⬜ Opcional\* | string(3) | ISO 4217 | Código de moneda usado en los campos de precio. Obligatorio si hay varias monedas. | EUR | currency code |
| tax\_rate | ⬜ Opcional | decimal(5,4) | 0 a 1 | Tipo de IVA/impuesto aplicado (0.20 = 20%). | 0.20 | vat rate, tax percentage |
| transaction\_type | ⬜ Opcional | string | sale / return | Tipo de transacción. Si es devolución, la cantidad debe ser negativa. | sale | order type, operation type |

## 4. Política de gestión de devoluciones (obligatoria si existen devoluciones)

Las devoluciones deben proporcionarse como filas de transacción separadas.

### **4.1 Formato de las devoluciones**

| **Campo** | **Valor** |
| :- | :- |
| transaction\_type | return |
| quantity | Valor negativo |
| selling\_price | Positivo |
| transaction\_timestamp | Hora real de la devolución |
| item\_id | El mismo que la venta original |

### **4.2 Ejemplo**

**Venta original**

| **transaction\_id** | **item\_id** | **quantity** | **selling\_price** | **transaction\_type** |
| :- | :- | :- | :- | :- |
| TRX\_1001 | SKU-1001 | 2 | 129.99 | sale |

**Devolución**

| **transaction\_id** | **item\_id** | **quantity** | **selling\_price** | **transaction\_type** |
| :- | :- | :- | :- | :- |
| TRX\_1055 | SKU-1001 | -1 | 129.99 | return |

### **4.3 Reglas importantes**

* NO elimines las filas de la venta original
* NO agregues valores netos antes de exportar
* NO uses cantidades positivas para las devoluciones
* unit\_price debe seguir siendo positivo
* Las devoluciones deben reflejar la fecha real de la devolución

## 5. Requisitos de formato de datos (estrictos)

### 5.1 Marca de tiempo

Debe seguir ISO 8601:

```text theme={null}
YYYY-MM-DD HH:MM:SS
```

Ejemplo:

```text theme={null}
2026-02-18 14:22:05
```

Zona horaria:

* Preferiblemente UTC
* O bien la zona horaria debe indicarse claramente

### **5.2 Campos numéricos**

* Separador decimal: `.`
* Sin separadores de miles
* Sin símbolos de moneda
* Sin formatos localizados

Correcto:

```text theme={null}
129.99
```

Incorrecto:

```text theme={null}
129,99
1 299.99
$129.99
```

### 5.3 Formato del descuento

Debe ser una tasa:

```text theme={null}
0.15  = 15%
0.00  = no discount
```

No:

```text theme={null}
15%
-20
```

## 6. Formato de archivo

Aceptados:

* CSV (codificación UTF-8), preferido
* XLSX

Sin tablas dinámicas\
Sin fórmulas\
Solo datos en bruto

## 7. Requisitos de datos históricos

Mínimo:

* De 6 a 12 meses de historial
* Preferiblemente 24 meses

Volumen mínimo recomendado:

* Más de 10.000 filas de transacciones por tienda

## 8. Reglas de validación de datos

* quantity ≠ 0
* quantity > 0 para ventas
* quantity \< 0 para devoluciones
* unit\_price ≥ 0
* discount\_rate entre 0 y 1
* transaction\_timestamp no nulo
* item\_id debe existir en el archivo maestro de productos

## 9. Ejemplo de esquema SQL

```text theme={null}
CREATE TABLE transaction_history (
    transaction_id VARCHAR(64) NOT NULL,
    store_id VARCHAR(32) NOT NULL,
    item_id VARCHAR(64) NOT NULL,
    transaction_timestamp TIMESTAMP NOT NULL,
    quantity INT NOT NULL,
    unit_price DECIMAL(12,2) NOT NULL,
    unit_cost DECIMAL(12,2),
    discount_rate DECIMAL(5,4),
    stock_after_sale INT,
    currency CHAR(3),
    transaction_type VARCHAR(16),
    sales_channel VARCHAR(16)
);
```

## 10. Conjunto de datos mínimo (si existen limitaciones del sistema)

Si el sistema no puede proporcionar la estructura completa, el mínimo obligatorio es:

```text theme={null}
transaction_id
store_id
item_id
transaction_timestamp
quantity
selling_price
```

Las devoluciones deben seguir igualmente la lógica de cantidad negativa.

## 11. Carga mediante la API

La API REST pública acepta los mismos datos a través de `POST /v1/transactions/bulk` (registros JSON) o `POST /v1/imports/transactions` (importación de CSV), con dos diferencias respecto al esquema CSV:

* No existe el campo `transaction_id` en la API. Usa el campo opcional `external_transaction_id` para transportar tu propio identificador de transacción; la API no exige uno.
* Campos obligatorios en las cargas por API: `item_id`, `store_id`, `transaction_timestamp`, `quantity`, `selling_price`.

Campos opcionales solo de la API: `sku`, `region`, `promo_type`, `zone_price`.

> [!WARNING]
>
> La API JSON rechaza los campos desconocidos: las cargas que contengan campos fuera del esquema no superan la validación.


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