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

# Precios de competidores

> Carga precios de competidores como datos emparejados, valida cada coincidencia en Competitor matching y deja que los precios aprobados alimenten tu pricing.

Los precios de competidores llegan a Retailgrid como **datos emparejados**: una fila por cada vínculo entre uno de tus productos y una ficha de producto de un competidor, con el precio del competidor en esa ficha.

Los datos emparejados son la forma principal de cargar precios de competidores. Cada fila pasa por [Matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md), donde compruebas la cobertura y la calidad, y después [revisas y apruebas las coincidencias](https://docs.retailgrid.io/es/price-monitoring/review-matches.md). Las coincidencias aprobadas se convierten en los precios de competidores que leen tus Grids, las métricas CPI y las reglas Price Match.

Los precios de competidores emparejados alimentan:

* El análisis de posicionamiento competitivo
* Los cálculos de brecha de precio e índice de precio
* La automatización de precios dinámicos
* El monitoreo de promociones
* El modelado de elasticidad y presión competitiva con IA

## Cómo cargar datos emparejados

| Método | Cuándo usarlo |
| :- | :- |
| **Update** en la página [Matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md) | Entregas puntuales o manuales |
| [`POST /v1/matching/matched-snapshots`](https://docs.retailgrid.io/es/api-reference/matching/overview) | Feeds programados desde un scraper, una canalización de matching o un partner |

Ambos aceptan el mismo CSV UTF-8, ejecutan la misma validación y publican de la misma forma. La API admite un archivo por solicitud, de hasta 25 MiB en total. Consulta [Cargas de matching](https://docs.retailgrid.io/es/api-reference/matching/overview.md) para las opciones de cobertura, el sondeo del progreso y la gestión de errores.

La cabecera decide cómo se procesa un archivo:

* **`item_id` está presente** - el archivo se trata como datos emparejados y se publica contra tu catálogo de Products.
* **`item_id` está ausente** - el archivo se trata como una exportación de competidor sin emparejar, y Retailgrid lo empareja primero con tu catálogo. Consulta [Exportaciones de competidores sin emparejar](#exportaciones-de-competidores-sin-emparejar).

> [!NOTE]
>
> Sube el conjunto emparejado completo con una cadencia regular (diaria funciona bien), no un delta. Las filas sin cambios conservan su historial, y los precios que cambian se registran como una nueva observación sobre la misma coincidencia.

## Esquema de los datos emparejados

Los nombres de columna son exactos y distinguen mayúsculas de minúsculas. Toda columna que describe la ficha del competidor empieza por `competitor_`. Las columnas sin prefijo describen tu producto (`item_id`) o la propia coincidencia (`match_*`).

### Columnas obligatorias

| Columna | Tipo | Formato | Descripción | Ejemplo |
| :- | :- | :- | :- | :- |
| `item_id` | string | Texto, hasta 128 caracteres | Tu identificador a nivel de SKU. Debe existir en tu conjunto de datos [Products](https://docs.retailgrid.io/es/data-requirements/products.md). Se envía byte a byte: se conservan los ceros iniciales y las mayúsculas. | 0334800002 |
| `competitor_url` | string | URL `http(s)` absoluta | La página de producto del competidor de la que se capturó el precio. | [https://www.fortinos.ca/shilajit/p/21708560\_EA](https://www.fortinos.ca/shilajit/p/21708560_EA) |
| `competitor_product_name` | string | Texto | El título de la ficha tal como lo muestra el competidor. Se muestra junto a tu producto en la cola de revisión. | Shilajit, 100 ea |
| `competitor_price` | decimal | Separador de punto, hasta 4 decimales | El precio que cobra actualmente el competidor (el precio efectivo). Debe ser mayor que 0. | 27.99 |
| `competitor_currency` | string | ISO 4217, 3 letras | Moneda de todas las columnas de precio de la fila. Obligatoria siempre que haya un precio. | CAD |

### Columnas de la coincidencia

Describen la coincidencia: cuál de tus productos es la ficha y con qué fundamento. Son opcionales, pero envíalas. La cola de revisión filtra y ordena por ellas, y las políticas de aprobación automática usan la confianza y el tipo de coincidencia para decidir qué coincidencias se saltan la revisión manual.

| Columna | Tipo | Valores permitidos | Descripción | Ejemplo |
| :- | :- | :- | :- | :- |
| `match_relation` | string | `direct`, `substitute`, `unknown` | `direct` es el mismo producto. `substitute` es una alternativa comparable. Vacío se registra como `unknown`. | direct |
| `match_method` | string | `barcode`, `manufacturer_code`, `fuzzy`, `embedding`, `llm` | Cómo estableció el vínculo tu sistema de matching. | barcode |
| `match_confidence` | decimal | 0 a 1 | La confianza de tu sistema de matching. Déjalo vacío si no se conoce: `0` significa "con seguridad no es una coincidencia". | 0.93 |
| `source` | string | `client`, `ai_search`, `domain_scraping`, `google_shopping`, `amazon` | Dónde se recogió el precio. | domain\_scraping |
| `external_match_id` | string | Texto, hasta 128 caracteres | Tu propio ID para esta coincidencia. Se guarda como procedencia. Retailgrid asigna su propio ID de coincidencia. | 0334800002\|Fortinos |

### Columnas de precio y disponibilidad

| Columna | Tipo | Formato | Descripción | Ejemplo |
| :- | :- | :- | :- | :- |
| `competitor_regular_price` | decimal | Separador de punto | Precio regular (sin descuento). | 32.99 |
| `competitor_promo_price` | decimal | Separador de punto | Precio promocional. Si está presente, debe ser igual a `competitor_price` y no debe superar `competitor_regular_price`. | 27.99 |
| `availability` | string | `in_stock`, `out_of_stock`, `preorder`, `backorder`, `discontinued`, `unknown` | Si la ficha se puede comprar. | in\_stock |
| `competitor_status` | string | Texto | El estado de ciclo de vida de la ficha tal como lo indica la fuente, por ejemplo `active` o `discontinued`. Se mantiene separado de `availability`. | active |
| `competitor_stock_on_hand` | integer | Número entero, 0 o más | Cantidad en stock, solo cuando se conoce un número real. | 125 |
| `observed_at` | fecha o fecha y hora | `YYYY-MM-DD`, o ISO 8601 con desplazamiento UTC | Cuándo se observó el precio. Una fecha sola se interpreta como el inicio de ese día en UTC. | 2026-10-27 |

### Columnas de la ficha del competidor

| Columna | Tipo | Descripción | Ejemplo |
| :- | :- | :- | :- |
| `competitor_name` | string | El nombre visible del minorista. Agrupa los precios por competidor en todo Retailgrid. | Fortinos |
| `competitor_domain` | string | Host en minúsculas del sitio del competidor. Se toma de `competitor_url` cuando está vacío, y debe coincidir con su host cuando se rellena. | fortinos.ca |
| `competitor_sku` | string | El código de producto del competidor. | 21708560\_EA |
| `competitor_barcode` | string | EAN / UPC / GTIN. Conserva los ceros iniciales. | 00803348000028 |
| `competitor_manufacturer_code` | string | Número de pieza del fabricante (MPN). Se espera cuando `match_method` es `manufacturer_code`. | LS-SHJ-100 |
| `competitor_brand` | string | Marca tal como aparece en la ficha. | Leaf source |
| `competitor_image_url` | string | URL absoluta de la imagen del producto. La forma más rápida para que un revisor confirme una coincidencia. | [https://digital.loblaws.ca/21708560.jpg](https://digital.loblaws.ca/21708560.jpg) |
| `competitor_category_1` ... `competitor_category_5` | string | Los niveles de categoría propios del competidor. Se muestran como referencia; la agrupación siempre usa tus categorías. | Health & Wellness |
| `attributes` | objeto JSON | Cualquier dato no cubierto por otra columna. Un objeto plano con valores escalares, hasta 50 claves y 8 KB. | `{"shelf":"A3"}` |

### Columnas de variante

Cuando una página de competidor vende varios tamaños o variantes, estas columnas los distinguen. Envía `competitor_variant_sku` siempre que la página exponga uno: es la señal de variante más fiable.

| Columna | Descripción | Ejemplo |
| :- | :- | :- |
| `competitor_variant_sku` | El ID del competidor para la variante concreta. | 21708560\_EA\_100 |
| `competitor_size`, `competitor_uom` | Tamaño del envase y su unidad. | 100, ea |
| `competitor_pack_count` | Unidades por paquete. | 6 |
| `competitor_colour`, `competitor_flavour` | Variante de color o sabor. | Mint |
| `competitor_strength`, `competitor_strength_uom` | Concentración y su unidad. | 500, mg |
| `competitor_seller` | Vendedor del marketplace, cuando el sitio aloja varios. | Leaf Source Store |

### Archivo de ejemplo

```csv theme={null}
item_id,competitor_name,competitor_url,competitor_product_name,competitor_price,competitor_regular_price,competitor_promo_price,competitor_currency,competitor_barcode,competitor_sku,match_relation,match_method,match_confidence,source,availability,observed_at
0334800002,Fortinos,https://www.fortinos.ca/shilajit/p/21708560_EA,"Shilajit, 100 ea",27.99,32.99,27.99,CAD,00803348000028,21708560_EA,direct,barcode,0.93,domain_scraping,in_stock,2026-10-27
0334800002,Well.ca,https://well.ca/products/leaf-source-shilajit_100.html,"Leaf Source Shilajit 100 count",31.49,31.49,,CAD,00803348000028,LS-100,direct,barcode,0.97,domain_scraping,in_stock,2026-10-27
```

Un producto emparejado en dos competidores son dos filas con el mismo `item_id`.

## Reglas del archivo

* CSV UTF-8 con una fila de cabecera. La cabecera debe caber en 64 KiB.
* Una fila = uno de tus productos x una ficha de competidor.
* Una celda vacía significa "no indicado". Nunca significa cero.
* Los precios son decimales simples con separador de punto, sin separador de miles ni símbolo de moneda.
* Todos los precios de una fila comparten la moneda de `competitor_currency`.
* Las columnas no listadas en esta página se rechazan. Pon los datos adicionales en `attributes`.
* `confidence`, `verified`, `matched_by`, `assurance`, `review_status` y campos de revisión similares están reservados. Retailgrid los establece durante la validación y la revisión, así que un archivo no puede hacerlo.
* Cada columna puede aparecer solo una vez.

## Qué ocurre después de la carga

1. **Comprobación de la cabecera.** El archivo completo se rechaza si tiene una columna desconocida, reservada o duplicada, o si no tiene `item_id`. Todas las columnas problemáticas se indican a la vez.
2. **Validación de filas.** Cada fila se comprueba contra las reglas anteriores. Las filas rechazadas se informan con su número de línea y un código de motivo; el resto continúa. Si se rechazan demasiadas filas, toda la entrega falla y no se publica nada.
3. **Publicación.** Las coincidencias aceptadas aparecen en la página [Matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md).
4. **Revisión.** Las coincidencias esperan en [Revisar coincidencias](https://docs.retailgrid.io/es/price-monitoring/review-matches.md) hasta su aprobación, salvo que una política de aprobación automática las apruebe.
5. **Pricing.** Las coincidencias directas aprobadas que están en stock (o cuya disponibilidad es desconocida) alimentan los precios de competidores en los Grids, las métricas CPI y las reglas Price Match.

La cobertura controla qué coincidencias existentes puede retirar una entrega. El valor por defecto, `partial`, nunca elimina competidores que el archivo no menciona. `full` declara que el archivo lo es todo y retira lo que omite. Consulta [Cargas de matching](https://docs.retailgrid.io/es/api-reference/matching/overview.md).

## Reglas de validación

Motivos habituales por los que se rechaza una fila:

| Código | Causa |
| :- | :- |
| `field_required` | `item_id`, `competitor_url`, `competitor_product_name` o `competitor_price` está vacío. |
| `amount_not_decimal_string`, `amount_not_positive` | Un precio no es un número, o es 0 o menor. |
| `currency_invalid` | `competitor_currency` falta o no es un código ISO de 3 letras. |
| `promo_above_regular` | `competitor_promo_price` es mayor que `competitor_regular_price`. |
| `promo_not_effective` | `competitor_promo_price` está relleno pero difiere de `competitor_price`. |
| `url_not_absolute` | `competitor_url` o `competitor_image_url` no es una URL `http(s)` completa. |
| `domain_url_mismatch` | `competitor_domain` difiere del host de `competitor_url`. |
| `match_relation_unknown_value`, `match_method_unknown_value`, `source_unknown_value`, `availability_unknown_value` | Un valor está fuera de la lista permitida. |
| `confidence_out_of_range` | `match_confidence` es menor que 0 o mayor que 1. |
| `observed_at_naive` | Una fecha y hora no tiene desplazamiento UTC. Añade uno (`2026-10-27T14:35:00Z`) o envía solo la fecha. |
| `observed_at_in_future` | `observed_at` está más de un día en el futuro. |
| `stock_not_integer` | `competitor_stock_on_hand` no es un número entero. |
| `field_too_long` | Un identificador supera los 128 caracteres, o un campo de texto supera su límite. |

Una fila cuyo `item_id` no está en tu catálogo de Products también se rechaza.

Algunos problemas rechazan toda la entrega en lugar de una sola fila:

* Dos filas describen la misma coincidencia (mismo `item_id`, URL y variante).
* La misma URL de competidor es específica de variante en una fila pero no en otra.
* El nombre, código de barras, MPN o tamaño de un producto cambió en tu catálogo después de que empezara la carga. Vuelve a exportar esas filas y súbelas de nuevo.

## Exportaciones de competidores sin emparejar

Si tienes fichas de competidores pero todavía no tienes coincidencias, sube el mismo archivo sin `item_id` y sin las columnas de la coincidencia (`external_match_id`, `match_relation`, `match_method`, `match_confidence`). Retailgrid empareja cada ficha con tu catálogo usando el código de barras y el nombre del producto, y después publica los resultados en Competitor matching para su revisión, como con cualquier archivo emparejado.

Para obtener la mejor tasa de emparejamiento sin emparejar, rellena `competitor_barcode` y `competitor_product_name` en todas las filas.

## Alcance de los competidores

Por defecto, cada competidor se aplica a todas tus tiendas. Si distintas tiendas, zonas de precios o canales de venta se enfrentan a rivales distintos, acota cada competidor al lugar donde compite - consulta [Asignar competidores a tiendas, zonas y canales](https://docs.retailgrid.io/es/stores/assign-competitors.md). El alcance determina qué competidores usan las reglas de precios por tienda y las métricas de brecha con competidores.

## Lógica de interpretación de precios

* `competitor_price` es el precio de venta activo.
* Si `competitor_regular_price` está presente, Retailgrid calcula el % de descuento, la profundidad de la promoción, la brecha de precio respecto a tu precio y el índice de precio a partir del par.
* Si solo está presente `competitor_price`, se usa como precio activo y como precio regular.

Sube los precios de competidores en la misma moneda que los precios de tus productos siempre que sea posible. Si hay varias monedas, configura reglas de conversión de tipo de cambio.

## Historial de precios

Cada entrega se guarda. Cada coincidencia conserva una identidad estable entre cargas, de modo que un cambio de precio en la misma ficha amplía el historial de esa coincidencia en lugar de crear una fila nueva. Esto permite:

* Seguimiento de cambios de precio
* Análisis de frecuencia de promociones
* Puntuación de volatilidad
* Detección de guerras de precios
* Clasificación EDLP frente a Hi-Lo
* Modelado de elasticidad con IA

## Otras formas de cargar precios de competidores

El **conjunto de datos Competitor Prices** importa observaciones de precio directamente, sin pasar por Competitor matching. Úsalo para cargar precios históricos (se recomiendan de 6 a 24 meses) o cuando solo tienes observaciones a nivel de SKU y no URLs de fichas. Las filas cargadas de esta forma no se revisan en Competitor matching.

> **Esquema del conjunto de datos Competitor Prices**
>
> Cada fila es una observación de precio de un competidor para un producto en un momento dado.
>
> | Nombre del campo | Obligatorio | Tipo | Formato | Descripción | Nombres alternativos | Ejemplo |
> | :- | :- | :- | :- | :- | :- | :- |
> | `itemId` | ⬜ No\* | string | Texto | Identificador a nivel de SKU vinculado a tu conjunto de datos Products | item\_id, sku\_id, product\_code | SKU-1001 |
> | `datetime` | ✅ Sí | datetime | YYYY-MM-DD HH:MM:SS | Fecha y hora de la observación | date, timestamp, observed\_at, price\_date | 2026-02-22 14:35:00 |
> | `competitorName` | ✅ Sí | string | Texto | Nombre del competidor / minorista | competitor, seller, shop\_name, retailer | Bauhaus |
> | `regularPrice` | ✅ Sí | float | Separador de punto | Precio regular (sin descuento) | price, list\_price, base\_price | 125 |
> | `promoPrice` | ⬜ No | float | Separador de punto | Precio promocional, si lo hay | sale\_price, discounted\_price, promo\_price | 119.99 |
> | `currency` | ⬜ No | string | ISO 4217 | Código de moneda | curr, currency\_code | EUR |
> | `url` | ⬜ No | string | URL | Página de producto de origen | link, product\_url, source\_url | [https://bauhaus.fi/product123](https://bauhaus.fi/product123) |
> | `barcode` | ⬜ No | string | Texto | Código de barras EAN / UPC | ean, ean13, upc, gtin | 5901234123457 |
> | `sku` | ⬜ No | string | Texto | SKU del competidor | competitor\_sku, seller\_sku | SKU-1001 |
> | `status` | ⬜ No | string | Texto | Estado de ciclo de vida (active / discontinued) | availability\_status, product\_status | active |
> | `stock` | ⬜ No | float | Numérico | Cantidad disponible, si se conoce | inventory, stock\_qty, quantity\_available | 125 |
>
> \* Se requiere al menos un identificador (`itemId`, `barcode` o `sku`). Retailgrid vincula cada fila a tus productos primero por `itemId`, luego por `barcode` y luego por `sku`. Proporciona `itemId` para tener el menor número de filas sin vincular.
>
> Los formatos admitidos son CSV (recomendado) y XLSX, en UTF-8, con separador decimal de punto. Una fila = un producto x un competidor x una marca de tiempo. Se pueden añadir atributos adicionales como columnas en las cargas CSV / XLSX.
>
> La carga falla si falta `datetime`, `competitorName` o `regularPrice`, si no hay ningún identificador, si `datetime` o `regularPrice` no es válido, si las filas no se pueden vincular a tu conjunto de datos Products, o si hay filas idénticas duplicadas.
>
> **API:** `POST /v1/competitor_prices/bulk` (registros JSON) o [`POST /v1/imports/competitor_prices`](https://docs.retailgrid.io/es/api-reference/imports/competitor-prices) (CSV). JSON usa nombres en snake\_case: `item_id`, `observed_at` (obligatorio), `competitor_name` (obligatorio), `regular_price` (obligatorio), `promo_price`, `source_url`, `competitor_sku`, `stock_on_hand`, `barcode`, `status`, `currency`. La API JSON rechaza los campos desconocidos.

## Relacionado

* [Matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md) - validar una entrega
* [Revisar y aprobar coincidencias de competidores](https://docs.retailgrid.io/es/price-monitoring/review-matches.md)
* [API de cargas de matching](https://docs.retailgrid.io/es/api-reference/matching/overview.md)
* [Especificación de datos de Products](https://docs.retailgrid.io/es/data-requirements/products.md)


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