Compras

8 artículos Maxim Por Maxim

Compras

Compras: comprar materiales y productos a los proveedores. Una compra suma existencias en el almacén y actualiza los precios de los materiales. A través de la API puedes crear, editar y eliminar compras, cambiar el estado y el estado de pago, y obtener la lista de compras y los datos de una compra. 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/purchases/add Crea una compra v1/purchases/edit Modifica una compra v1/purchases/delete Elimina una compra v1/purchases/update_status Cambia el estado de la compra v1/purchases/update_payment Cambia el estado de pago v1/purchases/get_list Devuelve las compras de la empresa v1/purchases/get_entry Devuelve los datos de una compra con sus líneas

Crear una compra

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

Editar una compra

Modifica una compra. Solo se cambian los campos que envías, el resto se queda como estaba. v1/purchases/edit.php Parámetros Campo Tipo Obligatorio Descripción purchase_id int Sí ID de la compra supplier_id int No ID del proveedor supplier_name string No Nombre del proveedor y los campos supplier_ materials array No Líneas de materiales. Reemplazan las líneas actuales por completo products array No Líneas de productos. Reemplazan las líneas actuales por completo date_placed string No Fecha del pedido de compra date_received string No Fecha de recepción. Una cadena vacía la borra materials_storage_id int No Almacén de materiales products_storage_id int No Almacén de productos 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/purchases/update_status y v1/purchases/update_payment. Líneas de la compra Las líneas se envían en los array materials y products. 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 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 Las líneas de la respuesta de v1/purchases/get_entry se pueden reenviar sin cambios. Ejemplo de solicitud Cambiar el coste de envío sin enviar las líneas: { "purchase_id": 29645, "delivery_price": 3000 } Los totales de las líneas se mantienen en 26000 y 4000, mientras que el coste pasa a 28600 y 4400. Los precios de los materiales se actualizan al nuevo coste. Reemplazar las líneas de la compra: { "purchase_id": 29645, "materials": [ { "sku": "M010", "amount": 0.25, "total": 32500 } ] } Ejemplo de respuesta { "success": true } Errores Error Motivo No purchase_id in input Falta purchase_id Purchase not found or access denied Compra no encontrada o eliminada The purchase total is 0, so line totals cannot be restored. Pass materials and products explicitly El total de la compra es 0 y no se enviaron líneas 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. Una date_placed vacía también se rechaza 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 Materials is not an array materials no es un array (igual para products) No products or materials in input Se enviaron materials y products vacíos Material with SKU "M010" not found El elemento no se encontró o está eliminado 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 Los demás errores de líneas son los mismos que en v1/purchases/add.

Eliminar una compra

Elimina una compra. v1/purchases/delete.php Parámetros Campo Tipo Obligatorio Descripción purchase_id int Sí ID de la compra La eliminación no se puede deshacer. Los precios de los materiales y los costes de los productos actualizados por la compra no se revierten a sus valores anteriores. Ejemplo de solicitud { "purchase_id": 29645 } Ejemplo de respuesta { "success": true } Errores Error Motivo No purchase_id in input Falta purchase_id Purchase not found or access denied Compra no encontrada o ya eliminada

Cambiar el estado de la compra

Cambia el estado de la compra. El estado determina si los materiales y productos de la compra entran en las existencias. v1/purchases/update_status.php Parámetros Campo Tipo Obligatorio Descripción purchase_id int Sí ID de la compra status int Sí Nuevo estado: 0 — Plan, 1 — Pedida, 3 — Recibida date_received string No Fecha de recepción. Se tiene en cuenta al pasar al estado Recibida El estado Parcialmente recibida (2) no se puede establecer por la API: aparece cuando parte de la compra se recibe como entregas en la interfaz de Controlata. date_received se tiene en cuenta al pasar a Recibida: se escribe en la compra y la entrada en existencias se fecha con ella. En otros estados date_received se ignora. Ejemplo de solicitud { "purchase_id": 29645, "status": 3, "date_received": "2026-10-09" } Ejemplo de respuesta { "success": true } Errores Error Motivo No purchase_id in input Falta un campo obligatorio (en lugar de purchase_id, el nombre del campo) Invalid status value. Must be one of: 0, 1, 3 Estado no válido, incluido el 2 Purchase not found or access denied Compra no encontrada o eliminada Date is not a valid date in format YYYY-MM-DD date_received no válida

Cambiar el estado de pago

Cambia el estado de pago de la compra. El estado de pago solo marca si la compra se ha pagado al proveedor: no afecta a las existencias, los importes ni el estado de la compra. v1/purchases/update_payment.php Parámetros Campo Tipo Obligatorio Descripción purchase_id int Sí ID de la compra status int Sí Estado de pago: 0 — Sin pagar, 1 — Parcialmente pagada, 2 — Pagada El estado de pago se muestra en la lista de compras si Mostrar el estado de pago de las compras está activado en Configuración → General. Por la API se cambia y se devuelve independientemente de ese ajuste. Ejemplo de solicitud { "purchase_id": 29645, "status": 2 } Ejemplo de respuesta { "success": true } Errores Error Motivo No purchase_id in input Falta un campo obligatorio (en lugar de purchase_id, el nombre del campo) Invalid payment status value. Must be one of: 0, 1, 2 Estado de pago no válido Purchase not found or access denied Compra no encontrada o eliminada

Obtener la lista de compras

Devuelve las compras de la empresa, de las nuevas a las antiguas por fecha del pedido de compra. Las líneas de las compras no se incluyen en la lista; las devuelve v1/purchases/get_entry. v1/purchases/get_list.php Parámetros Campo Tipo Obligatorio Descripción date_from string No Compras desde esta fecha de pedido inclusive date_to string No Compras hasta esta fecha de pedido inclusive supplier_id int No Solo las compras de este proveedor limit int No Tamaño de página, de 1 a 1000 offset int No Cuántos registros omitir Los filtros de fecha funcionan sobre date_placed. Sin parámetros se devuelven todas las compras de la empresa. Consulta la paginación en Reglas generales. Respuesta Un array purchases con los campos de la compra: Campo Tipo Descripción id int ID de la compra status int Estado, un código de Cambiar el estado de la compra payment int Estado de pago, un código de Cambiar el estado de pago date_placed string Fecha del pedido de compra date_received string Fecha de recepción. Cadena vacía si no se ha fijado supplier_id int ID del proveedor supplier_name string Nombre del proveedor materials_storage_id int Almacén de materiales materials_storage_name string Nombre del almacén de materiales products_storage_id int Almacén de productos products_storage_name string Nombre del almacén de productos 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 amount float Cantidad total si todas las líneas comparten una unidad, si no null lines int Número de líneas notes string Notas El campo total en la raíz de la respuesta contiene el número total de compras que cumplen los filtros. Ejemplo de solicitud { "date_from": "2026-10-01", "supplier_id": 45, "limit": 100, "offset": 0 } Ejemplo de respuesta { "success": true, "purchases": [ { "id": 29645, "status": 1, "payment": 0, "date_placed": "2026-10-06", "date_received": "", "supplier_id": 45, "supplier_name": "Maderas García", "materials_storage_id": 3998, "materials_storage_name": "Almacén principal", "products_storage_id": 3998, "products_storage_name": "Almacén principal", "subtotal": 30000, "delivery_price": 1500, "discount": 0, "total": 31500, "amount": null, "lines": 2, "notes": "Factura n.º 118" } ], "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 compra

Devuelve los datos de una compra y sus líneas. v1/purchases/get_entry.php Parámetros Campo Tipo Obligatorio Descripción purchase_id int Sí ID de la compra Respuesta Un objeto purchase con los campos de la compra: Campo Tipo Descripción id int ID de la compra status int Estado, un código de Cambiar el estado de la compra payment int Estado de pago, un código de Cambiar el estado de pago date_placed string Fecha del pedido de compra date_received string Fecha de recepción. Cadena vacía si no se ha fijado supplier_id int ID del proveedor supplier_name string Nombre del proveedor materials_storage_id int Almacén de materiales materials_storage_name string Nombre del almacén de materiales products_storage_id int Almacén de productos products_storage_name string Nombre del almacén de productos 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 amount float Cantidad total si todas las líneas comparten una unidad, si no null lines int Número de líneas notes string Notas Y dos array de líneas de la compra: materials y products. Campos de la línea: Campo Tipo Descripción id int ID del material o del producto 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 ficha de la compra, 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 compra. Las líneas de la respuesta se pueden enviar a v1/purchases/edit sin cambios: los campos de más se ignoran. Ejemplo de solicitud { "purchase_id": 29645 } Ejemplo de respuesta { "success": true, "purchase": { "id": 29645, "status": 1, "payment": 0, "date_placed": "2026-10-06", "date_received": "", "supplier_id": 45, "supplier_name": "Maderas García", "materials_storage_id": 3998, "materials_storage_name": "Almacén principal", "products_storage_id": 3998, "products_storage_name": "Almacén principal", "subtotal": 30000, "delivery_price": 1500, "discount": 0, "total": 31500, "amount": null, "lines": 2, "notes": "Factura n.º 118", "materials": [ { "id": 2051, "sku": "M010", "name": "Tablón de roble", "amount": 0.2, "cost": 27300, "unit": "m3", "position": 0, "total": 26000, "price": 130000, "notes": "Comprobar el grosor" }, { "id": 2052, "sku": "M011", "name": "Cola de carpintero", "amount": 10, "cost": 4200, "unit": "kg", "position": 1, "total": 4000, "price": 400, "notes": "" } ], "products": [] } } Errores Error Motivo No purchase_id in input Falta purchase_id Purchase not found or access denied Compra no encontrada o eliminada