Maxim

Maxim

Última actualización el Oct 21, 2026

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.