Saltar al contenido
Facturador

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ía file.
  • Al editar solo cambian los campos enviados; stock no modifica el inventario (usa ajustes de inventario).
  • Booleanos como 0/1 (form-data no tiene tipos).

Errores:

  • Validación: 422 con {success: false, message: {campo: [mensajes]}}. Ej.: internal_id repetido, precio de venta 0, item_code sin 8 dígitos.
  • Imagen de tipo no permitido: HTTP 200 con success: false.
  • Si el id no existe responde HTTP 500 con success: false y message No query results for model [...] (no 404). (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.