Advanced API для OpenCart
Розширений REST API з HMAC-захистом: товари, категорії, замовлення, покупці, вебхуки та масова синхронізація. Нижче — усе для швидкого старту.
Зміст сторінки
Огляд
Advanced API надає доступ до основних сутностей магазину OpenCart через захищені HTTP-запити. Кожен запит підписується алгоритмом HMAC-SHA256 — секрет ніколи не передається мережею.
Базовий URL
https://your-store.com/index.php?route=api/advanced_api/{ресурс}
Встановлення
- 1
Скопіюйте вміст папки
upload/до кореневої директорії OpenCart. - 2
В адмін-панелі: Розширення → Модулі → Advanced API — встановіть модуль.
- 3
Створіть API-ключ у налаштуваннях модуля (поля
api_keyтаapi_secret). - 4
За потреби вкажіть дозволені IP (
ip_whitelist, через кому) та ліміт запитів за хвилину на ключ (0— без обмежень; перевищення →429). - 5
Активуйте ліцензійний ключ на вкладці «Інформація» (прив'язується до домену магазину).
Важливо: без активованого дійсного ліцензійного ключа зберегти налаштування модуля неможливо — спершу активуйте ліцензію на вкладці «Інформація».
Права доступу ключа
Для кожного API-ключа окремо (у модальному вікні ключа):
- •
«Дозволити DELETE» — якщо вимкнено, ключ не може викликати жоден
DELETE(запити повертають403). - •
«Області доступу» (scopes) — візуальна матриця ресурс × дія (Читання / Створення / Оновлення / Видалення). Заборонені запити повертають
403.
Технічно scopes зберігаються як компактний рядок токенів (*, product, order:post, *:get), але редагувати їх зручно через матрицю — рядок формується автоматично.
Аутентифікація
Кожен запит (крім OPTIONS) повинен містити три HTTP-заголовки:
| Заголовок | Опис |
|---|---|
| X-Api-Key | Публічний ідентифікатор ключа |
| X-Api-Timestamp | Unix-час (секунди). Відхилення від серверного часу — не більше ±300 с |
| X-Api-Signature | HMAC-SHA256 підпис, hex-encoded |
Алгоритм підпису
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
$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
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
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):
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-параметри:
| Параметр | Тип | За замовч. | Опис |
|---|---|---|---|
| page | int | 1 | Номер сторінки |
| limit | int | 20 | Записів на сторінку (макс. 200) |
| sort | string | залежить | Поле сортування |
| order | string | ASC | ASC або DESC |
| search | string | — | Пошук за назвою |
Коди відповідей
| Код | Значення |
|---|---|
| 200 | Успіх |
| 201 | Запис створено |
| 400 | Невірний запит (відсутні/невалідні параметри) |
| 401 | Помилка аутентифікації |
| 403 | Доступ заборонено (DELETE вимкнено / scope) |
| 404 | Запис не знайдено |
| 405 | Метод не підтримується |
| 429 | Перевищено ліміт запитів |
Формат помилки
{
"success": false,
"error": "..."
}
Ресурси
19 ресурсів за єдиним шаблоном URL. Повний перелік методів, параметрів і схем — у Redoc-довідці.
| Ресурс | Методи | Опис |
|---|---|---|
| product | GET POST PUT DELETE | Товари + full, bulk_stock, specials, discounts, зв'язки |
| category | GET POST PUT DELETE | Категорії |
| order | GET POST PUT | Замовлення + історія статусів |
| order_status | GET POST PUT DELETE | Довідник статусів замовлень |
| return | GET POST PUT DELETE | Повернення + довідники |
| localization | GET | Мови, валюти, країни, зони, класи, податки |
| manufacturer | GET POST PUT DELETE | Виробники |
| attribute | GET POST PUT DELETE | Атрибути |
| attribute_group | GET POST PUT DELETE | Групи атрибутів |
| option | GET POST PUT DELETE | Опції та значення |
| store | GET | Магазини |
| customer | GET POST PUT DELETE | Покупці + групи |
| information | GET POST PUT DELETE | Інформаційні сторінки |
| review | GET POST PUT DELETE | Відгуки |
| coupon | GET POST PUT DELETE | Купони |
| seo_url | GET POST PUT DELETE | ЧПУ (SEO URL) |
| webhook | GET POST PUT DELETE | Підписки на події + events |
| image | POST | Завантаження зображень (multipart) |
| ping · spec | GET | Health-check та OpenAPI-специфікація |
Масова синхронізація (bulk_stock)
Оновлює залишки, ціни та інші поля багатьох товарів одним запитом — для синхронізації з ERP. Елемент ідентифікується за product_id, потім sku, потім model. Оновлюються лише передані поля. Максимум 500 елементів.
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 }
]
}
{
"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. Значення * підписує на всі.
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) — усі ресурси, методи, параметри та схеми. Придатний для генерації клієнтів.
Інструменти розробника
Redoc довідка
Інтерактивна OpenAPI-документація.
OpenAPI JSON
Специфікація для Swagger / генерації клієнтів.
Postman-колекція
~68 запитів з автоматичним HMAC-підписом.
У Postman задайте змінні base_url, api_key, api_secret — pre-request скрипт колекції сам обчислить X-Api-Timestamp та X-Api-Signature. Підписувати вручну не потрібно.
Готові підключити магазин?
Відкрийте інтерактивну довідку або поверніться на головну, щоб придбати модуль.