Maxim

Maxim

Última actualización el Oct 21, 2026

Crea una compra. El estado de la compra viene del ajuste Estado por defecto de las nuevas compras en los ajustes del sistema, y el estado determina si los materiales y productos se suman a las existencias de inmediato (consulta Cambiar el estado de la compra).

v1/purchases/add.php

Parámetros

Campo Tipo Obligatorio Descripción
supplier_id int supplier_id o supplier_name ID de un proveedor existente
supplier_name string supplier_id o supplier_name Nombre del proveedor. Si no existe, se crea a partir de los campos con prefijo supplier_
materials array materials o products Líneas de materiales
products array materials o products Líneas de productos
date_placed string No Fecha del pedido de compra. Por defecto hoy
date_received string No Fecha de recepción
materials_storage_id int No Almacén de materiales. Por defecto el de los ajustes
products_storage_id int No Almacén de productos. Por defecto el de los ajustes
delivery_price float No Coste de envío. Por defecto 0
discount float No Descuento. Por defecto 0
notes string No Notas

Líneas de la compra

Las líneas de la compra se envían en dos array: materials para los materiales y products para los productos. Hace falta al menos una línea en uno de los array.

Campo Tipo Obligatorio Descripción
id int id o sku ID del material o del producto
sku string id o sku SKU. Un producto también se busca por sus SKU alternativos
amount float Sí Cantidad
total float Sí Total de la línea (no el precio por unidad)
notes string No Comentario de la línea

A diferencia de las ventas, un elemento desconocido no se omite: la solicitud se rechaza con un error y la compra no se crea.

Proveedor

El proveedor se indica de una de dos formas:

  • supplier_id: el ID de un proveedor existente, p. ej. de v1/suppliers/add;
  • supplier_name: el nombre del proveedor. Si no hay un proveedor con ese nombre, Controlata lo crea junto con la compra a partir de los campos de abajo.
Campo Tipo Descripción
supplier_name string Nombre
supplier_email string Correo electrónico
supplier_phone string Teléfono
supplier_address string Dirección
supplier_agreement string Acuerdo
supplier_manager_name string Responsable
supplier_manager_post string Puesto del responsable
supplier_notes string Notas del proveedor

Si se envían ambos, se usa supplier_id y los supplier_* se ignoran. Si ya existe un proveedor con ese nombre, la compra se vincula a él y los supplier_* no se actualizan.

Ejemplo de solicitud

{
    "supplier_id": 45,
    "date_placed": "2026-10-06",
    "materials_storage_id": 3998,
    "materials": [
        {
            "sku": "M010",
            "amount": 0.2,
            "total": 26000,
            "notes": "Comprobar el grosor"
        },
        {
            "id": 2052,
            "amount": 10,
            "total": 4000
        }
    ],
    "delivery_price": 1500,
    "notes": "Factura n.º 118"
}

Ejemplo de respuesta

{
    "success": true,
    "purchase_id": 29645,
    "status": 1
}

status contiene el código del estado en el que se creó la compra.

Errores

Error Motivo
No supplier_name or supplier_id in input No se envió el proveedor
Supplier not found or access denied El proveedor de supplier_id no se encontró o está eliminado
Supplier name must not be empty supplier_name vacío
Supplier name must be a string supplier_name no es una cadena
Storage ID not found Almacén no encontrado o eliminado
Materials is not an array materials no es un array (igual para products)
No products or materials in input No se envió ninguna línea
Line 0 of materials must be an object La línea no es un objeto (en lugar de 0, el número de línea)
SKU or id not set for material 0 La línea no tiene ni id ni sku
Material with SKU "M010" not found El elemento no se encontró o está eliminado
Amount must be greater than 0 for material with SKU "M010" La cantidad falta, no es un número o no es mayor que 0 tras redondear
Total must be 0 or greater for material with SKU "M010" El total de la línea falta, no es un número o es menor que 0
Invalid notes value for material with SKU "M010". Must be a string notes de la línea no es una cadena
Notes for material with SKU "M010" are too long: maximum 10000 characters El comentario de la línea supera los 10 000 caracteres
Date is not a valid date in format YYYY-MM-DD Fecha de pedido o de recepción no válida
Invalid delivery_price value. Must be a number, 0 or greater El coste de envío no es un número o es menor que 0
Invalid discount value. Must be a number, 0 or greater El descuento no es un número o es menor que 0

En los textos de error de las líneas, material pasa a product en las líneas de productos, y en lugar de SKU "M010" aparece id 2052 si la línea se envió por id.