Ventas

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.

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

YYYY-MM-DD HH:MM:SS

Ejemplo:

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:

129.99

Incorrecto:

129,99
1 299.99
$129.99

5.3 Formato del descuento

Debe ser una tasa:

0.15  = 15%
0.00  = no discount

No:

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

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:

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.

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

Especificaciones de datos

Glosario

Especificación de datos del historial de transacciones

1. Objetivo

2. Requisito de granularidad de los datos

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

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

4.1 Formato de las devoluciones

4.2 Ejemplo

4.3 Reglas importantes

5. Requisitos de formato de datos (estrictos)

5.1 Marca de tiempo

5.2 Campos numéricos

5.3 Formato del descuento

6. Formato de archivo

7. Requisitos de datos históricos

8. Reglas de validación de datos

9. Ejemplo de esquema SQL

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

11. Carga mediante la API

​Especificación de datos del historial de transacciones

​1. Objetivo

​2. Requisito de granularidad de los datos

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

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

​4.1 Formato de las devoluciones

​4.2 Ejemplo

​4.3 Reglas importantes

​5. Requisitos de formato de datos (estrictos)

​5.1 Marca de tiempo

​5.2 Campos numéricos

​5.3 Formato del descuento

​6. Formato de archivo

​7. Requisitos de datos históricos

​8. Reglas de validación de datos

​9. Ejemplo de esquema SQL

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

​11. Carga mediante la API

Especificación de datos del historial de transacciones

1. Objetivo

2. Requisito de granularidad de los datos

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

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

4.1 Formato de las devoluciones

4.2 Ejemplo

4.3 Reglas importantes

5. Requisitos de formato de datos (estrictos)

5.1 Marca de tiempo

5.2 Campos numéricos

5.3 Formato del descuento

6. Formato de archivo

7. Requisitos de datos históricos

8. Reglas de validación de datos

9. Ejemplo de esquema SQL

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

11. Carga mediante la API