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

# Importaciones frente a bulk

> Cómo elegir entre las importaciones CSV asíncronas y los endpoints JSON bulk síncronos.

Para los conjuntos de datos modelados, la API pública ofrece dos formas de cargar muchos registros a la vez. Elegir la correcta mantiene tu integración simple y tu latencia baja.

Para publicar exportaciones de competidores en bruto o ya emparejadas en Price Radar, usa las [cargas de matching](https://docs.retailgrid.io/es/api-reference/matching/overview.md). Ese flujo actualiza el matching de competidores y tiene sus propios controles de cobertura y su propio endpoint de progreso.

## Comparativa

| | `POST /v1/imports/*` | `POST /v1/<entity>/bulk` |
| - | - | - |
| Transporte | CSV multipart | JSON |
| Modo | **Asíncrono**: devuelve un `job_id` | **Síncrono**: devuelve los resultados en la respuesta |
| Tamaño típico | De cientos de miles a millones de filas | De cientos a unos pocos miles de filas |
| Informe de errores por fila | Cuando el trabajo (job) termina | De inmediato, en `BulkResponse.results` |
| Semántica de reintento | Reintenta la carga; corrige el CSV y vuelve a enviarlo si el trabajo falla | Idempotente por elemento |
| Huella en el límite de uso | Una solicitud por archivo | Una solicitud por lote |

## Usa `imports/*` cuando...

* Estás haciendo una **actualización completa del catálogo** desde tu ERP o PIM.
* Los datos ya están en un CSV (o tu pipeline puede producir uno a bajo costo).
* La latencia de reloj no importa: puedes consultar el estado periódicamente.
* Quieres una sobrecarga mínima de solicitudes por fila.

Endpoints de esta familia:

* [`POST /v1/imports/products`](https://docs.retailgrid.io/es/api-reference/imports/products)
* [`POST /v1/imports/transactions`](https://docs.retailgrid.io/es/api-reference/imports/transactions)
* [`POST /v1/imports/competitor_prices`](https://docs.retailgrid.io/es/api-reference/imports/competitor-prices)
* [`POST /v1/imports/product_store`](https://docs.retailgrid.io/es/api-reference/imports/product-store)

## Usa `/bulk` cuando...

* Estás sincronizando **deltas** desde tu sistema de origen con una programación basada en eventos.
* Quieres un único viaje de ida y vuelta y un resultado inmediato por fila.
* Puedes dar forma a la carga útil como JSON (los registros no provienen de forma natural de un archivo).
* El tamaño del lote está entre **cientos y pocos miles**.

Endpoints de esta familia:

* [`POST /v1/products/bulk`](https://docs.retailgrid.io/es/api-reference/products/bulk-upsert)
* [`POST /v1/product_store/bulk`](https://docs.retailgrid.io/es/api-reference/product-store/bulk-upsert)
* [`POST /v1/transactions/bulk`](https://docs.retailgrid.io/es/api-reference/transactions/bulk-upsert)
* [`POST /v1/competitor_prices/bulk`](https://docs.retailgrid.io/es/api-reference/competitor-prices/bulk-upsert)

## Usa el registro individual `POST /v1/<entity>/{entity_id}` cuando...

* Estás reaccionando a un **cambio individual** en tu sistema de origen (un producto actualizado, una transacción registrada).
* Quieres una semántica de estado fuerte por llamada (`201` frente a `422` directamente).
* Necesitas el cuerpo completo de la respuesta para la fila que acabas de escribir.

## Un patrón pragmático

La mayoría de las integraciones en producción acaban usando dos de las tres:

1. `imports/products` de catálogo completo a **diario** para absorber todos los cambios del origen.
2. `products/bulk` o `POST /v1/products/{entity_id}` **basados en eventos** para actualizaciones de baja latencia entre sincronizaciones completas.

Esto mantiene Retailgrid eventualmente consistente sobre una infraestructura económica, con una vía rápida para la pequeña porción de cambios que realmente la necesita.


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