Importación de productos

Sube un CSV con tu catálogo y recibe al instante una operación. El archivo se procesa en segundo plano; consulta la operación hasta que termine y descarga el reporte si hubo filas rechazadas.

Requisitos

• Un token de Admin en ECOMIQ_TOKEN. Ver Inicio rápido.
• Los permisos catalog:create y catalog:update para importar, y operation:read para seguir la operación.

Arma el archivo

Cada fila es una variante. Las filas con el mismo Código producto forman un producto.

Código producto,Producto,SKU,Precio,Opción 1 nombre,Opción 1 valor,Opción 2 nombre,Opción 2 valor,Categoría
POL-001,Polo de algodón,POL-001-AZ-S,79.00,Talla,S,Color,Azul,Ropa > Polos
POL-001,Polo de algodón,POL-001-AZ-M,79.00,Talla,M,Color,Azul,Ropa > Polos
BOT-001,Botella,BOT-001-500,39.00,Capacidad,500 ml,,,Hogar > Botellas

Los encabezados en inglés, como Product code o Price, también sirven.

Cada fila necesita Código producto o ID interno. Si importas como vendedor, Categoría y Marca deben existir.

Para cargar stock, agrega Stock inicial (entero, desde 0) y Ubicación de stock, con el permiso inventory:update. La ubicación debe coincidir con una sola ubicación activa; sin ella, se usa la predeterminada. Una cantidad vacía conserva el stock actual.

Opciones de variante

Cada par lleva el nombre y el valor en la misma fila, así un archivo mezcla productos con Talla y Color y otros con Capacidad.

• La plantilla trae tres pares. Agrega Opción 4 nombre y Opción 4 valor y sigue la numeración si necesitas más.
• Un par con ambas celdas vacías no cambia nada. Al actualizar, cada par completo cambia esa opción y conserva las demás: enviar solo Color = Negro mantiene la Talla.
• La fila se rechaza si un par tiene solo nombre o solo valor, o si un nombre se repite en la fila (sin distinguir mayúsculas).
• Todas las variantes de un producto usan los mismos nombres de opción, en cualquier orden.

Plantilla y exportación

Pide la plantilla con POST /v1/catalog/products/exports y { "format": "xlsx", "template": true }. Trae las columnas obligatorias primero, listas con tus categorías, marcas y perfiles de envío, y ayuda en cada columna.

Sin template, la exportación trae tus productos con ID interno, ID interno variante y una columna ID en {canal} por cada canal con publicaciones. Súbela de nuevo para editar; las columnas de canal son de solo lectura. Ambas son operaciones: al terminar, descarga su resultUrl.

En XLSX, Productos debe ser la primera hoja y los encabezados, la primera fila con datos.

Formatos

Todos admiten hasta 100 000 filas. En JSONL, cada línea es un objeto con los mismos nombres de columna:

{"Código producto":"POL-001","Producto":"Polo de algodón","SKU":"POL-001-AZ-S","Precio":79,"Opción 1 nombre":"Talla","Opción 1 valor":"S"}

Sube el archivo

Envía el archivo en bruto en el cuerpo, con su Content-Type.

curl -X POST https://api.ecomiq.pe/api/v1/catalog/products/imports \
  -H "Authorization: Bearer $ECOMIQ_TOKEN" \
  -H "Content-Type: text/csv" \
  -H "Idempotency-Key: catalogo-2026-10-04" \
  --data-binary @productos.csv

La API revisa los encabezados del archivo y responde 202 con la operación. Location apunta a /v1/operations/7204558912004325401.

{
  "id": "7204558912004325401",
  "status": "pending",
  "resource": "products",
  "format": "csv",
  "createdOn": "2026-10-04T15:30:00Z"
}

Guarda el id para seguir la operación; los productos se crean después.

Idempotency-Key es opcional. Si se perdió la respuesta, reintenta con la misma clave y el mismo archivo: recibes el mismo 202 sin crear otra operación. La clave vale 24 horas.

Si el archivo no se puede leer, la API responde con un error y no crea la operación:

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "Import.InvalidFile": [
      "The import source is missing required headers: sku."
    ]
  },
  "code": "Import.InvalidFile"
}

Sigue la operación

Consulta la operación cada pocos segundos mientras status sea pending o running.

curl https://api.ecomiq.pe/api/v1/operations/7204558912004325401 \
  -H "Authorization: Bearer $ECOMIQ_TOKEN"

En este ejemplo el archivo tenía 4 filas y una no traía Código producto:

{
  "id": "7204558912004325401",
  "type": "import",
  "resource": "products",
  "format": "csv",
  "status": "completed",
  "fileName": "product-import-errors.csv",
  "resultUrl": null,
  "errorsUrl": "https://…/product-import-errors.csv?X-Amz-Expires=300&X-Amz-Signature=…",
  "error": null,
  "totalRows": 4,
  "processedRows": 4,
  "succeededRows": 3,
  "failedRows": 1,
  "startedOn": "2026-10-04T15:30:02Z",
  "completedOn": "2026-10-04T15:30:05Z",
  "createdOn": "2026-10-04T15:30:00Z"
}

En lugar de consultar en bucle, puedes recibir el webhook operation.finished, que trae el id y los contadores. Para cancelar, usa POST /v1/operations/{id}/cancel.

Revisa las filas rechazadas

Si failedRows es mayor que cero, errorsUrl trae un CSV con cada fila rechazada. Es un enlace firmado que vence a los 5 minutos y se descarga sin token; vuelve a pedir la operación para obtener uno nuevo.

curl -o errores.csv "$ERRORS_URL"

sheet,row,column,code,message
,5,,Products.ImportExternalProductIdRequired,Source row 5 requires product_id or product_code.

Corrige esas filas y súbelas en un archivo nuevo.

Siguientes pasos

• Para hasta 100 productos en JSON, usa POST /v1/catalog/products/batch: responde 200 con el resultado de cada fila, sin operación.
• Variantes y precios para ajustar precios después de importar.
• Inventario para cargar el stock.