API Integration
API integration enables full access to Controlata data: manage sales, customers, and products from external systems.
Setting up API integration requires technical knowledge in programming and experience with API interfaces. If you are
not a developer, you will need assistance from a technical specialist to implement the integration.
Integration Setup
1. Go to Controlata settings, find the "Integrations" section and click "Connect" next to "General API"
2. Get your API key for request authorization
3. Configure a prefix for sale numbers (will be added to the beginning of all sales created through API)
Authorization
All requests must include the API key in the Authorization header:
Authorization: your_api_key
Base URLs
All endpoints are located at:
- Customers: https://api.controlata.com/connect/v1/customers/
- Sales: https://api.controlata.com/connect/v1/orders/
- Products: https://api.controlata.com/connect/v1/products/
Request and Response Format
- Method: POST
- Data format: JSON
- Encoding: UTF-8
All responses contain a success field (true/false) and in case of error - an error field with description.
Working with Customers
Create Customer
URL: customers/add.php
Required parameters:
- name (string) - customer name
Optional parameters:
- email (string) - email address
- phone (string) - phone number
- address_legal (string) - legal address
- address_real (string) - delivery address
- agreement (string) - agreement number
- manager_name (string) - manager name
- manager_post (string) - manager position
- notes (string) - notes
Example request:
{
"name": "Acme Corp",
"email": "[email protected]",
"phone": "+1 (555) 123-4567"
}
Example response:
{
"success": true,
"customer_id": 123
}
Edit Customer
URL: customers/edit.php
Required parameters:
- customer_id (int) - customer ID
- name (string) - customer name
Optional parameters are the same as for creating a customer.
Important: If an optional parameter is not included in the request, the existing value will be replaced with empty.
Delete Customer
URL: customers/delete.php
Required parameters:
- customer_id (int) - customer ID
Get Customer List
URL: customers/get_list.php
No parameters required.
Example response:
{
"success": true,
"customers": [
{
"id": 123,
"name": "Acme Corp",
"email": "[email protected]",
"phone": "+1 (555) 123-4567",
"notes": ""
}
]
}
Get Customer Details
URL: customers/get_entry.php
Required parameters:
- customer_id (int) - customer ID
Working with Sales
Create Sale
URL: orders/add.php
Required parameters:
- num (string) - sale number
- products (array) - array of products:
- sku (string) - product SKU
- amount (float) - quantity
- total (float) - total amount (price × quantity)
Customer (one of the options):
- customer_id (int) - ID of existing customer
- customer_name (string) - name of new customer
Optional parameters:
- customer_email, customer_phone, customer_address_real and other customer fields
- storage_id (int) - storage location ID (if not specified, default sales storage location is used)
- date_placed (string) - sale date in YYYY-MM-DD format (if not specified, current date is used)
- date_shipped (string) - shipped date in YYYY-MM-DD format
- delivery_price (float) - delivery cost
- discount (float) - discount amount
- production (int) - 1 to create production, 0 to fulfill from inventory
- notes (string) - notes
Example request:
{
"num": "1001",
"customer_name": "John Smith",
"customer_email": "[email protected]",
"delivery_price": 25,
"discount": 5,
"products": [
{
"sku": "A001",
"amount": 2,
"total": 180
},
{
"sku": "A002",
"amount": 1,
"total": 100
}
]
}
Example response:
{
"success": true,
"order_id": 456,
"customer_id": 789
}
Edit Sale
URL: orders/edit.php
Required parameters:
- order_id (int) - sale ID
- num (string) - sale number
- products (array) - array of products
Optional parameters are the same as for creating a sale.
Important: If an optional parameter is not included in the request, the existing value will be replaced with empty.
Update Sale Status
URL: orders/update_status.php
Required parameters:
- order_id (int) - sale ID
- status (int) - new status (0 = new, 1 = packed, 3 = shipped, 4 = canceled)
Optional parameters:
- date_shipped (string) - shipped date in YYYY-MM-DD format, can be specified when transitioning sale to shipped
status
Update Payment Status
URL: orders/update_payment.php
Required parameters:
- order_id (int) - sale ID
- status (int) - payment status (0 = unpaid, 1 = partially paid, 2 = paid)
Delete Sale
URL: orders/delete.php
Required parameters:
- order_id (int) - sale ID
Get Sales List
URL: orders/get_list.php
Optional parameters:
- date_from (string) - from date in YYYY-MM-DD format
- date_to (string) - to date in YYYY-MM-DD format
Get Sale Details
URL: orders/get_entry.php
Required parameters:
- order_id (int) - sale ID
Example response:
{
"success": true,
"order": {
"id": "31591",
"num": "103",
"status": "0",
"payment": "0",
"date_placed": "2025-08-09",
"date_shipped": "2025-08-11",
"subtotal": "4800.00",
"delivery_price": "0.00",
"discount": "0.00",
"total": "4800.00",
"cost": "2294.00",
"notes": "",
"amount": "6.000",
"lines": "3",
"source": "api",
"production": "0",
"production_num": null,
"customer_id": "4877",
"customer_name": "John Smith",
"customer_email": "[email protected]",
"customer_phone": "",
"customer_address_real": "",
"customer_address_legal": "",
"customer_agreement": "",
"customer_manager_name": "",
"customer_manager_post": "",
"customer_notes": "",
"storage_id": "3998",
"storage_name": "Main",
"products": [
{
"id": "48390",
"sku": "F003",
"name": "Oak Dining Chair",
"amount": "4",
"unit": "pcs",
"total": "1800",
"price": "450",
"cost": "995.20",
"position": "0"
}
]
}
}
Working with Products
Create Product
URL: products/add.php
Required parameters:
- name (string) - product name
- unit (string) - unit of measure (see list below)
- storage_id (int) - storage location ID
Optional parameters:
- sku (string) - product SKU
- price (float) - sales price
- batch_size (float) - batch size (default: 1)
- stock (float) - initial stock level
- minimum (float) - minimum stock level
- notes (string) - notes
Example request:
{
"name": "Product 1",
"sku": "PROD001",
"unit": "pcs",
"price": 90,
"storage_id": 1,
"stock": 10,
"minimum": 5
}
Edit Product
URL: products/edit.php
Required parameters:
- product_id (int) - product ID
- name (string) - product name
- unit (string) - unit of measure (see list below)
- storage_id (int) - storage location ID
Optional parameters: Other parameters are the same as for creating a product.
Important: If an optional parameter is not included in the request, the existing value will be replaced with empty.
Update Stock Levels
URL: products/update_stock.php
Required parameters:
- product_id (int) - product ID
- storage_id (int) - storage location ID
- stock (float) - new stock quantity
Optional parameters:
- notes (string) - adjustment notes
Delete Product
URL: products/delete.php
Required parameters:
- product_id (int) - product ID
Get Products List
URL: products/get_list.php
Required parameters:
- storage_id (int) - storage location ID
Get Product Details
URL: products/get_entry.php
Required parameters:
- product_id (int) - product ID
- storage_id (int) - storage location ID
Available Units of Measure
When working with products, you can use the following units of measure:
Quantity and Weight:
- pcs - pieces
- kg - kilograms
- lbs - pounds
- oz - ounces
- g - grams
- mg - milligrams
- t - tons
- ct - carats
- pkg - packages
- set - sets
Volume:
- L - liters
- ml - milliliters
- gal - gallons
- fl oz - fluid ounces
Length and Area:
- m - meters
- cm - centimeters
- mm - millimeters
- km - kilometers
- in - inches
- ft - feet
- yd - yards
- sq m - square meters
- sq cm - square centimeters
- sq ft - square feet
- cu m - cubic meters
- cu cm - cubic centimeters
- cu ft - cubic feet
Finding storage_id
When creating products or sales, you may need the storage location identifier storage_id. Currently, we don't have
endpoints for getting the list of storage locations, but you can find the storage_id of existing locations in the system
by:
1. Going to the storage locations section
2. Opening the required storage location
3. Taking the storage_id from the browser address bar: https://app.controlata.com/storages/item/[storage_id]
Error Handling
In case of error, the API returns JSON with fields:
- success: false
- error: error description
Example errors:
{
"success": false,
"error": "Product not found or access denied"
}
Common errors:
- 401 Unauthorized - invalid API key
- Customer not found - customer not found
- All products have wrong SKU - all products have invalid SKU
- Invalid status value - invalid status value
Special Features
- Product matching is done by SKU. First, search is performed by main product SKU, if not found - by alternative SKUs.
If a product is not found, it is skipped, but the sale is created with the remaining products.
- Logging: All requests are logged for debugging and monitoring.
- Sale prefixes: The sale number prefix from integration settings is automatically added to the sale number.
