Crea una venta. El estado de la venta viene del ajuste **Estado por defecto de las nuevas ventas** en los ajustes del sistema, y el estado determina si los productos y materiales se descuentan de inmediato (consulta [Cambiar el estado de la venta](https://developers.controlata.com/hc/api-docs/articles/api-orders-update-status-es)).

```
v1/orders/add.php
```

## Parámetros

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| num | string | Sí | Número de venta sin el prefijo |
| products | array | products o materials | Líneas de productos |
| materials | array | products o materials | Líneas de materiales. Se aceptan cuando el ajuste **Permitir el pedido de materiales** está activado |
| customer_id | int | customer_id o customer_name | ID de un cliente existente |
| customer_name | string | customer_id o customer_name | Nombre del cliente. Si no existe, se crea a partir de los campos con prefijo customer_ |
| date_placed | string | No | Fecha de la venta. Por defecto hoy |
| date_shipped | string | No | Fecha de envío |
| products_storage_id | int | No | Almacén de productos. Por defecto el de los ajustes |
| materials_storage_id | int | No | Almacén de materiales. Por defecto el de los ajustes |
| production | int | No | 1 para preparar la venta con producción bajo pedido. Por defecto 0 |
| delivery_price | float | No | Coste de envío. Por defecto 0 |
| discount | float | No | Descuento. Por defecto 0 |
| notes | string | No | Notas |

El ajuste **Método de preparación por defecto de las nuevas ventas** no afecta a la API: sin production, la venta se prepara desde el almacén.

## Líneas de la venta

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

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| id | int | id o sku | ID del producto o del material |
| 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 |

Si no se encuentra un elemento, la línea se omite y se añade un mensaje a las notas de la venta, por ejemplo:

```
Product with SKU "P099", amount 2, total 5000 not found in Controlata, check sku.
```

Si no se encuentra ninguna línea, la venta no se crea.

Los materiales en las ventas se aceptan solo si **Permitir el pedido de materiales** está activado en **Configuración → General**. De lo contrario, una solicitud con materiales se rechaza.

## Cliente

El cliente se indica de una de dos formas:

* **customer_id**: el ID de un cliente existente, p. ej. de [v1/customers/add](https://developers.controlata.com/hc/api-docs/articles/api-customers-add-es);
* **customer_name**: el nombre del cliente. Si no hay un cliente con ese nombre, Controlata lo crea junto con la venta a partir de los campos de abajo.

| Campo | Tipo | Descripción |
|---|---|---|
| customer_name | string | Nombre |
| customer_email | string | Correo electrónico |
| customer_phone | string | Teléfono |
| customer_address_real | string | Dirección de entrega |
| customer_address_legal | string | Dirección fiscal |
| customer_agreement | string | Acuerdo |
| customer_manager_name | string | Responsable |
| customer_manager_post | string | Puesto del responsable |
| customer_notes | string | Notas del cliente |

Si se envían ambos, se usa customer_id y los customer_* se ignoran. Si ya existe un cliente con ese nombre, la venta se vincula a él y los customer_* no se actualizan.

## Número de venta

Controlata añade un prefijo del ajuste **Prefijo del número de venta** en la conexión de la API. Con el prefijo «A-», el número «1001» que envías se guarda como «A-1001» y se devuelve como «A-1001».

## Ejemplo de solicitud

```
{
    "num": "1001",
    "date_placed": "2026-10-06",
    "customer_name": "Juan Pérez",
    "customer_phone": "+34 600 111 222",
    "customer_email": "juan@example.com",
    "customer_address_real": "C/ Mayor 5, 3º, Madrid",
    "products": [
        {
            "sku": "P001",
            "amount": 2,
            "total": 26000,
            "notes": "Grabado: Ana"
        },
        {
            "id": 816,
            "amount": 1,
            "total": 4500
        }
    ],
    "delivery_price": 500,
    "discount": 1000,
    "notes": "Pedido desde la web"
}
```

## Ejemplo de respuesta

```
{
    "success": true,
    "order_id": 43727,
    "customer_id": 512
}
```

customer_id contiene el ID del cliente de la venta: el encontrado por customer_id o el creado por customer_name.

## Errores

| Error | Motivo |
|---|---|
| No num in input | num falta o está vacío |
| Products is not an array | products no es un array (igual para materials) |
| No products or materials in input | No se envió ninguna línea |
| Materials in orders are disabled in company settings | Se enviaron materiales, pero el ajuste **Permitir el pedido de materiales** está desactivado |
| Storage ID is not set | Se envió un almacén vacío |
| Storage ID not found | Almacén no encontrado o eliminado |
| Date is not a valid date in format YYYY-MM-DD | Fecha de venta o de envío 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 |
| Line 0 of products 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 product 0 | La línea no tiene ni id ni sku |
| Amount not set for product with SKU "P001" | La línea no tiene amount |
| Total not set for product with SKU "P001" | La línea no tiene total |
| Amount must be greater than 0 for product with SKU "P001" | La cantidad no es un número o no es mayor que 0 tras redondear |
| Total must be a number for product with SKU "P001" | El total de la línea no es un número |
| Invalid notes value for product with SKU "P001". Must be a string | notes de la línea no es una cadena |
| Notes for product with SKU "P001" are too long: maximum 10000 characters | El comentario de la línea supera los 10 000 caracteres |
| All products have wrong SKU or id | No se encontró ninguna línea. Si se enviaron materiales, el texto es "All products and materials have wrong SKU or id" |
| No customer_name or customer_id in input | No se envió el cliente |
| Customer not found | El cliente de customer_id no se encontró o está eliminado |
| Customer name must not be empty | customer_name vacío |
| Customer name must be a string | customer_name no es una cadena |

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