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](https://developers.controlata.com/hc/api-docs/articles/api-purchases-update-status-es)).

```
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](https://developers.controlata.com/hc/api-docs/articles/api-suppliers-add-es);
* **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.
