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).
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;
- 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.