Inicio rápido de la API

Esta guía recorre el flujo completo de entrada y salida: verificar tu clave, crear un producto, hacer un upsert masivo de muchos, leer los datos enriquecidos y consultar el estado de un trabajo (job). Al terminar tendrás comandos curl funcionales y un camino claro para escalar a la sincronización completa del catálogo.

1. Obtén una clave de API

Sigue los pasos de Autenticación para generar una clave desde Settings → Integrations. Expórtala para el resto de esta página:

export RETAILGRID_API_KEY="rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Verifica que la clave funciona

curl https://clientapi.retailgrid.io/v1/auth/verify \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

Un 200 con "ok": true significa que todo está listo.

3. Crea un producto

Elige un id de producto que controles: es el identificador estable que usarás más adelante para actualizar o eliminar este producto. Los UUID valen, pero cualquier cadena funciona.

PRODUCT_ID="11111111-2222-3333-4444-555555555555"

curl -X POST "https://clientapi.retailgrid.io/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "SKU-DEMO-001",
    "product_name": "Demo running shoe",
    "brand": "Acme",
    "manufacturer": "Acme Footwear",
    "product_type": "shoe",
    "status": "active"
  }'

Una respuesta 201 Created devuelve el registro completo del producto, incluido el id interno que asignó Retailgrid.

4. Haz un upsert masivo de muchos productos a la vez

Para más de un puñado de registros, usa /bulk. Acepta hasta unos pocos miles de elementos en una sola solicitud y devuelve resultados por elemento.

curl -X POST "https://clientapi.retailgrid.io/v1/products/bulk" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {"product_id": "SKU-DEMO-002", "product_name": "Demo trail shoe", "brand": "Acme"},
      {"product_id": "SKU-DEMO-003", "product_name": "Demo road shoe",  "brand": "Acme"}
    ]
  }'

La respuesta contiene un BulkItemResult por cada fila de entrada, de modo que los fallos parciales no bloquean el lote completo. Consulta Convenciones para más detalles.

5. Lee lo que has cargado

La API lee además de escribir. Extrae productos enriquecidos (campos canónicos más cualquier columna personalizada añadida en la importación) para ingestarlos en tu ERP o BI:

curl -s "https://clientapi.retailgrid.io/v1/products?updated_after=2026-05-01T00:00:00Z&limit=500" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

El mismo patrón funciona para transacciones:

curl -s "https://clientapi.retailgrid.io/v1/transactions?updated_after=2026-05-01T00:00:00Z&limit=1000" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

Para exportar el contenido completo de las filas de un Grid, incluidas las columnas personalizadas y las columnas de fórmula o calculadas, primero lista tus Grids y luego extrae las filas:

# List grids
curl -s "https://clientapi.retailgrid.io/v1/grids" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

# Pull rows from a grid
curl -s "https://clientapi.retailgrid.io/v1/grids/grd_01HX2K8E4Y/rows?limit=5000" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

Todos los endpoints de lectura admiten paginación por cursor y un filtro updated_after para extracciones incrementales. Consulta Obtener filas del Grid para ver todas las opciones de selección de columnas.

6. Cargas de CSV asíncronas

Para actualizaciones completas del catálogo, usa los endpoints de importación de CSV. Devuelven de inmediato un job_id:

curl -X POST "https://clientapi.retailgrid.io/v1/imports/products" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY" \
  -F "file=@products.csv"

{ "job_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" }

Después, consulta el estado por sondeo:

curl "https://clientapi.retailgrid.io/v1/jobs/0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b" \
  -H "Authorization: Bearer $RETAILGRID_API_KEY"

Cuando "status": "completed", los datos ya están disponibles en tus Grids de Retailgrid.

Siguientes pasos

Importaciones frente a bulk: decide qué familia de endpoints encaja con tu pipeline.
Convenciones: los patrones que sigue cada endpoint.
Errores: cómo son las respuestas 422 y cómo corregirlas.
Listar productos y Obtener filas del Grid: la referencia del lado de lectura.

Descripción general

Autenticación

Importaciones (CSV)

Productos

Producto-tienda

Transacciones

Precios de competidores

Matching

Grids

Trabajos

Precios

auth

imports

internal-import-events

products

transaction exports

transactions

competitor_prices

approved_prices

product_store

jobs

matching

grids

1. Obtén una clave de API

2. Verifica que la clave funciona

3. Crea un producto

4. Haz un upsert masivo de muchos productos a la vez

5. Lee lo que has cargado

6. Cargas de CSV asíncronas

Siguientes pasos

​1. Obtén una clave de API

​2. Verifica que la clave funciona

​3. Crea un producto

​4. Haz un upsert masivo de muchos productos a la vez

​5. Lee lo que has cargado

​6. Cargas de CSV asíncronas

​Siguientes pasos

1. Obtén una clave de API

2. Verifica que la clave funciona

3. Crea un producto

4. Haz un upsert masivo de muchos productos a la vez

5. Lee lo que has cargado

6. Cargas de CSV asíncronas

Siguientes pasos