Productos - Sistema de Facturación Electrónica SUNAT

GET /api/productos

Lista todos los productos de la empresa activa.

Autenticación

Requiere autenticación con token Bearer y permiso productos.view.

Parámetros de Consulta

almacen

string

Filtrar por almacén: 1 (Virtual) o 2 (Real). Default: 1

string

Término de búsqueda (busca en código, nombre, descripción)

solo_con_stock

boolean

Si es true, solo muestra productos con stock > 0. Default: false

Headers Opcionales

X-Empresa-Activa

integer

ID de la empresa a consultar (sobrescribe la empresa del usuario)

Respuesta

success

boolean

Indica si la operación fue exitosa

data

array

Lista de productos

Show Estructura

id_producto

integer

ID único del producto

codigo

string

Código interno del producto

cod_barra

string

Código de barras

nombre

string

Nombre del producto

descripcion

string

Descripción del producto

precio

number

Precio de venta

costo

number

Costo del producto

precio_mayor

number

Precio por mayor

precio_menor

number

Precio por menor

cantidad

integer

Stock actual

stock_minimo

integer

Stock mínimo

stock_maximo

integer

Stock máximo

almacen

string

Almacén: 1 (Virtual) o 2 (Real)

categoria_id

integer

ID de la categoría

unidad_id

integer

ID de la unidad de medida

codsunat

string

Código SUNAT del producto

moneda

string

Moneda: PEN o USD

estado

string

Estado: 1 (Activo), 0 (Inactivo)

imagen

string

Ruta de la imagen del producto

ultima_salida

string

Fecha de última salida

fecha_ultimo_ingreso

string

Fecha de último ingreso

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/productos?almacen=1&search=laptop" \
  -H "Authorization: Bearer {token}"

POST /api/productos

Crea un nuevo producto en ambos almacenes (virtual y real).

Autenticación

Requiere autenticación con token Bearer y permiso productos.create.

Parámetros del Body

codigo

string

required

Código interno del producto (único por empresa)

nombre

string

required

Nombre del producto

descripcion

string

Descripción del producto

cod_barra

string

Código de barras

precio

number

required

Precio de venta (mínimo 0)

costo

number

Costo del producto (mínimo 0)

precio_mayor

number

Precio por mayor

precio_menor

number

Precio por menor

cantidad

integer

Stock inicial (default: 0)

stock_minimo

integer

Stock mínimo para alertas

stock_maximo

integer

Stock máximo

categoria_id

integer

ID de la categoría

unidad_id

integer

ID de la unidad de medida

codsunat

string

Código SUNAT del producto (para facturación electrónica)

moneda

string

Moneda: PEN o USD (default: PEN)

imagen

file

Imagen del producto (formatos: jpeg, png, jpg. Máximo: 2MB)

Proceso Automático

Al crear un producto:

Crea el producto en el almacén 1 (Virtual)
Crea automáticamente un duplicado en el almacén 2 (Real) con el mismo código
Ambos productos comparten el mismo código pero tienen IDs diferentes
Permite gestionar stock virtual y real por separado

Respuesta

success

boolean

Indica si el producto fue creado exitosamente

message

string

Mensaje confirmando la creación en ambos almacenes

data

object

Producto creado (almacén virtual)

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/productos" \
  -H "Authorization: Bearer {token}" \
  -F "codigo=LAP001" \
  -F "nombre=Laptop HP 15" \
  -F "descripcion=Laptop HP Core i5 8GB RAM" \
  -F "precio=2500.00" \
  -F "costo=2000.00" \
  -F "cantidad=10" \
  -F "categoria_id=1" \
  -F "unidad_id=1" \
  -F "moneda=PEN" \
  -F "[email protected]"

GET /api/productos/

Obtiene el detalle de un producto específico.

Autenticación

Requiere autenticación con token Bearer y permiso productos.view.

Parámetros de Ruta

integer

required

ID del producto

Respuesta

success

boolean

Indica si la operación fue exitosa

data

object

Producto con sus relaciones (categoría, unidad)

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/productos/123" \
  -H "Authorization: Bearer {token}"

PUT /api/productos/

Actualiza un producto existente.

Autenticación

Requiere autenticación con token Bearer y permiso productos.edit.

Parámetros de Ruta

integer

required

ID del producto

Parámetros del Body

Los mismos que en POST (todos opcionales).

Sincronización entre Almacenes

Si el producto tiene un duplicado en el otro almacén (mismo código):

Sincroniza: nombre, descripción, precio, costo, categoría, unidad, codsunat
NO sincroniza: stock (cantidad), imagen

Respuesta

success

boolean

Indica si la actualización fue exitosa

message

string

Mensaje confirmando la actualización. Indica si se sincronizó con el otro almacén.

data

object

Producto actualizado

sincronizado

boolean

Indica si se sincronizó con el producto del otro almacén

Ejemplo de Uso

curl -X PUT "https://api.ejemplo.com/api/productos/123" \
  -H "Authorization: Bearer {token}" \
  -F "precio=2600.00" \
  -F "cantidad=15"

DELETE /api/productos/

Elimina un producto.

Autenticación

Requiere autenticación con token Bearer y permiso productos.delete.

Parámetros de Ruta

integer

required

ID del producto

Respuesta

success

boolean

Indica si la eliminación fue exitosa

message

string

Mensaje confirmando la eliminación

Ejemplo de Uso

curl -X DELETE "https://api.ejemplo.com/api/productos/123" \
  -H "Authorization: Bearer {token}"

GET /api/productos/plantilla-excel

Descarga la plantilla Excel para importar productos masivamente.

Autenticación

Requiere autenticación con token Bearer.

Respuesta

Archivo Excel (.xlsx) con el formato requerido para importación.

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/productos/plantilla-excel" \
  -H "Authorization: Bearer {token}" \
  -o plantilla-productos.xlsx

GET /api/productos/descargar-excel

Exporta todos los productos de la empresa a Excel.

Autenticación

Requiere autenticación con token Bearer.

Respuesta

Archivo Excel (.xlsx) con todos los productos.

Ejemplo de Uso

curl -X GET "https://api.ejemplo.com/api/productos/descargar-excel" \
  -H "Authorization: Bearer {token}" \
  -o productos.xlsx

POST /api/productos/leer-excel

Lee un archivo Excel y valida los productos antes de importar.

Autenticación

Requiere autenticación con token Bearer y permiso productos.create.

Parámetros del Body

archivo

file

required

Archivo Excel (.xlsx) con los productos

Respuesta

success

boolean

Indica si la lectura fue exitosa

productos

array

Lista de productos validados del Excel

errores

array

Lista de errores de validación encontrados

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/productos/leer-excel" \
  -H "Authorization: Bearer {token}" \
  -F "[email protected]"

POST /api/productos/importar-lista

Importa masivamente una lista de productos desde Excel.

Autenticación

Requiere autenticación con token Bearer y permiso productos.create.

Parámetros del Body

productos

array

required

Lista de productos validados (obtenida de /leer-excel)

Respuesta

success

boolean

Indica si la importación fue exitosa

importados

integer

Cantidad de productos importados exitosamente

errores

array

Lista de productos que no se pudieron importar

Ejemplo de Uso

curl -X POST "https://api.ejemplo.com/api/productos/importar-lista" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"productos": [...]}'

Códigos de Error

404 Not Found: Producto no encontrado.
422 Unprocessable Entity: Error de validación (código duplicado, datos inválidos).
500 Internal Server Error: Error en el servidor.

Notas Importantes

Doble almacén: Cada producto se crea automáticamente en almacén 1 (Virtual) y almacén 2 (Real).
Código único: El código debe ser único por empresa (no puede repetirse en ningún almacén).
Sincronización: Al actualizar un producto, los datos generales se sincronizan entre almacenes, pero NO el stock.
Stock: Use /api/ventas para descontar stock automáticamente, o gestione movimientos de stock directamente.
Las imágenes se almacenan en storage/app/public/productos/.
El precio incluye IGV si la empresa lo tiene configurado.

Autenticación

Endpoints

Recursos

​GET /api/productos

​Autenticación

​Parámetros de Consulta

​Headers Opcionales

​Respuesta

​Ejemplo de Uso

​POST /api/productos

​Autenticación

​Parámetros del Body

​Proceso Automático

​Respuesta

​Ejemplo de Uso

​GET /api/productos/

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​PUT /api/productos/

​Autenticación

​Parámetros de Ruta

​Parámetros del Body

​Sincronización entre Almacenes

​Respuesta

​Ejemplo de Uso

​DELETE /api/productos/

​Autenticación

​Parámetros de Ruta

​Respuesta

​Ejemplo de Uso

​GET /api/productos/plantilla-excel

​Autenticación

​Respuesta

​Ejemplo de Uso

​GET /api/productos/descargar-excel

​Autenticación

​Respuesta

​Ejemplo de Uso

​POST /api/productos/leer-excel

​Autenticación

​Parámetros del Body

​Respuesta

​Ejemplo de Uso

​POST /api/productos/importar-lista

​Autenticación

​Parámetros del Body

​Respuesta

​Ejemplo de Uso

​Códigos de Error

​Notas Importantes

Build docs developers (and LLMs) love

GET /api/productos

Autenticación

Parámetros de Consulta

Headers Opcionales

Respuesta

Ejemplo de Uso

POST /api/productos

Autenticación

Parámetros del Body

Proceso Automático

Respuesta

Ejemplo de Uso

GET /api/productos/

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

PUT /api/productos/

Autenticación

Parámetros de Ruta

Parámetros del Body

Sincronización entre Almacenes

Respuesta

Ejemplo de Uso

DELETE /api/productos/

Autenticación

Parámetros de Ruta

Respuesta

Ejemplo de Uso

GET /api/productos/plantilla-excel

Autenticación

Respuesta

Ejemplo de Uso

GET /api/productos/descargar-excel

Autenticación

Respuesta

Ejemplo de Uso

POST /api/productos/leer-excel

Autenticación

Parámetros del Body

Respuesta

Ejemplo de Uso

POST /api/productos/importar-lista

Autenticación

Parámetros del Body

Respuesta

Ejemplo de Uso

Códigos de Error

Notas Importantes