Identificadores
En la API aparecen dos tipos de ids:item_id/sku/competitor_name/ etc. - tu identificador de negocio estable. Lo proporcionas tú. Úsalo para los upserts.item_ides la clave única a nivel de SKU para productos y transacciones;product_ides un código opcional a nivel de producto que agrupa ítems relacionados.id/entity_id- el id interno de fila de Retailgrid, devuelto en las respuestas. Úsalo en los parámetros de ruta al modificar o eliminar (PATCH /v1/products/{entity_id}).
entity_id es un UUID para productos, variantes de producto y transacciones. Para los precios de competidores es un entero - el único lugar de la API donde esto varía.
Endpoints masivos
Cada entidad tiene un endpointPOST /v1/<entity>/bulk que acepta un array items y devuelve resultados por ítem.
Solicitud:
BulkResponse):
BulkItemResult.ok antes de dar el proceso por terminado.
Tamaño de lote recomendado: de 500 a 2.000 ítems por solicitud, según el ancho de las filas. Los payloads más grandes funcionan, pero aumentan la latencia y la probabilidad de un reintento a nivel de transporte.
Trabajos asíncronos
Los endpointsPOST /v1/imports/* aceptan un CSV multipart y devuelven de inmediato un JobHandle:
GET /v1/jobs/{job_id}:
status es uno de queued, running, completed, failed. Una cadencia de sondeo razonable es cada 5-10 segundos para trabajos activos y cada 30-60 segundos para trabajos en cola.
Síncrono vs asíncrono
Consulta Importaciones vs masivo para ver el árbol de decisión completo.
Decimales
Los importes, cantidades y tasas se devuelven como cadenas de texto, no como números de punto flotante. Esto evita las sorpresas de redondeo que tendrías con IEEE-754:Marcas de tiempo
Todas las marcas de tiempo están en ISO 8601 en UTC:YYYY-MM-DD. La API no realiza conversión de zona horaria - envía UTC, recibe UTC.
Idempotencia
POST /v1/<entity>/{entity_id} es un upsert con clave en el entity_id de la ruta, lo que hace que sea seguro reintentarlo. PATCH también es idempotente a nivel de campo. DELETE es idempotente (eliminar una fila ya eliminada devuelve 204).
Los endpoints /bulk son idempotentes por ítem, con clave en el identificador de negocio dentro de cada ítem (item_id, sku, etc.).
Hoy no existe la cabecera Idempotency-Key - la añadiremos antes de recomendar esta API para flujos cercanos a pagos.
Paginación
Los endpoints de listado (productos, transacciones, Grids, trabajos, precios aprobados) usan paginación basada en cursor. Pasalimit para definir el tamaño de página y, para obtener la siguiente página, pasa el valor cursor devuelto como next_cursor en la respuesta anterior. Un next_cursor con valor null significa que no hay más filas.
Límites de uso
El uso se mide por organización - el presupuesto se comparte entre todas las claves de API, todos los usuarios y el conector MCP, así que añadir más claves o repartir las llamadas entre endpoints no eleva tu límite. Cuando el presupuesto de uso de la organización se agota, la API rechaza la solicitud antes de realizar cualquier procesamiento costoso y devuelve429 Too Many Requests, una cabecera Retry-After y un cuerpo JSON que indica el límite, el margen restante y cuándo se restablece (consulta Errores).
También se aplica un límite de uso independiente por clave, que igualmente devuelve 429 con una cabecera Retry-After. Los límites actuales son lo bastante amplios como para que los pipelines de sincronización bien diseñados no los alcancen; publicaremos aquí las cifras concretas cuando tengamos datos de producción estables. La única regla que importa para el diseño del pipeline: ante un 429, espera y respeta Retry-After en lugar de reintentar de inmediato.