Inventarios físicos

7 artículos Maxim Por Maxim

Inventarios físicos

Inventarios físicos: conciliar las existencias reales de un almacén con las existencias en Controlata. Envías la cantidad real, y Controlata la compara con las existencias previstas y ajusta las existencias por la diferencia. A través de la API puedes crear, editar y eliminar inventarios, cambiar su estado, y obtener la lista y los datos de un inventario. 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/audits/add Crea un inventario v1/audits/edit Modifica las líneas del inventario v1/audits/delete Elimina un inventario v1/audits/update_status Cambia el estado del inventario v1/audits/get_list Devuelve la lista de inventarios v1/audits/get_entry Devuelve un inventario con sus líneas

Crear un inventario físico

Crea un inventario físico de materiales o productos en un almacén. Envía solo las existencias reales: Controlata calcula las existencias previstas en la fecha del inventario. v1/audits/add.php Parámetros Campo Tipo Obligatorio Descripción storage_id int Sí Almacén donde se realiza el inventario materials array materials o products Líneas de inventario de materiales products array materials o products Líneas de inventario de productos date string No Fecha del inventario, YYYY-MM-DD. Por defecto hoy Línea materials y products: Campo Tipo Obligatorio Descripción id int id o sku ID del material o del producto sku string id o sku SKU actual float Sí Existencias reales, 0 o más notes string No Notas de la línea Las líneas se envían en un solo array: un inventario cuenta o materiales o productos. El número se asigna automáticamente. Un inventario nuevo se crea con el estado del ajuste Estado por defecto de los nuevos inventarios físicos. Ejemplo de solicitud { "storage_id": 3998, "date": "2026-09-30", "materials": [ { "id": 2051, "actual": 3.8 }, { "sku": "M022", "actual": 0, "notes": "No encontrado en el almacén" } ] } Ejemplo de respuesta { "success": true, "audit_id": 1699, "num": 24, "status": 1 } La respuesta devuelve el ID, el número y el código de estado del nuevo inventario. Las existencias previstas y la diferencia por línea las devuelve v1/audits/get_entry. Errores Error Motivo No storage_id in input Falta storage_id Storage ID is not set storage_id es 0 o está vacío Storage ID not found Almacén no encontrado o eliminado Storage location 4001 does not store materials El almacén no guarda elementos del tipo del inventario (para productos: does not store products) An audit counts either materials or products. Create separate audits Se enviaron materials y products No products or materials in input No se envió ninguna línea Materials is not an array materials no es un array (igual para products) 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 id 2051 not found Material no encontrado o eliminado (para un SKU: Material with SKU "M022" not found) Actual must be 0 or greater for material with id 2051 actual falta, no es un número o es menor que 0 Material with id 2051 is listed twice El elemento aparece en dos líneas Date is not a valid date in format YYYY-MM-DD Formato de fecha no válido

Editar un inventario físico

Modifica las líneas del inventario. La fecha, el almacén y el tipo del inventario no cambian. v1/audits/edit.php Parámetros Campo Tipo Obligatorio Descripción audit_id int Sí ID del inventario materials array No Líneas de inventario de materiales: id o sku, actual, notes products array No Líneas de inventario de productos: id o sku, actual, notes Las líneas se envían como en v1/audits/add, y solo en el array del tipo que cuenta el inventario. Las líneas se reemplazan por completo. Ejemplo de solicitud { "audit_id": 1699, "materials": [ { "id": 2051, "actual": 4 }, { "sku": "M022", "actual": 0, "notes": "No encontrado en el almacén" } ] } Ejemplo de respuesta { "success": true } Errores Error Motivo No audit_id in input Falta audit_id Audit not found or access denied Inventario no encontrado o eliminado This audit counts materials. Its type cannot be changed Las líneas se enviaron en el array del otro tipo (para productos: This audit counts products) An audit counts either materials or products. Create separate audits Se enviaron materials y products No products or materials in input Los array de líneas se enviaron pero vacíos Material with id 2051 not found Material no encontrado o eliminado Actual must be 0 or greater for material with id 2051 actual falta, no es un número o es menor que 0 Material with id 2051 is listed twice El elemento aparece en dos líneas Los demás errores de líneas son los mismos que en v1/audits/add.

Eliminar un inventario físico

Elimina un inventario físico. v1/audits/delete.php Parámetros Campo Tipo Obligatorio Descripción audit_id int Sí ID del inventario La eliminación no se puede deshacer. Los ajustes del inventario se revierten: los excedentes se quitan del almacén y los faltantes vuelven a él. Ejemplo de solicitud { "audit_id": 1699 } Ejemplo de respuesta { "success": true } Errores Error Motivo No audit_id in input Falta audit_id Audit not found or access denied Inventario no encontrado o ya eliminado

Cambiar el estado del inventario físico

Cambia el estado del inventario. El estado determina si las existencias se ajustan en el almacén. v1/audits/update_status.php Parámetros Campo Tipo Obligatorio Descripción audit_id int Sí ID del inventario status int Sí Nuevo estado: 0 — Planificado, 1 — Completado Ejemplo de solicitud { "audit_id": 1699, "status": 1 } Ejemplo de respuesta { "success": true } Errores Error Motivo No audit_id in input Falta un campo obligatorio (en lugar de audit_id, el nombre del campo) Invalid status value. Must be one of: 0, 1 Código de estado no válido Audit not found or access denied Inventario no encontrado o eliminado

Obtener la lista de inventarios físicos

Devuelve los inventarios de la empresa, de los nuevos a los antiguos: por fecha y, dentro de una misma fecha, por número. Las líneas no se incluyen en la lista; las devuelve v1/audits/get_entry. v1/audits/get_list.php Parámetros Campo Tipo Obligatorio Descripción storage_id int No Solo los inventarios de este almacén date_from string No Inventarios desde esta fecha inclusive, YYYY-MM-DD date_to string No Inventarios hasta esta fecha inclusive, YYYY-MM-DD status int No Estado: 0 Planificado, 1 Completado limit int No Tamaño de página, de 1 a 1000 offset int No Cuántos registros omitir Sin limit se devuelve toda la lista. Consulta la paginación en Reglas generales. Respuesta Un array audits con los campos del inventario: Campo Tipo Descripción id int ID del inventario físico num int Número. Se asigna automáticamente date string Fecha del inventario, YYYY-MM-DD status int Estado: 0 Planificado, 1 Completado storage_id int Almacén donde se realiza el inventario storage_name string Nombre del almacén lines int Número de líneas surplus_cost float Excedentes al coste shortage_cost float Faltantes al coste, un número negativo total_cost float Total al coste: surplus_cost más shortage_cost surplus_price float Excedentes al precio de venta. Solo productos, 0 en materiales shortage_price float Faltantes al precio de venta, un número negativo. Solo productos total_price float Total al precio de venta: surplus_price más shortage_price El campo total contiene el número total de inventarios que cumplen los filtros. Ejemplo de solicitud { "storage_id": 3998, "date_from": "2026-01-01", "limit": 100, "offset": 0 } Ejemplo de respuesta { "success": true, "audits": [ { "id": 1699, "num": 24, "date": "2026-09-30", "status": 1, "storage_id": 3998, "storage_name": "Principal", "lines": 2, "surplus_cost": 0, "shortage_cost": -57900, "total_cost": -57900, "surplus_price": 0, "shortage_price": 0, "total_price": 0 } ], "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 status value. Must be a number status no es un número Invalid limit value. Must be between 1 and 1000 limit no válido Offset requires limit se envió offset sin limit

Obtener los datos de un inventario físico

Devuelve un inventario con sus líneas: las existencias previstas y reales y la diferencia de cada elemento. v1/audits/get_entry.php Parámetros Campo Tipo Obligatorio Descripción audit_id int Sí ID del inventario Respuesta Un objeto audit con los campos del inventario: Campo Tipo Descripción id int ID del inventario físico num int Número. Se asigna automáticamente date string Fecha del inventario, YYYY-MM-DD status int Estado: 0 Planificado, 1 Completado storage_id int Almacén donde se realiza el inventario storage_name string Nombre del almacén lines int Número de líneas surplus_cost float Excedentes al coste shortage_cost float Faltantes al coste, un número negativo total_cost float Total al coste: surplus_cost más shortage_cost surplus_price float Excedentes al precio de venta. Solo productos, 0 en materiales shortage_price float Faltantes al precio de venta, un número negativo. Solo productos total_price float Total al precio de venta: surplus_price más shortage_price Y líneas en dos array: materials y products. Solo se rellena el array del tipo que cuenta el inventario; el otro llega vacío. Campo Tipo Descripción id int ID del material o del producto sku string SKU name string Nombre unit string Unidad de medida expected float Existencias previstas en la fecha del inventario actual float Existencias reales difference float Diferencia: actual menos expected. Positiva significa excedente, negativa faltante notes string Notas de la línea position int Número de línea, desde 0 Las líneas de la respuesta se pueden enviar a v1/audits/edit sin cambios: el método toma de ellas id, actual y notes. Ejemplo de solicitud { "audit_id": 1699 } Ejemplo de respuesta { "success": true, "audit": { "id": 1699, "num": 24, "date": "2026-09-30", "status": 1, "storage_id": 3998, "storage_name": "Principal", "lines": 2, "surplus_cost": 0, "shortage_cost": -57900, "total_cost": -57900, "surplus_price": 0, "shortage_price": 0, "total_price": 0, "materials": [ { "id": 2051, "sku": "M010", "name": "Tablón de roble", "unit": "m3", "expected": 4.2, "actual": 3.8, "difference": -0.4, "notes": "", "position": 0 }, { "id": 2077, "sku": "M022", "name": "Barniz para muebles", "unit": "l", "expected": 6, "actual": 0, "difference": -6, "notes": "No encontrado en el almacén", "position": 1 } ], "products": [] } } Errores Error Motivo No audit_id in input Falta audit_id Audit not found or access denied Inventario no encontrado o eliminado