Opencart REST API
Документація

Advanced API для OpenCart

Розширений REST API з HMAC-захистом: товари, категорії, замовлення, покупці, вебхуки та масова синхронізація. Нижче — усе для швидкого старту.

Зміст сторінки

Огляд

Advanced API надає доступ до основних сутностей магазину OpenCart через захищені HTTP-запити. Кожен запит підписується алгоритмом HMAC-SHA256 — секрет ніколи не передається мережею.

Базовий URL

https://your-store.com/index.php?route=api/advanced_api/{ресурс}

19
ресурсів
~68
ендпоінтів
OpenAPI 3.0
+ Postman

Встановлення

  1. 1

    Скопіюйте вміст папки upload/ до кореневої директорії OpenCart.

  2. 2

    В адмін-панелі: Розширення → Модулі → Advanced API — встановіть модуль.

  3. 3

    Створіть API-ключ у налаштуваннях модуля (поля api_key та api_secret).

  4. 4

    За потреби вкажіть дозволені IP (ip_whitelist, через кому) та ліміт запитів за хвилину на ключ (0 — без обмежень; перевищення → 429).

  5. 5

    Активуйте ліцензійний ключ на вкладці «Інформація» (прив'язується до домену магазину).

Важливо: без активованого дійсного ліцензійного ключа зберегти налаштування модуля неможливо — спершу активуйте ліцензію на вкладці «Інформація».

Права доступу ключа

Для кожного API-ключа окремо (у модальному вікні ключа):

  • «Дозволити DELETE» — якщо вимкнено, ключ не може викликати жоден DELETE (запити повертають 403).

  • «Області доступу» (scopes) — візуальна матриця ресурс × дія (Читання / Створення / Оновлення / Видалення). Заборонені запити повертають 403.

Технічно scopes зберігаються як компактний рядок токенів (*, product, order:post, *:get), але редагувати їх зручно через матрицю — рядок формується автоматично.

Аутентифікація

Кожен запит (крім OPTIONS) повинен містити три HTTP-заголовки:

ЗаголовокОпис
X-Api-KeyПублічний ідентифікатор ключа
X-Api-TimestampUnix-час (секунди). Відхилення від серверного часу — не більше ±300 с
X-Api-SignatureHMAC-SHA256 підпис, hex-encoded

Алгоритм підпису

algorithm
string_to_sign = METHOD + "\n" + REQUEST_URI + "\n" + TIMESTAMP + "\n" + md5(raw_body)
signature      = HMAC-SHA256(api_secret, string_to_sign)
  • METHOD — HTTP-метод у верхньому регістрі (GET, POST, PUT…).
  • REQUEST_URI — повний URI, включно з query-рядком.
  • md5(raw_body) — md5 тіла запиту (для GET — md5 порожнього рядка).

Приклад на PHP

php
$method    = 'GET';
$uri       = '/index.php?route=api/advanced_api/product';
$timestamp = time();
$body      = '';

$string_to_sign = $method . "\n" . $uri . "\n" . $timestamp . "\n" . md5($body);
$signature      = hash_hmac('sha256', $string_to_sign, $api_secret);

Приклад на cURL

bash
API_KEY="your_api_key"
API_SECRET="your_api_secret"
TIMESTAMP=$(date +%s)
METHOD="GET"
URI="/index.php?route=api/advanced_api/product"
BODY=""

STRING_TO_SIGN="${METHOD}\n${URI}\n${TIMESTAMP}\n$(echo -n "$BODY" | md5sum | cut -d' ' -f1)"
SIGNATURE=$(echo -ne "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$API_SECRET" | sed 's/^.* //')

curl -X GET "https://your-store.com${URI}" \
  -H "X-Api-Key: ${API_KEY}" \
  -H "X-Api-Timestamp: ${TIMESTAMP}" \
  -H "X-Api-Signature: ${SIGNATURE}"

Приклад на Node.js

javascript
const crypto = require('crypto');

const apiKey    = 'your_api_key';
const apiSecret = 'your_api_secret';
const method    = 'GET';
const uri       = '/index.php?route=api/advanced_api/product';
const timestamp = Math.floor(Date.now() / 1000);
const body      = '';

const bodyHash     = crypto.createHash('md5').update(body).digest('hex');
const stringToSign = [method, uri, timestamp, bodyHash].join('\n');
const signature    = crypto.createHmac('sha256', apiSecret).update(stringToSign).digest('hex');

const res = await fetch('https://your-store.com' + uri, {
  method,
  headers: {
    'X-Api-Key': apiKey,
    'X-Api-Timestamp': String(timestamp),
    'X-Api-Signature': signature
  }
});
console.log(await res.json());

Обхід заборони методів

Деякі хостинги блокують DELETE та PUT. Щоб виконати їх через POST, додайте параметр method (або заголовок X-HTTP-Method-Override):

http
POST /index.php?route=api/advanced_api/product&id=42&method=delete   # = DELETE
POST /index.php?route=api/advanced_api/product&id=42&method=put      # = PUT

Підпис не змінюється: підписуйте реальний метод (POST), а &method=… вже входить до REQUEST_URI, який хешується. Перевірки «Дозволити DELETE» та scopes діють так само, ніби це справжній DELETE.

Пагінація та сортування

Більшість GET-списків підтримують query-параметри:

ПараметрТипЗа замовч.Опис
pageint1Номер сторінки
limitint20Записів на сторінку (макс. 200)
sortstringзалежитьПоле сортування
orderstringASCASC або DESC
searchstringПошук за назвою

Коди відповідей

КодЗначення
200Успіх
201Запис створено
400Невірний запит (відсутні/невалідні параметри)
401Помилка аутентифікації
403Доступ заборонено (DELETE вимкнено / scope)
404Запис не знайдено
405Метод не підтримується
429Перевищено ліміт запитів

Формат помилки

json
{
  "success": false,
  "error": "..."
}

Ресурси

19 ресурсів за єдиним шаблоном URL. Повний перелік методів, параметрів і схем — у Redoc-довідці.

РесурсМетодиОпис
productGET POST PUT DELETEТовари + full, bulk_stock, specials, discounts, зв'язки
categoryGET POST PUT DELETEКатегорії
orderGET POST PUTЗамовлення + історія статусів
order_statusGET POST PUT DELETEДовідник статусів замовлень
returnGET POST PUT DELETEПовернення + довідники
localizationGETМови, валюти, країни, зони, класи, податки
manufacturerGET POST PUT DELETEВиробники
attributeGET POST PUT DELETEАтрибути
attribute_groupGET POST PUT DELETEГрупи атрибутів
optionGET POST PUT DELETEОпції та значення
storeGETМагазини
customerGET POST PUT DELETEПокупці + групи
informationGET POST PUT DELETEІнформаційні сторінки
reviewGET POST PUT DELETEВідгуки
couponGET POST PUT DELETEКупони
seo_urlGET POST PUT DELETEЧПУ (SEO URL)
webhookGET POST PUT DELETEПідписки на події + events
imagePOSTЗавантаження зображень (multipart)
ping · specGETHealth-check та OpenAPI-специфікація

Масова синхронізація (bulk_stock)

Оновлює залишки, ціни та інші поля багатьох товарів одним запитом — для синхронізації з ERP. Елемент ідентифікується за product_id, потім sku, потім model. Оновлюються лише передані поля. Максимум 500 елементів.

json · request
POST /index.php?route=api/advanced_api/product&action=bulk_stock

{
  "items": [
    { "product_id": 42, "quantity": 100, "price": 199.99 },
    { "sku": "SKU-001", "quantity": 0, "status": 0 },
    { "model": "PROD-XYZ", "price": 349.50, "stock_status_id": 7 }
  ]
}
json · response 200
{
  "success": true,
  "updated": 2,
  "skipped": 0,
  "not_found": 1,
  "results": [
    { "product_id": 42, "status": "updated" },
    { "sku": "SKU-001", "status": "updated" },
    { "model": "PROD-XYZ", "status": "not_found" }
  ]
}

Оновлювані поля: quantity, price, status, stock_status_id, subtract, minimum, points, weight, sku, model, upc, ean, location, date_available.

Вебхуки

Підписки на події магазину. Коли подія стається, модуль надсилає підписаний POST на ваш URL. Доставка синхронна, best-effort, з коротким тайм-аутом — повільний підписник не блокує API.

Події: order.add, order.status, product.add, product.update, product.delete, customer.add. Значення * підписує на всі.

json · payload
POST {your_url}
X-Webhook-Event: order.status
X-Webhook-Signature: {HMAC-SHA256(raw_body, secret)}

{
  "event": "order.status",
  "timestamp": 1712345678,
  "data": { "order_id": 1024, "order_status_id": 3 }
}

Перевірка на приймачі: обчисліть HMAC-SHA256(raw_body, secret) і порівняйте з заголовком X-Webhook-Signature.

Службові ендпоінти

GET …/ping

Легка перевірка доступності API (health-check). Повертає статус, час і таймзону.

GET …/spec

Повний документ OpenAPI 3.0 (JSON) — усі ресурси, методи, параметри та схеми. Придатний для генерації клієнтів.

Інструменти розробника

У Postman задайте змінні base_url, api_key, api_secret — pre-request скрипт колекції сам обчислить X-Api-Timestamp та X-Api-Signature. Підписувати вручну не потрібно.

Готові підключити магазин?

Відкрийте інтерактивну довідку або поверніться на головну, щоб придбати модуль.