API Integration | Help Center

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

Go to Controlata settings, find the "Integrations" section and click "Connect" next to "General API"
Get your API key for request authorization
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:

Going to the storage locations section
Opening the required storage location
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.