Maxim

Maxim

Última actualización el Oct 8, 2026

Crea un producto junto con sus componentes. El producto aparece en el almacén storage_id y en los almacenes que guardan todos los productos o sus categorías.

v1/products/add.php

Parámetros

Campo Tipo Obligatorio Descripción
name string Sí Nombre
unit string Sí Unidad de medida, un código de Unidades de medida
storage_id int Sí Almacén donde se crean las existencias
sku string No SKU
price float No Precio de venta por unidad. Por defecto 0
batch_size float No Tamaño del lote: la cantidad de producto para la que se indican los componentes. Por defecto 1
stock float No Existencias iniciales en el almacén storage_id. Por defecto 0
minimum float No Existencias mínimas en el almacén storage_id. Por defecto 0
notes string No Notas
categories array No Categorías: objetos con id o name
suppliers array No ID de proveedores de v1/suppliers/get_list
alternative_sku array No SKU alternativos: objetos con sku y label (una etiqueta opcional)
materials array No Materiales en los componentes
products array No Semielaborados en los componentes
resources array No Recursos en los componentes

Una categoría se puede pasar por nombre: si no existe, se crea. Los ID de las categorías existentes los devuelve v1/categories/get_list.

La unicidad del SKU principal y de los alternativos no se comprueba.

Componentes del producto

Los componentes se definen por lote (batch_size unidades) y se envían en los array materials (materiales), products (semielaborados) y resources (recursos).

Líneas materials y products

Campo Tipo Obligatorio Descripción
id int Sí ID del material o del producto
amount_per_batch float Sí Cantidad por lote
unit string Sí Unidad de la línea. Del mismo grupo que la unidad del material o del producto: para un material en «kg» valen «kg» o «g»
loss_percent float No Pérdidas, en porcentaje. Por defecto 0. Se aceptan solo si en los ajustes de la empresa está activada la visualización de pérdidas en los componentes
position int No Posición de la línea en los componentes

position fija el orden de las líneas de componentes en la interfaz de Controlata, común para materials y products. Las líneas sin este campo van al final, en el orden enviado. Controlata renumera las posiciones desde 0, por lo que en Obtener los datos de un producto pueden diferir de las enviadas.

Líneas resources

Cada línea de recurso contiene el id del recurso. Si hacen falta amount_per_batch y unit depende del tipo de recurso (consulta Crear un recurso):

Tipo de recurso amount_per_batch unit
Tarifa fija Cantidad por lote, p. ej. horas de trabajo Necesario
Tarifa fija, el precio se indica en los componentes del producto Un importe por lote No necesario
Porcentaje No se envía: se toma del recurso No necesario
Porcentaje, se indica en los componentes del producto El porcentaje No necesario
Amortización Cantidad por lote, p. ej. horas de uso del equipo Necesario

Ejemplo de solicitud

Una mesa: 10 por lote, cada lote usa 0.5 m3 de tablero con un 5 % de pérdidas, 400 tornillos, 40 patas (un semielaborado) y 30 horas de trabajo del carpintero. Los gastos generales son un porcentaje fijado en el propio recurso, así que basta con su id.

{
    "name": "Mesa de comedor",
    "sku": "P100",
    "unit": "ud",
    "price": 45000,
    "batch_size": 10,
    "storage_id": 3999,
    "stock": 5,
    "minimum": 2,
    "categories": [{ "id": 21 }],
    "suppliers": [{ "id": 46 }],
    "alternative_sku": [
        {
            "label": "Shopify",
            "sku": "SH-P100"
        }
    ],
    "materials": [
        {
            "id": 2051,
            "amount_per_batch": 0.5,
            "unit": "m3",
            "loss_percent": 5
        },
        {
            "id": 2060,
            "amount_per_batch": 400,
            "unit": "ud"
        }
    ],
    "products": [
        {
            "id": 312,
            "amount_per_batch": 40,
            "unit": "ud"
        }
    ],
    "resources": [
        {
            "id": 57,
            "amount_per_batch": 30,
            "unit": "h"
        },
        {
            "id": 58
        }
    ]
}

Ejemplo de respuesta

{
    "success": true,
    "product_id": 3120
}

Errores

Error Motivo
No name in input Falta un campo obligatorio (en lugar de name, el nombre del campo)
Name must not be empty Nombre vacío
Name must be a string El nombre no se envió como cadena, p. ej. como array
Unit not set Se envió una unidad de medida vacía
Unit not found Unidad de medida desconocida, o una unidad solo para recursos
Storage ID is not set storage_id es 0 o está vacío
Storage ID not found Almacén no encontrado o eliminado
Batch size must be greater than 0 El tamaño del lote es 0 o menor
Invalid price value. Must be a number El valor no es un número, p. ej. "12,5" (igual para batch_size, stock y minimum)
Category 12 not found Categoría no encontrada
Supplier not found or access denied Proveedor no encontrado o eliminado
Alternative_sku is not an array alternative_sku no se envió como array
SKU must be from 1 to 50 characters for alternative_sku 0 El SKU alternativo está vacío o supera los 50 caracteres (al final, el número de línea desde 0)
Label must not exceed 100 characters for alternative_sku 0 La etiqueta del SKU alternativo supera los 100 caracteres

Errores en las líneas de componentes

En el texto del error, en lugar de 2051 aparece el ID del elemento, y en lugar de 0 el número de línea en el array (desde 0).

Error Motivo
Materials is not an array materials no se envió como array (igual para products y resources)
Line 0 of materials must be an object La línea no es un objeto (igual para products y resources)
No id for material 0 Falta el id del material o no es un número (igual para product)
Material 2051 not found Material no encontrado o eliminado
Product 2051 not found Producto no encontrado o eliminado
Product cannot be a component of itself El producto se añadió a sus propios componentes
Amount per batch must be greater than 0 for material 2051 La cantidad falta, no es un número, o es 0 tras redondear a 3 decimales (igual para product y resource)
Unit not found for material 2051. Use a unit of the same group as the material unit La unidad falta, es desconocida o de otro grupo (igual para product)
Loss percent must be from 0 to 100 for material 2051 Las pérdidas son menores que 0, mayores que 100 o no son un número (igual para product)
Loss percent is disabled in company settings for material 2051 Se enviaron pérdidas, pero en los ajustes de la empresa está desactivada su visualización en los componentes (igual para product)
Resource for line 0 not found Recurso no encontrado o eliminado
Percent must not exceed 100 for resource 2051 El porcentaje en los componentes supera 100
Unit not found for resource 2051. Use a unit of the same group as the resource unit La unidad del recurso falta, es desconocida o de otro grupo