Resources

Resources

Resources: everything used in production that is not a material. For example, staff labor, electricity, equipment or overhead. Resources go into a product's components and count towards its cost; they have no stock at storage locations. Via the API you can create, edit and delete them, and get a list and a resource's details. 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/resources/add | Creates a resource | | v1/resources/edit | Updates a resource | | v1/resources/delete | Deletes a resource | | v1/resources/get_list | Returns the company's resources | | v1/resources/get_entry | Returns a resource's details |

Creating a Resource

Creates a resource. The set of required fields depends on the calculation type. v1/resources/add.php Parameters | Field | Type | Required | Description | |---|---|---|---| | name | string | Yes | Name | | type | string | Yes | Calculation type: "rate", "percent" or "amortized" | | dynamic | int | No | 1: the price of a fixed rate or the percentage of a percentage resource is specified in the product components. Default 0. Not used for depreciation | | unit | string | For rate and amortized | Unit of measure, a code from Units of Measure. Not needed for a rate with dynamic 1 | | price | float | For rate | Price per unit. Not needed for a rate with dynamic 1 | | base | string | For percent | Calculation basis: "cost" or "price" | | percent | float | For percent | Percentage. Not needed with dynamic 1 | | initial_cost | float | For amortized | Initial cost | | useful_life | float | For amortized | Useful life, in unit units | | notes | string | No | Notes | | categories | array | No | Categories: objects with id or name | A category can be passed by name: if there is no such category, it is created. The IDs of existing categories are returned by v1/categories/get_list. Resource types The calculation type determines which fields are needed when creating a resource. | Type | Description | Required fields | |---|---|---| | "rate", Fixed rate | Labor, electricity, contract manufacturing | unit, price | | "rate" with dynamic 1, Price specified in the product components | The amount is set in each product's components | None | | "percent", Percentage | Overhead, commissions | base, percent | | "percent" with dynamic 1, Percentage specified in the product components | The percentage is set in each product's components | base | | "amortized", Depreciation | Equipment, vehicles, tools | unit, initial_cost, useful_life | The calculation basis (base) of a percentage resource: - "cost": the product cost without percentage resources; - "price": the sale price from the product card. Units of measure A resource can use any unit, including the time and energy units available to resources only: "h", "min", "kWh". See the full list in Units of Measure. Example requests A fixed rate: a carpenter's hourly rate. { "name": "Carpenter's work", "type": "rate", "unit": "h", "price": 600, "categories": [{ "id": 31 }] } A percentage of cost, the same for all products: { "name": "Overhead", "type": "percent", "base": "cost", "percent": 10 } A marketplace commission whose percentage is set in each product's components: { "name": "Marketplace commission", "type": "percent", "dynamic": 1, "base": "price" } Equipment depreciation: { "name": "Milling machine", "type": "amortized", "unit": "h", "initial_cost": 600000, "useful_life": 2000 } Example response { "success": true, "resource_id": 57 } Errors | Error | Reason | |---|---| | No name in input | A required field is missing (instead of name, the field's name: type or a field required for the type) | | Name must not be empty | Empty name | | Name must be a string | Name passed not as a string, e.g. as an array | | Invalid type value. Must be one of: rate, percent, amortized | Invalid type | | Unit not set | An empty unit of measure was passed | | Unit not found | Unknown unit of measure | | Invalid price value. Must be a number, 0 or greater | Price is not a number or below 0 (same for initial_cost) | | Invalid base value. Must be one of: cost, price | Invalid calculation basis | | Percent must be greater than 0 and not exceed 100 | Percentage is 0, below 0 or above 100 | | Useful life must be greater than 0 | Useful life is 0 or less | | Category 12 not found | Category not found |

Editing a Resource

Updates a resource. Only the fields you pass are changed, the rest stay as they were. v1/resources/edit.php Parameters | Field | Type | Required | Description | |---|---|---|---| | resource_id | int | Yes | Resource ID | | name | string | No | Name | | type | string | No | Calculation type: "rate", "percent" or "amortized" | | dynamic | int | No | 1: the price or percentage is specified in the product components | | unit | string | No | Unit of measure. Used only for a fixed rate and depreciation | | price | float | No | Price per unit | | base | string | No | Calculation basis: "cost" or "price" | | percent | float | No | Percentage | | initial_cost | float | No | Initial cost | | useful_life | float | No | Useful life, in the resource's units | | notes | string | No | Notes | | categories | array | No | Categories: objects with id or name. Replace the current ones as a whole | Which fields each type needs is described in Creating a Resource. When changing type, pass the fields the resource does not have yet: unit for a fixed rate and depreciation, base and percent for a percentage, initial_cost and useful_life for depreciation. The resource's quantity in product components is not recalculated, so check it after the change. For a resource that has already been consumed in production, the calculation type cannot be changed, and for a depreciated resource the initial cost, useful life and unit cannot either. The other fields can be changed. Example request { "resource_id": 57, "price": 650 } Example response { "success": true } Errors | Error | Reason | |---|---| | No resource_id in input | resource_id is missing | | Resource not found or access denied | Resource not found or deleted | | Name must not be empty | An empty name was passed | | Name must be a string | Name passed not as a string, e.g. as an array | | Invalid type value. Must be one of: rate, percent, amortized | Invalid type | | No unit in input | Type changed to a fixed rate or depreciation, but the resource has no unit | | Unit not set | An empty unit of measure was passed | | Unit not found | Unknown unit of measure | | Unit cannot be changed to another unit group: the resource is used in components of products | Changing the unit group of a resource used in product components | | Invalid price value. Must be a number, 0 or greater | Price is not a number or below 0 (same for initial_cost) | | Invalid base value. Must be one of: cost, price | Invalid calculation basis, or it was not passed when changing the type to percentage | | Percent must be greater than 0 and not exceed 100 | Percentage out of range, or not passed when changing the type to percentage | | Useful life must be greater than 0 | Useful life is 0 or less, or not passed when changing the type to depreciation | | The resource is already used in production, so these fields cannot be changed: type, useful_life | The resource has already been consumed in production. The fields that cannot be changed are listed at the end: type, initial_cost, useful_life, unit | | Category 12 not found | Category not found |

Deleting a Resource

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

Retrieving a List of Resources

Returns the company's resources, sorted by name. Archived resources are included too. v1/resources/get_list.php Parameters | Field | Type | Required | Description | |---|---|---|---| | 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 resources with the resource's fields and its categories. The total field holds the total number of resources. | Field | Type | Description | |---|---|---| | id | int | Resource ID | | name | string | Name | | type | string | Calculation type: "rate", "percent" or "amortized" | | dynamic | int | 1 if the price or percentage is specified in the product components | | base | string | Calculation basis of a percentage resource: "cost" or "price". null for other types | | unit | string | Unit of measure, a code from Units of Measure. Present only for a fixed rate and depreciation, null for the rest | | price | float | Price per unit | | percent | float | Percentage of a percentage resource | | initial_cost | float | Initial cost of the equipment | | useful_life | float | Useful life, in the resource's units | | left_life | float | Remaining useful life. Decreases when the resource is consumed in production | | notes | string | Notes | | archived | int | 1 if the resource is archived | | categories | array | The resource's categories: objects with id and name | Example request { "limit": 100, "offset": 0 } Example response { "success": true, "resources": [ { "id": 57, "name": "Carpenter's work", "type": "rate", "dynamic": 0, "base": null, "unit": "h", "price": 600, "percent": 0, "initial_cost": 0, "useful_life": 0, "left_life": 0, "notes": "", "archived": 0, "categories": [ { "id": 31, "name": "Staff" } ] }, { "id": 59, "name": "Milling machine", "type": "amortized", "dynamic": 0, "base": null, "unit": "h", "price": 300, "percent": 0, "initial_cost": 600000, "useful_life": 2000, "left_life": 1874.5, "notes": "", "archived": 0, "categories": [] } ], "total": 2 } Errors | Error | Reason | |---|---| | Invalid limit value. Must be between 1 and 1000 | Invalid limit | | Invalid offset value. Must be 0 or greater | Invalid offset | | Offset requires limit | offset passed without limit |

Retrieving a Resource

Returns a resource's details. v1/resources/get_entry.php Parameters | Field | Type | Required | Description | |---|---|---|---| | resource_id | int | Yes | Resource ID | Response An object resource with the resource's fields and its categories. The categories from the response can be sent to v1/resources/edit unchanged. | Field | Type | Description | |---|---|---| | id | int | Resource ID | | name | string | Name | | type | string | Calculation type: "rate", "percent" or "amortized" | | dynamic | int | 1 if the price or percentage is specified in the product components | | base | string | Calculation basis of a percentage resource: "cost" or "price". null for other types | | unit | string | Unit of measure, a code from Units of Measure. Present only for a fixed rate and depreciation, null for the rest | | price | float | Price per unit | | percent | float | Percentage of a percentage resource | | initial_cost | float | Initial cost of the equipment | | useful_life | float | Useful life, in the resource's units | | left_life | float | Remaining useful life. Decreases when the resource is consumed in production | | notes | string | Notes | | archived | int | 1 if the resource is archived | | categories | array | The resource's categories: objects with id and name | Example request { "resource_id": 58 } Example response { "success": true, "resource": { "id": 58, "name": "Overhead", "type": "percent", "dynamic": 0, "base": "cost", "unit": null, "price": 0, "percent": 10, "initial_cost": 0, "useful_life": 0, "left_life": 0, "notes": "", "archived": 0, "categories": [] } } Errors | Error | Reason | |---|---| | No resource_id in input | resource_id is missing | | Resource not found or access denied | Resource not found or deleted |