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.