Importar y Exportar desde Excel

Cachicamo permite cargar y descargar información masiva en Excel para dos catálogos distintos, cada uno con su propio formato de columnas:

• Productos: Importar y Exportar desde Excel — exportar tu catálogo, preparar el archivo, tipos de producto, atributos, precios, actualización de productos existentes y solución de problemas.
• Clientes: Importar y Exportar desde Excel — exportar tu directorio de clientes y proveedores, preparar el archivo, campos personalizados, actualización de contactos existentes y solución de problemas.

Importación asíncrona (para integraciones por API)

Si importas por la API en vez de por el panel, la importación se procesa en segundo plano: la petición para importar responde de inmediato con un identificador de trabajo (uuid) que usas para consultar el avance y, al final, el resultado. Así, un archivo grande no agota el tiempo de espera de la conexión.

Endpoints:

Verbo y ruta	Para qué sirve
POST /products/bulk/xlsx	Envía el archivo Excel de productos y encola la importación. Responde 202 Accepted con el trabajo recién creado, en estado PROCESSING
GET /products/bulk/xlsx/uuid/{uuid}	Consulta el avance o el resultado de una importación de productos por su uuid. Responde 200 OK con el trabajo, o 404 Not Found si ese uuid no existe o no es tuyo
GET /products/bulk/xlsx/current	Consulta la importación de productos más reciente de tu tienda, esté corriendo o ya terminada. Responde 200 OK, o 404 Not Found si nunca importaste
POST /inventories/simple/import/xlsx	Envía el archivo Excel de inventario y encola la importación. Responde 202 Accepted con el trabajo recién creado, en estado PROCESSING
GET /inventories/simple/import/xlsx/uuid/{uuid}	Consulta el avance o el resultado de una importación de inventario por su uuid. Responde 200 OK, o 404 Not Found si ese uuid no existe o no es tuyo
GET /inventories/simple/import/xlsx/current	Consulta la importación de inventario más reciente de tu tienda, esté corriendo o ya terminada. Responde 200 OK, o 404 Not Found si nunca importaste

Ambos POST responden además 400 Bad Request si el archivo no se puede leer o excede tu límite de filas, 409 Conflict si ya tienes una importación corriendo, y 503 Service Unavailable si el sistema no puede aceptar tu importación en ese momento.

Cómo funciona el flujo:

1. Envías el archivo Excel al endpoint de importación de productos o de inventario.
2. Recibes de inmediato, con 202 Accepted, el trabajo con estado PROCESSING y su uuid.
3. Con ese uuid consultas el avance cuando quieras. Mientras el trabajo corre, la respuesta trae el estado PROCESSING y el porcentaje procesado.
4. Cuando el trabajo termina, la misma consulta devuelve el estado COMPLETED (o FAILED si algo impidió terminarlo) junto con el resultado: productos creados, actualizados y errores por fila.
5. Si no guardaste el uuid o quieres saber en qué quedó tu última importación, usa el endpoint current, que trae el trabajo más reciente de tu tienda, esté corriendo o ya terminado.

Datos que trae la consulta de estado:

Campo	Qué indica
uuid	Identificador del trabajo, el mismo que recibiste al iniciar la importación
kind	Si es una importación de productos (PRODUCTS) o de inventario (INVENTORY)
status	PROCESSING mientras corre, COMPLETED si terminó bien, FAILED si falló
total_rows / processed_rows	Filas totales y filas ya procesadas
percentage	Porcentaje de avance, útil para mostrar una barra de progreso
started_at / finished_at	Cuándo arrancó y cuándo terminó (este último vacío mientras el trabajo corre)
result	El resumen de la importación: productos creados, actualizados y errores por fila. Sólo viene lleno cuando status es COMPLETED
error_message	El motivo del fallo, sólo si status es FAILED

Reglas importantes:

• No puedes tener dos importaciones corriendo a la vez. Si ya tienes una en curso —sea de productos o de inventario— e intentas iniciar otra, el sistema la rechaza con 409 Conflict hasta que la primera termine.
• El sistema puede estar ocupado. En momentos de mucha carga, puede responder 503 Service Unavailable y no aceptar tu importación en ese momento; espera unos minutos y vuelve a intentarlo.
• El resultado se conserva 2 horas. Pasado ese tiempo desde que el trabajo terminó, deja de estar disponible y la consulta por su uuid responde 404 Not Found.

---

Relacionado: Productos: Importar y Exportar desde Excel · Clientes: Importar y Exportar desde Excel · Token de API