Getting Started
By Maxim
By Maxim
Connecting, authorization, request format and reference data
API Overview
The Controlata API lets external systems (a website, CRM, accounting system or marketplace) work with your data in Controlata: manage the catalog of materials, products and resources, create sales, purchases, productions, write-offs, transfers and audits, and read stock levels at storage locations. Connecting requires programming experience and familiarity with APIs. If you are not a developer, hand this documentation to a technical specialist or an AI assistant: every article can be copied as Markdown. Connecting 1. Open Settings → Integrations and click Connect next to General API. 2. Copy the API key. It authorizes every request. 3. If needed, change the Sale number prefix. The default is "A-". Base URL and request format Base API URL: https://api.controlata.com/connect/ In this documentation method paths are given relative to this URL. For example, the method v1/materials/add is called at https://api.controlata.com/connect/v1/materials/add.php. The first path segment is the method version: a new version appears only if the response changes incompatibly, and the old one keeps working. - Every method is called with a POST request. - Request body: JSON in UTF-8, header Content-Type: application/json. The API is meant for requests from your server. Requests from a browser on another domain are rejected with code 401. Authorization Pass the API key in the Authorization header as is, without the word Bearer: Authorization: your_api_key Example request: curl -X POST https://api.controlata.com/connect/v1/storages/get_list.php \ -H "Authorization: your_api_key" \ -H "Content-Type: application/json" \ -d '{}' Responses and errors A successful response has code 200 and a success field equal to true. The other fields depend on the method: { "success": true, "material_id": 2051 } On error, success is false and the error field holds a description in English: { "success": false, "error": "Material not found or access denied" } | HTTP code | When | Response body | |---|---|---| | 200 | Request completed | JSON, success: true | | 400 | Error in the request data: a required field is missing, an invalid value, a record is not found | JSON, success: false | | 401 | API key is missing or invalid | Empty | | 429 | Daily request limit reached | JSON, success: false | | 500 | Internal error | JSON, success: false | If a required field is missing, the error reads «No in input», for example «No material_id in input». The other errors are listed in each method's article. Request limit A company can send up to 10,000 requests per day. Every request with a valid key counts, including those that end in an error. The counter resets once a day, at night. When the limit is exceeded, the API responds with code 429 and the error «Daily connections limit reached». What's next - Common Rules: partial editing, pagination, number precision. - Reference lists integrations usually start with: Categories, Storage Locations, Units of Measure. - Method sections: Materials, Products, Resources, Customers, Sales, Suppliers, Purchases, Production, Write-offs, Transfers, Audits. Controlata keeps a log of API requests. If a request does not work as expected, contact support and include the method and the time of the request.
Common Rules
Rules that work the same way across all API methods. Number precision Quantities are stored with up to 3 decimal places, amounts and prices to the cent. The API rounds incoming values the same way the Controlata interface does: 0.3333 is saved as 0.333, 10.125 as 10.13. A quantity in operation lines must stay above zero after rounding: 0.0004 is rejected. Editing edit methods change only the fields you pass. Only the record ID is required, the other fields keep their current values. - Arrays (operation lines, categories, suppliers, product components) are replaced as a whole when passed. To clear an array, pass an empty array. - If at least one of the materials and products arrays is passed, the operation lines are replaced as a whole, and the array that is not passed is treated as empty. If neither is passed, the lines stay unchanged. For example, to change only a purchase's notes, pass purchase_id and notes: the lines, dates, storage locations and supplier stay as they were. Pagination get_list methods accept optional pagination parameters. Exception: small reference lists (units of measure, categories and storage locations) are always returned in full and do not accept these parameters. | Field | Type | Description | |---|---|---| | limit | int | Page size, from 1 to 1000 | | offset | int | How many records to skip. Passed together with limit | Without limit the whole list is returned. The response has a total field with the total number of records matching the filters. | 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 |