Skip to main content
POST
/
api
/
productos
/
leer-excel
Importar Productos desde Excel
curl --request POST \
  --url https://api.example.com/api/productos/leer-excel \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '{}'
{
  "422": {},
  "500": {},
  "success": true,
  "data": [
    {
      "codigoProd": "<string>",
      "producto": "<string>",
      "descripcicon": "<string>",
      "categoria": "<string>",
      "unidad": "<string>",
      "moneda": "<string>",
      "costo": 123,
      "cantidad": 123,
      "precio_unidad": 123,
      "precio_mayor": 123,
      "precio_menor": 123,
      "duplicado": true
    }
  ],
  "total": 123,
  "warnings": [
    {
      "tipo": "<string>",
      "mensaje": "<string>"
    }
  ],
  "formato_detectado": "<string>"
}
Lee y valida un archivo Excel con productos, detectando automáticamente el formato (plantilla propia o formato del cliente). Devuelve una lista normalizada lista para importar.

​
Flujo de Importación

  1. Leer Excel: POST /api/productos/leer-excel (esta página)
  2. Revisar/Editar la lista devuelta en el frontend
  3. Importar: POST /api/productos/importar-lista

​
Autenticación

Requiere token Bearer y permiso productos.create.

​
Headers

​
Authorization
string
required
Token de autenticación Bearer
​
Content-Type
string
required
multipart/form-data
​
X-Empresa-Activa
integer
ID de la empresa activa (opcional)

​
Body Parameters

​
archivo
file
required
Archivo Excel (.xlsx, .xls, .csv) con los productos. Máximo 10 MB.

​
Formatos Soportados

El sistema detecta automáticamente dos formatos:

​
Formato Propio (Plantilla del Sistema)

Descargar plantilla: GET /api/productos/plantilla-excel Columnas esperadas (orden flexible, detecta por nombre):
  • Código: Código interno del producto
  • Producto: Nombre del producto (requerido)
  • Detalle: Descripción adicional
  • Categoría: Nombre de la categoría
  • Unidad: Unidad de medida
  • Moneda: PEN/USD/Soles/Dólares
  • Costo: Costo de adquisición
  • Stock: Cantidad en inventario
  • Precio Vta: Precio de venta unitario
  • Precio Distribuidor: Precio mayorista (opcional)
  • Precio Mayorista: Precio minorista (opcional)

​
Formato Cliente (Externo)

Detectado por columna CODIGOITEM. Columnas:
  • CODIGOITEM: Código del producto
  • DESCRIPCIONITEM: Nombre del producto
  • MARCAITEM: Categoría/marca
  • DESCRIPCIONALMACEN: Nombre del almacén (se valida contra empresa activa)
  • MONEDA: Soles/Dólares
  • COSTOPROMEDIO: Costo unitario
  • STOCK: Cantidad disponible
  • VALORTOTAL: Precio de venta
  • [columna con UNIDAD]: Unidad de medida (opcional)

​
Validaciones y Procesamiento

Al leer el archivo:
  1. Detecta el formato (propio o cliente) analizando los encabezados
  2. Omite productos con stock 0 automáticamente
  3. Normaliza moneda: Mapea “Soles”/“Sol”/“S/” → PEN, “Dólares”/”$” → USD
  4. Detecta códigos duplicados en el Excel y los marca
  5. Valida empresa (solo formato cliente): Compara DESCRIPCIONALMACEN con empresa activa
  6. Detecta categorías nuevas que se crearán automáticamente
  7. Valida unidades: Si faltan, se asigna “UNIDAD (NIU)” por defecto

​
Respuesta Exitosa

​
success
boolean
true si el archivo se leyó correctamente
​
data
array
Lista normalizada de productos listos para importar
​
total
integer
Total de productos leídos (excluyendo los omitidos por stock 0)
​
warnings
array
Advertencias y notificaciones importantes
​
formato_detectado
string
Formato detectado: cliente o propio

​
Ejemplo de Respuesta

{
  "success": true,
  "data": [
    {
      "codigoProd": "LAP-001",
      "producto": "Laptop HP ProBook 450 G9",
      "descripcicon": "Intel Core i7, 16GB RAM",
      "categoria": "LAPTOPS",
      "unidad": "UNIDAD",
      "moneda": "PEN",
      "costo": 2800.00,
      "cantidad": 15,
      "precio_unidad": 3540.00,
      "precio_mayor": 3400.00,
      "precio_menor": 3500.00,
      "duplicado": false
    },
    {
      "codigoProd": "MOU-055",
      "producto": "Mouse Logitech M720",
      "descripcicon": "",
      "categoria": "PERIFÉRICOS",
      "unidad": "UNIDAD",
      "moneda": "PEN",
      "costo": 85.00,
      "cantidad": 50,
      "precio_unidad": 118.00,
      "precio_mayor": 110.00,
      "precio_menor": 0,
      "duplicado": false
    }
  ],
  "total": 2,
  "warnings": [
    {
      "tipo": "categorias",
      "mensaje": "Se crearán 2 categoría(s) nueva(s) automáticamente: LAPTOPS, PERIFÉRICOS."
    },
    {
      "tipo": "stock_cero",
      "mensaje": "12 producto(s) omitido(s) porque tienen stock 0."
    }
  ],
  "formato_detectado": "propio"
}

​
Códigos de Error

​
422
error
Errores de validación:
  • Archivo no válido (formato no soportado)
  • Archivo vacío
  • Formato no reconocido
  • No se encontraron productos con stock
​
500
error
Error al leer el archivo Excel

​
Siguientes Pasos

Una vez leído el Excel:
  1. Revisar los productos en el frontend:
    • Editar códigos duplicados (marcados con duplicado: true)
    • Ajustar precios o cantidades
    • Modificar categorías o unidades
  2. Importar la lista: 
    POST /api/productos/importar-lista
{
  "almacen": "1",
  "lista": [...productos editados...]
}

​
Descargar Plantilla

Para facilitar la importación, puedes descargar la plantilla oficial: 
GET /api/productos/plantilla-excel
Devuelve un archivo Excel con los encabezados correctos y filas de ejemplo.

​
Notas de Implementación

  • El sistema omite automáticamente:
    • Filas completamente vacías
    • Filas de ejemplo (ej: “Nombre del producto”)
    • Productos con stock 0 o cantidad vacía
  • Los encabezados NO son case-sensitive ni sensibles a tildes
  • El orden de las columnas es flexible (se detectan por nombre)
  • Las categorías y unidades que no existen se crean automáticamente en el paso de importación
  • Los códigos duplicados en el Excel se marcan pero NO impiden la lectura (se manejan en la UI)

Build docs developers (and LLMs) love

Get started for freeTalk to us