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

# Inicio rápido de la API

> De cero a tu primer producto cargado mediante la API en menos de cinco minutos.

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](https://docs.retailgrid.io/es/api-reference/authentication.md) para generar una clave desde **Settings → Integrations**. Expórtala para el resto de esta página:

```bash theme={null}
export RETAILGRID_API_KEY="rg_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## 2. Verifica que la clave funciona

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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](https://docs.retailgrid.io/es/api-reference/conventions.md) 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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](https://docs.retailgrid.io/es/api-reference/grids/get-rows.md) 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`:

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

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

Después, consulta el estado por sondeo:

```bash theme={null}
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](https://docs.retailgrid.io/es/api-reference/imports-vs-bulk.md): decide qué familia de endpoints encaja con tu pipeline.
* [Convenciones](https://docs.retailgrid.io/es/api-reference/conventions.md): los patrones que sigue cada endpoint.
* [Errores](https://docs.retailgrid.io/es/api-reference/errors.md): cómo son las respuestas 422 y cómo corregirlas.
* [Listar productos](https://docs.retailgrid.io/es/api-reference/products/list.md) y [Obtener filas del Grid](https://docs.retailgrid.io/es/api-reference/grids/get-rows.md): la referencia del lado de lectura.


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