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

# Publicar datos de competidores en Price Radar

> Publica CSV de competidores en bruto o ya emparejados con una clave de API y sigue su progreso y las filas rechazadas.

Usa la API de Matching para refrescar el **Price Radar** de tu organización desde un scraper programado, un pipeline de matching o una integración de un partner. Acepta las mismas exportaciones de competidores en bruto o ya emparejadas que **Update** (actualizar) en la página de [matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md), con la misma validación, los mismos controles de cobertura y el mismo comportamiento de publicación.

Tanto la solicitud de carga como la de progreso usan tu [clave Bearer de la API pública](https://docs.retailgrid.io/es/api-reference/authentication.md). No se requiere una sesión de navegador iniciada.

## Elige la carga correcta

| Tu objetivo | Endpoint |
| :- | :- |
| Publicar datos de competidores en Price Radar y refrescar el matching de competidores | `POST /v1/matching/matched-snapshots` |
| Importar observaciones al conjunto de datos de precios de competidores | [`POST /v1/imports/competitor_prices`](https://docs.retailgrid.io/es/api-reference/imports/competitor-prices) |

El endpoint de Matching acepta **un CSV UTF-8**. La cabecera decide cómo se procesa:

* **`item_id` está presente:** el archivo se trata como ya emparejado y se publica contra tu catálogo.
* **`item_id` está ausente:** Price Radar empareja la exportación de competidores en bruto con tu catálogo antes de la publicación.
* Un archivo en bruto también debe omitir las columnas de enlace `external_match_id`, `match_relation`, `match_method` y `match_confidence`. Un archivo que contenga cualquiera de esas columnas sin `item_id` se rechaza.

El nombre `matched-snapshots` cubre ambos tipos de archivo; no hay un endpoint separado para cargas en bruto ni un parámetro de tipo de carga. Usa el mismo formato de exportación que subirías en la página de matching de competidores. La cabecera del CSV debe caber en 64 KiB.

## Subir un archivo

```bash theme={null}
curl -X POST "https://clientapi.retailgrid.io/v1/matching/matched-snapshots" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -F "file=@competitor-export.csv" \
  -F "coverage=partial" \
  -F "covered_competitors=Shop A,Shop B" \
  -F "allow_large_removal=false"
```

La **solicitud multipart completa debe tener como máximo 25 MiB** (26.214.400 bytes), incluidos los campos del formulario y la sobrecarga multipart. Mantén el archivo por debajo de ese total. Deja que `curl` establezca el `Content-Type` multipart y el boundary.

| Campo del formulario | Obligatorio | Valor por defecto | Significado |
| :- | :- | :- | :- |
| `file` | Sí | - | Un CSV de competidores en bruto o ya emparejado. |
| `coverage` | No | `partial` | `partial` o `full`; controla qué coincidencias existentes puede retirar la entrega. |
| `covered_competitors` | No | Vacío | Nombres de competidores separados por comas, hasta 500 nombres. Se usa para la cobertura parcial. |
| `allow_large_removal` | No | `false` | Confirmación booleana para permitir una entrega que active la protección contra eliminaciones grandes. |

Con cobertura **partial** (parcial), los precios de competidores fuera de `covered_competitors` se mantienen. Una entrega parcial sin competidores cubiertos añade lo que trae y no retira nada. Con cobertura **full** (completa), el archivo declara el conjunto completo y puede retirar las coincidencias que omite; `covered_competitors` no acota esa declaración.

> [!WARNING]
>
> Elige `full` solo cuando el archivo sea una entrega completa. Revisa la exportación antes de establecer `allow_large_removal=true`; esta confirmación permite que una eliminación inusualmente grande siga adelante.

Una carga correcta devuelve **`202 Accepted`** y un identificador de trabajo:

```json theme={null}
{
  "job_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b"
}
```

Esto significa que la publicación se puso en cola. La validación, el matching de los archivos en bruto y la publicación continúan en segundo plano. Guarda el ID del trabajo y síguelo hasta un estado terminal.

## Seguir la publicación

Consulta el endpoint de progreso específico de Matching con la misma clave de API:

```bash theme={null}
curl "https://clientapi.retailgrid.io/v1/matching/jobs/0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b/progress" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"
```

Este endpoint incluye el progreso, los recuentos y las filas rechazadas. Úsalo para estos trabajos en lugar del endpoint genérico `/v1/jobs/{job_id}`.

```json theme={null}
{
  "job_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b",
  "status": "completed",
  "progress": 100,
  "current_step": "Completed",
  "error_message": null,
  "created_at": "2026-10-22T10:00:00Z",
  "started_at": "2026-10-22T10:00:01Z",
  "completed_at": "2026-10-22T10:01:30Z",
  "result_summary": {
    "accepted": 99,
    "rejected": 1,
    "sent": 100,
    "row_errors": [
      {
        "line": 3,
        "code": "no_catalogue_match",
        "message": "No match",
        "item_id": ""
      }
    ]
  }
}
```

`status` es `queued`, `running`, `cancelling`, `completed`, `failed` o `cancelled`. Los tres últimos son terminales. Consulta cada **5-10 segundos** mientras está en ejecución y cada **30-60 segundos** mientras está en cola; el sondeo consume el [presupuesto de uso compartido](https://docs.retailgrid.io/es/api-reference/usage-limits.md) de la organización.

| Campo de respuesta | Significado |
| :- | :- |
| `progress` | Porcentaje de 0 a 100. |
| `current_step` | Una etiqueta de estado pública, como `Processing import` o `Completed`. Usa `status` y el `progress` numérico para seguir el trabajo. |
| `error_message` | Comentario de validación conocido cuando está disponible, o un mensaje genérico para fallos inesperados; puede ser `null`. |
| `created_at`, `started_at`, `completed_at` | Marcas de tiempo en UTC. Las horas de inicio y finalización pueden ser `null`. |
| `result_summary` | Recuentos de resultados y detalles de rechazos cuando están disponibles; puede ser `null` antes de que exista un resultado. |

Dentro de `result_summary`, `accepted` es el número de filas aceptadas, `rejected` es el total de filas rechazadas y `sent` es el total de filas procesadas. Revisa estos recuentos incluso cuando `status` sea `completed`: un archivo publicado puede contener filas rechazadas.

`row_errors` contiene una **muestra de como máximo 200 rechazos**, cada uno con `line`, `code`, `message` e `item_id`. El ID del ítem puede estar vacío, por ejemplo cuando una fila en bruto no tiene coincidencia en el catálogo. No es un informe completo de rechazos. La muestra puede ser más corta que `rejected`, o estar vacía si no se pudieron recuperar los detalles del rechazo; usa `rejected` para el total.

## Gestionar conflictos y fallos

| Estado | Significado | Acción |
| :- | :- | :- |
| `401` | Clave de la API pública ausente o inválida. | Consulta [Autenticación](https://docs.retailgrid.io/es/api-reference/authentication.md). |
| `404` en progreso | Trabajo de matching no encontrado en tu organización, incluido un ID desconocido u otro tipo de trabajo. | Comprueba el ID de trabajo devuelto por esta carga. |
| `409` en carga | Tu organización ya tiene una publicación de matching en curso. | Espera a que termine antes de subir otro archivo. |
| `413` | La carga supera el límite de tamaño de la solicitud. | Reduce la solicitud por debajo de 25 MiB. |
| `422` | El campo de archivo o las opciones multipart no son válidos. | Corrige la solicitud antes de volver a enviarla. |
| `429` | Se alcanzó el límite de uso por clave o de la organización. | Respeta `Retry-After`; consulta [Uso y límites](https://docs.retailgrid.io/es/api-reference/usage-limits.md). |

Los fallos de validación del CSV y de publicación en el sistema de destino pueden ocurrir después del `202`; aparecen como un trabajo terminal `failed`. Revisa `error_message` y los rechazos de filas disponibles, corrige la entrada o espera a que se resuelva un problema temporal del servicio, y luego envía una nueva carga.

La publicación y el progreso se comparten dentro de la organización. Otro usuario con clave de API en la misma organización puede seguir el trabajo; un usuario de otra organización no. Solo se ejecuta una entrega de matching a la vez entre las cargas por API y las cargas desde la aplicación.

## Relacionado

* [Publicar una instantánea de matching](https://docs.retailgrid.io/es/api-reference/matching/publish-snapshot.md)
* [Obtener el progreso de la publicación de matching](https://docs.retailgrid.io/es/api-reference/matching/get-progress.md)
* [Matching de competidores](https://docs.retailgrid.io/es/price-monitoring/competitor-matching.md)
* [Importaciones vs masivo](https://docs.retailgrid.io/es/api-reference/imports-vs-bulk.md)


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