Materials

Materials

Materials: the raw materials and components your products are made from. Via the API you can create, edit and delete them, get a list and a material's details, and update stock at storage locations. Method paths are given relative to the base API URL; the rules common to all methods (authorization, request format, partial editing, pagination) are described in API Overview and Common Rules. Methods | Method | What it does | |---|---| | v1/materials/add | Creates a material | | v1/materials/edit | Updates a material | | v1/materials/delete | Deletes a material | | v1/materials/update_stock | Sets the stock at a storage location | | v1/materials/get_list | Returns the materials of a storage location | | v1/materials/get_entry | Returns a material's details | | v1/materials/get_stocks | Returns material stock across all storage locations |

Creating a Material

Creates a material. The material appears at storage location storage_id and at any storage location that stores all materials or its categories. v1/materials/add.php Parameters | Field | Type | Required | Description | |---|---|---|---| | name | string | Yes | Name | | unit | string | Yes | Unit of measure, a code from Units of Measure | | storage_id | int | Yes | Storage location where the stock is created | | sku | string | No | SKU | | price | float | No | Price per unit. Default 0 | | stock | float | No | Initial stock at storage location storage_id. Default 0 | | minimum | float | No | Minimum stock at storage location storage_id. Default 0 | | notes | string | No | Notes | | categories | array | No | Categories: objects with id or name | | suppliers | array | No | Suppliers: objects with id | A category can be passed by name: if there is no such category, it is created. The IDs of existing categories and suppliers are returned by v1/categories/get_list and v1/suppliers/get_list. SKU uniqueness is not checked. Example request { "name": "Oak board", "sku": "M010", "unit": "cu m", "price": 130000, "storage_id": 3998, "stock": 2.5, "minimum": 0.5, "categories": [{ "id": 12 }, { "name": "Hardware" }], "suppliers": [{ "id": 45 }] } Example response { "success": true, "material_id": 2051 } Errors | Error | Reason | |---|---| | No name in input | A required field is missing (instead of name, the field's name) | | Name must not be empty | Empty name | | Unit not found | Unknown unit of measure, or a resources-only unit | | Storage ID not found | Storage location not found or deleted | | Invalid price value. Must be a number | The value is not a number, e.g. "12,5" (same for stock and minimum) | | Category 12 not found | Category not found | | Supplier not found or access denied | Supplier not found or deleted |

Editing a Material

Updates a material. Only the fields you pass are changed, the rest stay as they were. v1/materials/edit.php Parameters | Field | Type | Required | Description | |---|---|---|---| | material_id | int | Yes | Material ID | | name | string | No | Name | | sku | string | No | SKU | | unit | string | No | Unit of measure | | price | float | No | Price per unit | | notes | string | No | Notes | | minimum | float | No | Minimum stock at storage location storage_id | | storage_id | int | With minimum | Storage location where the minimum stock is changed | | categories | array | No | Categories: objects with id or name. Replace the current ones as a whole | | suppliers | array | No | Suppliers: objects with id. Replace the current ones as a whole | Example request { "material_id": 2051, "price": 135000, "minimum": 1, "storage_id": 3998 } Example response { "success": true } Errors | Error | Reason | |---|---| | No material_id in input | material_id is missing | | Material not found or access denied | Material not found or deleted | | Name must not be empty | An empty name was passed | | Unit not found | Unknown unit of measure | | Unit cannot be changed to another unit group: the material is used in components of products | Changing the unit group of a material used in product components | | No storage_id in input | minimum passed without storage_id | | Material is not stored in storage location 3998, so its minimum cannot be set there | The material is not stocked at that storage location | | Invalid price value. Must be a number | The value is not a number (same for minimum) | | Category 12 not found | Category not found | | Supplier not found or access denied | Supplier not found or deleted |

Deleting a Material

Deletes a material. v1/materials/delete.php Parameters | Field | Type | Required | Description | |---|---|---|---| | material_id | int | Yes | Material ID | Example request { "material_id": 2051 } Example response { "success": true } Errors | Error | Reason | |---|---| | No material_id in input | material_id is missing | | Material not found or access denied | Material not found or already deleted |

Updating Material Stock

Sets a material's stock at a storage location. You pass the final stock, not the change: Controlata creates an adjustment for the difference between the current and the new stock. v1/materials/update_stock.php Parameters | Field | Type | Required | Description | |---|---|---|---| | material_id | int | Yes | Material ID | | storage_id | int | Yes | Storage location ID | | stock | float | Yes | New stock | | notes | string | No | Notes for the adjustment | Example request { "material_id": 2051, "storage_id": 3998, "stock": 4.2, "notes": "Stocktake at the storage location" } Example response { "success": true } Errors | Error | Reason | |---|---| | No stock in input | A required field is missing (instead of stock, the field's name) | | Material not found or access denied | Material not found or deleted | | Storage ID not found | Storage location not found or deleted | | Invalid stock value. Must be a number | The stock is not a number, e.g. "" or "4,2" |

Retrieving a List of Materials

Returns the materials stocked at a storage location (including those with zero stock), sorted by name. Archived materials are included too. v1/materials/get_list.php Parameters | Field | Type | Required | Description | |---|---|---|---| | storage_id | int | Yes | Storage location ID | | limit | int | No | Page size, from 1 to 1000 | | offset | int | No | How many records to skip | Without limit the whole list is returned. See Common Rules for pagination. Response An array materials with the material's fields and its stock at storage location storage_id: | Field | Type | Description | |---|---|---| | id | int | Material ID | | name | string | Name | | sku | string | SKU | | unit | string | Unit of measure, a code from Units of Measure | | price | float | Price per unit | | notes | string | Notes | | archived | int | 1 if the material is archived | | stock | float | Stock at storage location storage_id | | minimum | float | Minimum stock at storage location storage_id | | planned | float | Stock change from operations in the Planned status. null if there are none | | categories | array | The material's categories: objects with id and name | | suppliers | array | The material's suppliers: objects with id and name | The total field holds the total number of materials at the storage location. Example request { "storage_id": 3998, "limit": 100, "offset": 0 } Example response { "success": true, "materials": [ { "id": 2051, "name": "Oak board", "sku": "M010", "price": 135000, "notes": "", "archived": 0, "stock": 4.2, "minimum": 1, "planned": null, "unit": "cu m", "categories": [ { "id": 12, "name": "Wood" } ], "suppliers": [ { "id": 45, "name": "Woodtrade Ltd" } ] } ], "total": 1 } Errors | Error | Reason | |---|---| | No storage_id in input | storage_id is missing | | Storage ID not found | Storage location not found or deleted | | Invalid limit value. Must be between 1 and 1000 | Invalid limit | | Offset requires limit | offset passed without limit |

Retrieving a Material

Returns a material's details and its stock at a storage location. v1/materials/get_entry.php Parameters | Field | Type | Required | Description | |---|---|---|---| | material_id | int | Yes | Material ID | | storage_id | int | Yes | Storage location ID | The material is returned only if it is stocked at storage location storage_id. Stock across all storage locations at once is returned by v1/materials/get_stocks. Response An object material with the material's fields, its stock at storage location storage_id, its categories and suppliers. The categories and suppliers from the response can be sent to v1/materials/edit unchanged. | Field | Type | Description | |---|---|---| | id | int | Material ID | | name | string | Name | | sku | string | SKU | | unit | string | Unit of measure, a code from Units of Measure | | price | float | Price per unit | | notes | string | Notes | | archived | int | 1 if the material is archived | | stock | float | Stock at storage location storage_id | | minimum | float | Minimum stock at storage location storage_id | | planned | float | Stock change from operations in the Planned status. null if there are none | | categories | array | The material's categories: objects with id and name | | suppliers | array | The material's suppliers: objects with id and name | Example request { "material_id": 2051, "storage_id": 3998 } Example response { "success": true, "material": { "id": 2051, "name": "Oak board", "sku": "M010", "price": 135000, "notes": "", "archived": 0, "stock": 4.2, "minimum": 1, "planned": null, "unit": "cu m", "categories": [ { "id": 12, "name": "Wood" } ], "suppliers": [ { "id": 45, "name": "Woodtrade Ltd" } ] } } Errors | Error | Reason | |---|---| | No material_id in input | A required field is missing (instead of material_id, the field's name) | | Storage ID not found | Storage location not found or deleted | | Material not found or access denied | Material not found, deleted or not stocked at the storage location |

Material Stock Across Storage Locations

Returns material stock across all storage locations as a single list: one row per «material, storage location» pair where the material is stocked. v1/materials/get_stocks.php Parameters | Field | Type | Required | Description | |---|---|---|---| | material_ids | array | No | Material IDs. Without them, all materials are returned | | storage_ids | array | No | Only these storage locations. Without them, all storage locations | | limit | int | No | Page size, from 1 to 1000 | | offset | int | No | How many records to skip | Rows are sorted by material ID and storage location ID. Deleted materials and storage locations are not included. Example request { "material_ids": [2051, 2052] } Example response { "success": true, "stocks": [ { "material_id": 2051, "storage_id": 3998, "stock": 4.2, "minimum": 1, "planned": null }, { "material_id": 2051, "storage_id": 4002, "stock": 0, "minimum": 0, "planned": 1.5 } ], "total": 2 } Errors | Error | Reason | |---|---| | Material_ids is not an array | material_ids was not passed as an array | | Storage_ids is not an array | storage_ids was not passed as an array | | Storage ID not found | Storage location not found or deleted | | Invalid limit value. Must be between 1 and 1000 | Invalid limit |