Crear o editar producto (con imagen)
POST /api/items/save
Autenticación: Bearer del usuario del tenant (Authorization: Bearer <api_token>).
Crea un producto o, si envías id, lo edita. Se envía como multipart/form-data (no JSON) para poder adjuntar la imagen en file. Deja Content-Type sin fijar para que se envíe el boundary.
Quién puede usarlo: cualquier usuario autenticado (administrador o vendedor).
Formato de respuesta: heredado {success, message?, data?} sin paginación. Ante reglas de negocio puede responder HTTP 200 con success: false: revisa siempre success.
| Campo | Tipo | Obligatorio | Descripción / valores permitidos |
|---|---|---|---|
id |
integer | No | Id del producto a editar. Sin id se crea uno nuevo. |
description |
string | Sí | Nombre del producto (máx. 600). |
name / second_name |
string | No | Descripción y nombre secundario (máx. 600). |
internal_id |
string | No | Código interno. Único. Si se omite al crear, se genera automáticamente. |
barcode |
string | No | Código de barras. |
item_code |
string | No | Código de producto SUNAT: 8 dígitos. |
model |
string | No | Modelo (máx. 100). |
unit_type_id |
string | Sí | Unidad de medida (NIU unidad, ZZ servicio, KGM...; ver Unidades de medida). |
currency_type_id |
string | Sí | PEN o USD. |
sale_unit_price |
numeric | Sí | Precio de venta, mayor que 0. |
purchase_unit_price |
numeric | Sí | Precio de compra. |
sale_affectation_igv_type_id / purchase_affectation_igv_type_id |
string | Sí | Afectación IGV (catálogo SUNAT 07): 10 gravado, 20 exonerado, 30 inafecto... |
has_igv / purchase_has_igv |
boolean (0/1) | No | 1 si el precio de venta / compra incluye IGV. |
category_id / brand_id |
integer | No | Categoría y marca (sección Categorías y marcas). |
stock |
numeric | No | Solo al crear: stock inicial en el almacén de warehouse_id (o en el del establecimiento del usuario). No aplica a servicios (ZZ). |
warehouse_id |
integer | No | Solo al crear: almacén del stock inicial. |
stock_min |
numeric | No | Stock mínimo para alertas. |
calculate_quantity |
boolean (0/1) | No | Calcular cantidad a partir del monto en la venta. |
has_isc / system_isc_type_id / percentage_isc |
0/1 / string / numeric | No | ISC en venta: si has_isc = 1, el tipo y el porcentaje son obligatorios. |
purchase_has_isc / purchase_system_isc_type_id / purchase_percentage_isc |
0/1 / string / numeric | No | ISC en compra, misma regla. |
favorite |
boolean (0/1) | No | Favorito en el punto de venta. |
active |
boolean (0/1) | No | Activo. |
file |
archivo | No | Imagen jpg, jpeg, png, gif, svg o webp. Se guardan 3 tamaños; al editar reemplaza la imagen anterior. |
Reglas:
- Al crear: tipo de producto
01, impuesto a bolsas según la configuración de la empresa e imagen por defecto si no se envíafile. - Al editar solo cambian los campos enviados;
stockno modifica el inventario (usa ajustes de inventario). - Booleanos como
0/1(form-data no tiene tipos).
Errores:
- Validación:
422con{success: false, message: {campo: [mensajes]}}. Ej.:internal_idrepetido, precio de venta 0,item_codesin 8 dígitos. - Imagen de tipo no permitido: HTTP 200 con
success: false. - Si el id no existe responde HTTP 500 con
success: falseymessageNo query results for model [...](no404). (al editar)
Cuerpo
Content-Type: multipart/form-data
| Campo | Tipo | Obligatorio | Ejemplo | Descripción |
|---|---|---|---|---|
id |
texto | no | Solo para editar: id del producto. Vacío = crear. | |
description |
texto | sí | GASEOSA COCA COLA 500ML |
Nombre del producto (obligatorio). |
name |
texto | sí | Gaseosa personal |
Descripción. |
second_name |
texto | no | Nombre secundario. | |
internal_id |
texto | sí | P0001 |
Código interno único. |
barcode |
texto | sí | 7751271001234 |
Código de barras. |
item_code |
texto | sí | 50202301 |
Código SUNAT (8 dígitos). |
model |
texto | no | Modelo. | |
unit_type_id |
texto | sí | NIU |
Unidad de medida (obligatorio). |
currency_type_id |
texto | sí | PEN |
Moneda (obligatorio). |
sale_unit_price |
texto | sí | 2.50 |
Precio de venta > 0 (obligatorio). |
purchase_unit_price |
texto | sí | 1.80 |
Precio de compra (obligatorio). |
sale_affectation_igv_type_id |
texto | sí | 10 |
Afectación IGV venta (obligatorio). |
purchase_affectation_igv_type_id |
texto | sí | 10 |
Afectación IGV compra (obligatorio). |
has_igv |
texto | sí | 1 |
Precio de venta incluye IGV. |
purchase_has_igv |
texto | sí | 1 |
Precio de compra incluye IGV. |
category_id |
texto | sí | 1 |
Categoría. |
brand_id |
texto | sí | 1 |
Marca. |
stock |
texto | sí | 120 |
Solo al crear: stock inicial. |
warehouse_id |
texto | sí | 1 |
Solo al crear: almacén del stock inicial. |
stock_min |
texto | sí | 10 |
Stock mínimo. |
calculate_quantity |
texto | sí | 0 |
Calcular cantidad por monto. |
has_isc |
texto | sí | 0 |
Tiene ISC. |
system_isc_type_id |
texto | no | Tipo de ISC (si has_isc = 1). | |
percentage_isc |
texto | sí | 0 |
Porcentaje ISC. |
purchase_has_isc |
texto | no | 0 |
ISC en compra. |
purchase_system_isc_type_id |
texto | no | Tipo de ISC en compra. | |
purchase_percentage_isc |
texto | no | 0 |
Porcentaje ISC en compra. |
favorite |
texto | sí | 0 |
Favorito. |
active |
texto | sí | 1 |
Activo. |
file |
archivo | sí | Imagen del producto (opcional). |
Respuestas
200 — Registrado
{
"success": true,
"message": "Producto registrado con éxito",
"data": {
"id": 31,
"item_id": 31,
"name": "Gaseosa personal",
"full_description": "P0001 - GASEOSA COCA COLA 500ML",
"description": "GASEOSA COCA COLA 500ML",
"currency_type_id": "PEN",
"internal_id": "P0001",
"item_code": "50202301",
"barcode": "7751271001234",
"currency_type_symbol": "S/",
"sale_unit_price": "2.50",
"purchase_unit_price": "1.80",
"unit_type_id": "NIU",
"sale_affectation_igv_type_id": "10",
"purchase_affectation_igv_type_id": "10",
"calculate_quantity": false,
"has_igv": true,
"is_set": false,
"category_id": 7,
"brand_id": 4,
"image": "gaseosa-coca-cola-500ml-31.jpg",
"image_medium": "gaseosa-coca-cola-500ml-31-medium.jpg",
"image_small": "gaseosa-coca-cola-500ml-31-small.jpg",
"image_url": "https://empresa.dominio/storage/uploads/items/gaseosa-coca-cola-500ml-31.jpg",
"favorite": false,
"aux_quantity": 1
}
}
422 — Validación
{
"success": false,
"message": {
"sale_unit_price": [
"El precio unitario de venta debe ser mayor que 0."
],
"internal_id": [
"El campo código interno ya ha sido registrado."
]
}
}
Pruébalo
Prueba este endpoint con tu empresa y tu token: elige la URL en Servers, pega el token en Authorize y haz clic en Try it out.