Ventas
Por Maxim
Por Maxim
Ventas
Ventas: vender productos, y materiales cuando el ajuste está activado, a tus clientes. A través de la API puedes crearlas, editarlas y eliminarlas, cambiar el estado y el estado de pago, y obtener la lista de ventas y los datos de una venta. Las rutas de los métodos se indican respecto a la dirección base de la API; las reglas comunes a todos los métodos (autorización, formato de las solicitudes, edición parcial, paginación) se describen en Descripción general de la API y Reglas generales. Métodos Método Qué hace v1/orders/add Crea una venta v1/orders/edit Modifica una venta v1/orders/delete Elimina una venta v1/orders/update_status Cambia el estado de la venta v1/orders/update_payment Cambia el estado de pago v1/orders/get_list Devuelve las ventas de la empresa v1/orders/get_entry Devuelve los datos de una venta con sus líneas
Crear una venta
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.
Editar una venta
Modifica una venta. Solo se cambian los campos que envías, el resto se queda como estaba. v1/orders/edit.php Parámetros Campo Tipo Obligatorio Descripción order_id int Sí ID de la venta num string No Número de venta sin el prefijo products array No Líneas de productos. Reemplazan las líneas actuales por completo materials array No Líneas de materiales. Reemplazan las líneas actuales por completo customer_id int No ID del cliente customer_name string No Nombre del cliente y los campos customer_ date_placed string No Fecha de la venta date_shipped string No Fecha de envío. Una cadena vacía la borra products_storage_id int No Almacén de productos materials_storage_id int No Almacén de materiales production int No 1 activa la producción bajo pedido, 0 la desactiva delivery_price float No Coste de envío discount float No Descuento notes string No Notas El estado y el estado de pago no se cambian con este método; usa v1/orders/update_status y v1/orders/update_payment. Líneas de la venta Las líneas se envían en los array products y materials. Si se envía al menos uno de los array, las líneas se reemplazan por completo, y el array que no se envía se considera vacío. Si no se envía ninguno, las líneas no cambian. 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 Las líneas de la respuesta de v1/orders/get_entry se pueden reenviar sin cambios. Ejemplo de solicitud Añadir un descuento y cambiar las notas sin tocar las líneas ni el cliente: { "order_id": 43727, "discount": 1500, "notes": "Descuento por código promocional" } Reemplazar las líneas de la venta: { "order_id": 43727, "products": [ { "sku": "P001", "amount": 3, "total": 39000 } ] } Ejemplo de respuesta { "success": true } Errores Error Motivo No order_id in input Falta order_id Order not found or access denied Venta no encontrada o eliminada Products is not an array products no es un array (igual para materials) No products or materials in input Se enviaron products y materials vacíos Materials in orders are disabled in company settings Se enviaron materiales, pero el ajuste Permitir el pedido de materiales está desactivado All products have wrong SKU or id No se encontró ninguna línea (con materiales, "All products and materials have wrong SKU or id") 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 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 Customer not found El cliente de customer_id no se encontró o está eliminado Customer name must not be empty customer_name vacío Los errores de líneas individuales (sin amount o total, cantidad no válida) son los mismos que en v1/orders/add.
Eliminar una venta
Elimina una venta. v1/orders/delete.php Parámetros Campo Tipo Obligatorio Descripción order_id int Sí ID de la venta La eliminación no se puede deshacer. Para conservar la venta en el historial pero quitar su efecto en las existencias, pásala al estado Cancelado con v1/orders/update_status. Ejemplo de solicitud { "order_id": 43727 } Ejemplo de respuesta { "success": true } Errores Error Motivo No order_id in input Falta order_id Order not found or access denied Venta no encontrada o ya eliminada
Cambiar el estado de la venta
Cambia el estado de la venta. El estado determina si los productos y materiales de la venta se descuentan de las existencias. v1/orders/update_status.php Parámetros Campo Tipo Obligatorio Descripción order_id int Sí ID de la venta status int Sí Nuevo estado: 0 — Nuevo, 1 — Empaquetado, 3 — Enviado, 4 — Cancelado date_shipped string No Fecha de envío. Se tiene en cuenta al pasar al estado Enviado El estado Parcialmente enviado (2) no se puede establecer por la API: aparece cuando parte de la venta se envía en la interfaz de Controlata. date_shipped se tiene en cuenta al pasar a Enviado: se escribe en la venta y el descuento se fecha con ella. En otros estados date_shipped se ignora. Ejemplo de solicitud { "order_id": 43727, "status": 3, "date_shipped": "2026-10-08" } Ejemplo de respuesta { "success": true } Errores Error Motivo No order_id in input Falta un campo obligatorio (en lugar de order_id, el nombre del campo) Invalid status value. Must be one of: 0, 1, 3, 4 Estado no válido, incluido el 2 Order not found or access denied Venta no encontrada o eliminada Date is not a valid date in format YYYY-MM-DD date_shipped no válida
Cambiar el estado de pago
Cambia el estado de pago de la venta. El estado de pago solo marca si se ha recibido el dinero del cliente: no afecta a las existencias, los importes ni el estado de la venta. v1/orders/update_payment.php Parámetros Campo Tipo Obligatorio Descripción order_id int Sí ID de la venta status int Sí Estado de pago: 0 — Sin pagar, 1 — Parcialmente pagada, 2 — Pagada El estado de pago se muestra en la lista de ventas si Mostrar el estado de pago de las ventas está activado en Configuración → General. Por la API se cambia y se devuelve independientemente de ese ajuste. Ejemplo de solicitud { "order_id": 43727, "status": 2 } Ejemplo de respuesta { "success": true } Errores Error Motivo No order_id in input Falta un campo obligatorio (en lugar de order_id, el nombre del campo) Invalid payment status value. Must be one of: 0, 1, 2 Estado de pago no válido Order not found or access denied Venta no encontrada o eliminada
Obtener la lista de ventas
Devuelve las ventas de la empresa, de las nuevas a las antiguas: por fecha de venta y, dentro de una misma fecha, por número. Las líneas de las ventas no se incluyen en la lista; las devuelve v1/orders/get_entry. v1/orders/get_list.php Parámetros Campo Tipo Obligatorio Descripción date_from string No Ventas desde esta fecha de venta inclusive date_to string No Ventas hasta esta fecha de venta inclusive limit int No Tamaño de página, de 1 a 1000 offset int No Cuántos registros omitir Los filtros funcionan sobre date_placed. Sin parámetros se devuelven todas las ventas de la empresa. Consulta la paginación en Reglas generales. Respuesta Un array orders. Cada objeto contiene los campos de la venta: Campo Tipo Descripción id int ID de la venta num string Número de venta con el prefijo status int Estado, un código de Cambiar el estado de la venta payment int Estado de pago, un código de Cambiar el estado de pago date_placed string Fecha de la venta date_shipped string Fecha de envío. Cadena vacía si no se ha fijado subtotal float Suma de las líneas delivery_price float Coste de envío discount float Descuento total float Total: subtotal más delivery_price menos discount cost float Coste de la venta amount float Cantidad total si todas las líneas comparten una unidad, si no null lines int Número de líneas production int 1 si la venta se prepara con producción bajo pedido production_num string Número de la producción vinculada, null sin producción source string De dónde viene la venta: «manual», «api», «shopify» notes string Notas products_storage_id int Almacén de productos products_storage_name string Nombre del almacén de productos materials_storage_id int Almacén de materiales materials_storage_name string Nombre del almacén de materiales customer_id int ID del cliente 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 El campo total en la raíz de la respuesta contiene el número total de ventas que cumplen los filtros. Ejemplo de solicitud { "date_from": "2026-10-01", "date_to": "2026-10-31", "limit": 100, "offset": 0 } Ejemplo de respuesta { "success": true, "orders": [ { "id": 43727, "num": "A-1001", "status": 3, "payment": 2, "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "subtotal": 30500, "delivery_price": 500, "discount": 1000, "total": 30000, "cost": 17800, "amount": 3, "lines": 2, "production": 0, "production_num": null, "source": "api", "notes": "Pedido desde la web", "products_storage_id": 3998, "products_storage_name": "Almacén principal", "materials_storage_id": 3998, "materials_storage_name": "Almacén principal", "customer_id": 512, "customer_name": "Juan Pérez", "customer_email": "juan@example.com", "customer_phone": "+34 600 111 222", "customer_address_real": "C/ Mayor 5, 3º, Madrid", "customer_address_legal": "", "customer_agreement": "", "customer_manager_name": "", "customer_manager_post": "", "customer_notes": "" } ], "total": 1 } Errores Error Motivo Date is not a valid date in format YYYY-MM-DD date_from o date_to no válida Invalid limit value. Must be between 1 and 1000 limit no válido Invalid offset value. Must be 0 or greater offset no válido Offset requires limit se envió offset sin limit
Obtener los datos de una venta
Devuelve los datos de una venta, el cliente y las líneas de la venta. v1/orders/get_entry.php Parámetros Campo Tipo Obligatorio Descripción order_id int Sí ID de la venta Respuesta Un objeto order con los campos de la venta: Campo Tipo Descripción id int ID de la venta num string Número de venta con el prefijo status int Estado, un código de Cambiar el estado de la venta payment int Estado de pago, un código de Cambiar el estado de pago date_placed string Fecha de la venta date_shipped string Fecha de envío. Cadena vacía si no se ha fijado subtotal float Suma de las líneas delivery_price float Coste de envío discount float Descuento total float Total: subtotal más delivery_price menos discount cost float Coste de la venta amount float Cantidad total si todas las líneas comparten una unidad, si no null lines int Número de líneas production int 1 si la venta se prepara con producción bajo pedido production_num string Número de la producción vinculada, null sin producción source string De dónde viene la venta: «manual», «api», «shopify» notes string Notas products_storage_id int Almacén de productos products_storage_name string Nombre del almacén de productos materials_storage_id int Almacén de materiales materials_storage_name string Nombre del almacén de materiales customer_id int ID del cliente 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 Y dos array de líneas de la venta: products y materials. Campos de la línea: Campo Tipo Descripción id int ID del producto o del material sku string SKU name string Nombre amount float Cantidad unit string Unidad de medida total float Total de la línea price float Precio por unidad: total dividido entre amount cost float Coste de la línea position int Número de línea en la venta, desde 0 notes string Comentario de la línea. Cadena vacía si no hay La numeración de position es común para ambos array: con ella se restaura el orden de las líneas como en la ficha de la venta. Las líneas de la respuesta se pueden enviar a v1/orders/edit sin cambios: los campos de más se ignoran. Ejemplo de solicitud { "order_id": 43727 } Ejemplo de respuesta { "success": true, "order": { "id": 43727, "num": "A-1001", "status": 3, "payment": 2, "date_placed": "2026-10-06", "date_shipped": "2026-10-08", "subtotal": 30500, "delivery_price": 500, "discount": 1000, "total": 30000, "cost": 17800, "amount": 3, "lines": 2, "production": 0, "production_num": null, "source": "api", "notes": "Pedido desde la web", "products_storage_id": 3998, "products_storage_name": "Almacén principal", "materials_storage_id": 3998, "materials_storage_name": "Almacén principal", "customer_id": 512, "customer_name": "Juan Pérez", "customer_email": "juan@example.com", "customer_phone": "+34 600 111 222", "customer_address_real": "C/ Mayor 5, 3º, Madrid", "customer_address_legal": "", "customer_agreement": "", "customer_manager_name": "", "customer_manager_post": "", "customer_notes": "", "products": [ { "id": 815, "sku": "P001", "name": "Mesa de roble", "amount": 2, "unit": "ud", "total": 26000, "price": 13000, "cost": 15400, "position": 0, "notes": "Grabado: Ana" }, { "id": 816, "sku": "P002", "name": "Taburete de roble", "amount": 1, "unit": "ud", "total": 4500, "price": 4500, "cost": 2400, "position": 1, "notes": "" } ], "materials": [] } } Errores Error Motivo No order_id in input Falta order_id Order not found or access denied Venta no encontrada o eliminada