Audits

Audits

Audits: reconciling the actual stock at a storage location with the stock in Controlata. You pass the actual quantity, and Controlata compares it with the expected stock and adjusts the stock by the difference. Via the API you can create, edit and delete audits, change their status, and get a list and an audit'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/audits/add | Creates an audit | | v1/audits/edit | Updates the audit lines | | v1/audits/delete | Deletes an audit | | v1/audits/update_status | Changes the audit status | | v1/audits/get_list | Returns the list of audits | | v1/audits/get_entry | Returns an audit with its lines |

Creating an Audit

Creates an audit of materials or products at a storage location. Pass only the actual stock: Controlata calculates the expected stock on the audit date. v1/audits/add.php Parameters | Field | Type | Required | Description | |---|---|---|---| | storage_id | int | Yes | Storage location the audit is carried out at | | materials | array | materials or products | Audit lines for materials | | products | array | materials or products | Audit lines for products | | date | string | No | Audit date, YYYY-MM-DD. Default today | materials and products line: | Field | Type | Required | Description | |---|---|---|---| | id | int | id or sku | Material or product ID | | sku | string | id or sku | SKU | | actual | float | Yes | Actual stock, 0 or greater | | notes | string | No | Line notes | Lines are passed in one array only: an audit counts either materials or products. The number is assigned automatically. A new audit is created with the status from the Default status for new audits setting. Example request { "storage_id": 3998, "date": "2026-09-30", "materials": [ { "id": 2051, "actual": 3.8 }, { "sku": "M022", "actual": 0, "notes": "Not found at the storage location" } ] } Example response { "success": true, "audit_id": 1699, "num": 24, "status": 1 } The response returns the ID, number and status code of the new audit. The expected stock and the per-line difference are returned by v1/audits/get_entry. Errors | Error | Reason | |---|---| | No storage_id in input | storage_id is missing | | Storage ID is not set | storage_id is 0 or empty | | Storage ID not found | Storage location not found or deleted | | Storage location 4001 does not store materials | The storage location does not store items of the audit type (for products: does not store products) | | An audit counts either materials or products. Create separate audits | Both materials and products were passed | | No products or materials in input | No line was passed | | Materials is not an array | materials is not an array (same for products) | | Line 0 of materials must be an object | The line is not an object (instead of 0, the line number) | | SKU or id not set for material 0 | The line has neither id nor sku | | Material with id 2051 not found | Material not found or deleted (for a SKU: Material with SKU "M022" not found) | | Actual must be 0 or greater for material with id 2051 | actual is missing, not a number or below 0 | | Material with id 2051 is listed twice | The item is listed in two lines | | Date is not a valid date in format YYYY-MM-DD | Invalid date format |

Editing an Audit

Updates the audit lines. The audit's date, storage location and type do not change. v1/audits/edit.php Parameters | Field | Type | Required | Description | |---|---|---|---| | audit_id | int | Yes | Audit ID | | materials | array | No | Material audit lines: id or sku, actual, notes | | products | array | No | Product audit lines: id or sku, actual, notes | Lines are passed as in v1/audits/add, and only in the array of the type the audit counts. Lines are replaced as a whole. Example request { "audit_id": 1699, "materials": [ { "id": 2051, "actual": 4 }, { "sku": "M022", "actual": 0, "notes": "Not found at the storage location" } ] } Example response { "success": true } Errors | Error | Reason | |---|---| | No audit_id in input | audit_id is missing | | Audit not found or access denied | Audit not found or deleted | | This audit counts materials. Its type cannot be changed | Lines were passed in the array of the other type (for products: This audit counts products) | | An audit counts either materials or products. Create separate audits | Both materials and products were passed | | No products or materials in input | The line arrays were passed but empty | | Material with id 2051 not found | Material not found or deleted | | Actual must be 0 or greater for material with id 2051 | actual is missing, not a number or below 0 | | Material with id 2051 is listed twice | The item is listed in two lines | Other line errors are the same as in v1/audits/add.

Deleting an Audit

Deletes an audit. v1/audits/delete.php Parameters | Field | Type | Required | Description | |---|---|---|---| | audit_id | int | Yes | Audit ID | Deletion cannot be undone. The audit's adjustments are reversed: surpluses are removed from stock and shortages are returned to it. Example request { "audit_id": 1699 } Example response { "success": true } Errors | Error | Reason | |---|---| | No audit_id in input | audit_id is missing | | Audit not found or access denied | Audit not found or already deleted |

Changing the Audit Status

Changes the audit status. The status determines whether the stock is adjusted at the storage location. v1/audits/update_status.php Parameters | Field | Type | Required | Description | |---|---|---|---| | audit_id | int | Yes | Audit ID | | status | int | Yes | New status: 0 — Planned, 1 — Completed | Example request { "audit_id": 1699, "status": 1 } Example response { "success": true } Errors | Error | Reason | |---|---| | No audit_id in input | A required field is missing (instead of audit_id, the field's name) | | Invalid status value. Must be one of: 0, 1 | Invalid status code | | Audit not found or access denied | Audit not found or deleted |

Retrieving a List of Audits

Returns the company's audits, from newest to oldest: by date, and within one date by number. Lines are not included in the list; they are returned by v1/audits/get_entry. v1/audits/get_list.php Parameters | Field | Type | Required | Description | |---|---|---|---| | storage_id | int | No | Only audits of this storage location | | date_from | string | No | Audits from this date inclusive, YYYY-MM-DD | | date_to | string | No | Audits up to this date inclusive, YYYY-MM-DD | | status | int | No | Status: 0 Planned, 1 Completed | | 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 audits with the audit's fields: | Field | Type | Description | |---|---|---| | id | int | Audit ID | | num | int | Number. Assigned automatically | | date | string | Audit date, YYYY-MM-DD | | status | int | Status: 0 Planned, 1 Completed | | storage_id | int | Storage location the audit is carried out at | | storage_name | string | Storage location name | | lines | int | Number of lines | | surplus_cost | float | Surpluses at cost | | shortage_cost | float | Shortages at cost, a negative number | | total_cost | float | Total at cost: surplus_cost plus shortage_cost | | surplus_price | float | Surpluses at sale price. Products only, 0 for materials | | shortage_price | float | Shortages at sale price, a negative number. Products only | | total_price | float | Total at sale price: surplus_price plus shortage_price | The total field holds the total number of audits matching the filters. Example request { "storage_id": 3998, "date_from": "2026-01-01", "limit": 100, "offset": 0 } Example response { "success": true, "audits": [ { "id": 1699, "num": 24, "date": "2026-09-30", "status": 1, "storage_id": 3998, "storage_name": "Main", "lines": 2, "surplus_cost": 0, "shortage_cost": -57900, "total_cost": -57900, "surplus_price": 0, "shortage_price": 0, "total_price": 0 } ], "total": 1 } Errors | Error | Reason | |---|---| | Date is not a valid date in format YYYY-MM-DD | Invalid date_from or date_to | | Invalid status value. Must be a number | status is not a number | | Invalid limit value. Must be between 1 and 1000 | Invalid limit | | Offset requires limit | offset passed without limit |

Retrieving an Audit

Returns an audit with its lines: the expected and actual stock and the difference for each item. v1/audits/get_entry.php Parameters | Field | Type | Required | Description | |---|---|---|---| | audit_id | int | Yes | Audit ID | Response An object audit with the audit's fields: | Field | Type | Description | |---|---|---| | id | int | Audit ID | | num | int | Number. Assigned automatically | | date | string | Audit date, YYYY-MM-DD | | status | int | Status: 0 Planned, 1 Completed | | storage_id | int | Storage location the audit is carried out at | | storage_name | string | Storage location name | | lines | int | Number of lines | | surplus_cost | float | Surpluses at cost | | shortage_cost | float | Shortages at cost, a negative number | | total_cost | float | Total at cost: surplus_cost plus shortage_cost | | surplus_price | float | Surpluses at sale price. Products only, 0 for materials | | shortage_price | float | Shortages at sale price, a negative number. Products only | | total_price | float | Total at sale price: surplus_price plus shortage_price | And lines in two arrays: materials and products. Only the array of the type the audit counts is filled; the other comes empty. | Field | Type | Description | |---|---|---| | id | int | Material or product ID | | sku | string | SKU | | name | string | Name | | unit | string | Unit of measure | | expected | float | Expected stock on the audit date | | actual | float | Actual stock | | difference | float | Difference: actual minus expected. Positive means a surplus, negative a shortage | | notes | string | Line notes | | position | int | Line number, from 0 | The lines from the response can be sent to v1/audits/edit unchanged: the method takes id, actual and notes from them. Example request { "audit_id": 1699 } Example response { "success": true, "audit": { "id": 1699, "num": 24, "date": "2026-09-30", "status": 1, "storage_id": 3998, "storage_name": "Main", "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": "Oak board", "unit": "cu m", "expected": 4.2, "actual": 3.8, "difference": -0.4, "notes": "", "position": 0 }, { "id": 2077, "sku": "M022", "name": "Furniture varnish", "unit": "L", "expected": 6, "actual": 0, "difference": -6, "notes": "Not found at the storage location", "position": 1 } ], "products": [] } } Errors | Error | Reason | |---|---| | No audit_id in input | audit_id is missing | | Audit not found or access denied | Audit not found or deleted |