Authentication

Every Web API request must include your API key. Create keys in Admin → API.

Supported Methods (use one)

Method	Example
Header (recommended)	`X-API-Key: YOUR_API_KEY`
Bearer token	`Authorization: Bearer YOUR_API_KEY`
Query string	`?api_key=YOUR_API_KEY`

Important: Never expose the API key in client-side JavaScript or mobile apps. Call the API only from your server.

Permission matrix

Permission key	Description	Example endpoints
`orders.read`	Read / pull orders	`GET /orders`, `GET /orders/{id}`
`orders.write`	Update orders / invoice	`PATCH /orders/{id}`, invoice
`products.read`	Read products	`GET /products`, `GET /products/{id}`
`products.create`	Create products	`POST /products`
`products.update`	Update product / stock / image	`PATCH`, `/quick`, `/image`
`products.delete`	Delete products	`DELETE /products/{id}`
`categories.read`	Read categories	`GET /categories`
`brands.read`	Read brands	`GET /brands`

Recommended key setups

ERP / stock: products.read + products.update (+ create if needed)
Marketplace / shipping: orders.read + orders.write
Read-only reporting: *.read permissions only

Rate limit

Successful requests are limited to roughly 300 per 15 minutes per IP. Failed auth attempts can be locked separately. Exceeding limits may return 429 — see API Conventions.

Common errors

Status	Likely cause
`403` Web API disabled	Web API off in Admin → API
`403` Invalid key / permission	Wrong key or missing permission
`503`	No API key configured

Note: Storefront AJAX endpoints (/api/cart.php, etc.) do not use API keys; they use customer session + CSRF. See Storefront AJAX API. Cron jobs use SHOP_TOKEN — Cron.

PHP

<?php

$baseUrl = 'https://example.com/api/v1';
$apiKey  = 'YOUR_API_KEY'; // Admin → API

function apiRequest(string $method, string $url, string $apiKey, ?array $data = null): array
{
    $ch = curl_init();

    $headers = [
        'X-API-Key: ' . trim($apiKey),
        'Accept: application/json',
    ];

    if ($data !== null) {
        $headers[] = 'Content-Type: application/json';
    }

    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_SSL_VERIFYPEER => true,
    ]);

    if ($data !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data, JSON_UNESCAPED_UNICODE));
    }

    $response = curl_exec($ch);
    $httpCode = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error = curl_error($ch);
    curl_close($ch);

    $decoded = json_decode((string) $response, true);

    return [
        'http_code' => $httpCode,
        'curl_error' => $error,
        'response' => is_array($decoded) ? $decoded : $response,
    ];
}

// Connection check — categories
$result = apiRequest('GET', $baseUrl . '/categories', $apiKey);
print_r($result);

cURL

curl -s -H "X-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  "https://example.com/api/v1/categories"

Sample Response (JSON)

{
  "totalElements": 4,
  "content": [
    {
      "id": 3,
      "name": "Vitamin & Takviye",
      "slug": "vitamin-takviye",
      "parentId": 1,
      "parentName": "Sağlık",
      "active": true
    }
  ]
}