Headless API
Модуль Headless API віддає дані магазину через REST — тож вітриною не обовʼязково має бути тема ECMS9: сайт на Next.js чи Nuxt, мобільний застосунок, кіоск або чужа система можуть читати каталог, наповнювати кошик, оформлювати замовлення й показувати покупцеві його історію.
Усе налаштовується в Модулі → Headless API.
З чого почати
Базова адреса — https://ваш-магазин/api/v1. Дві адреси варто відкрити в
браузері одразу:
/api/v1/meta— назва магазину, мови, валюта, версія API і які додаткові можливості цей магазин віддає;/api/v1/docs/ui— повний список ендпоінтів;/api/v1/docs— те саме у вигляді OpenAPI-файлу, який розуміють Postman, Insomnia й генератори коду.
Шляхи без /v1 (/api/products, /api/cart, …) відповідають так само, як
раніше, з тими самими полями. Після оновлення модуля переписувати нічого не
треба.
Що вміє API
| Напрям | Ендпоінти |
|---|---|
| Каталог | товари з варіантами, галереєю, залишками, рейтингом і габаритами посилки; категорії; фільтри; пошук; банери; супутні товари й акції |
| Кошик | переглянути, додати, змінити кількість, прибрати, очистити |
| Оформлення | способи доставки, способи оплати, власні поля магазину, створення замовлення |
| Покупець | реєстрація, вхід, профіль, список замовлень і замовлення з номером накладної; баланс бонусів (якщо встановлено модуль system_bonus) |
| Гостьові замовлення | статус замовлення за номером і телефоном та накладна/трекінг такого замовлення — для магазинів, де більшість замовлень оформлюють без акаунта |
| Контент магазину | умови доставки й оплати, контакти, опубліковані інформаційні сторінки і пошук по них за релевантністю — ті самі відповіді, що цитує AI-чат на сайті |
| Доставка | пошук міст і відділень Нової Пошти — щоб headless-оформлення мало ті самі підказки, що й вітрина |
Токени доступу
Типово API відповідає всім — так само, як сторінки вітрини, які воно дублює. Два перемикачі це змінюють:
- Вимагати токен для читання — каталог закритий, його бачать лише клієнти з токеном;
- Вимагати токен для запису — кошик, оформлення й авторизація вимагають
токен із правом
write.
Токени створюються на тій самій сторінці. У токена є назва і права: типово лише читання, плюс галочки дозволити запис (кошик, замовлення) і чат-бот — право, яким користується чат-віджет на сайті: статус замовлення за телефоном і виклик оператора, і більше нічого, тож токен, що потрапив у браузер, не стане ключем на запис. Токен показується один раз, при створенні, — магазин зберігає лише його відбиток. Видавайте кожній інтеграції свій токен: тоді видно, скільки запитів вона зробила, і її можна вимкнути чи видалити, не зачепивши інші.
Токен передається заголовком:
Authorization: Bearer hk_xxxxxxxxxxxxxxxx
Якщо Authorization уже зайнятий чимось перед магазином (наприклад,
basic-авторизацією), надсилайте X-Api-Key: hk_… — приймається і те, і те.
Покупці
POST /api/v1/auth/login повертає токен покупця (hc_…), який упізнає
його в наступних запитах — без куків, які браузери все одно блокують між
доменами. Термін дії токена — налаштування (типово 30 днів), а
/auth/logout відкликає його одразу.
Кошик для стороннього фронтенду
Кошик зазвичай живе в PHP-сесії, яку сайт на іншому домені втримати не може.
Тому в API є серверний кошик: перший запис із use_key=1 повертає
cart_key, а клієнт далі шле його в заголовку X-Cart-Key. Оформлення
приймає той самий ключ — тож замовлення створюється саме з того, що покупець
зібрав.
Запобіжники
- Ліміт запитів — на токен, а для анонімних викликів на IP (типово 120 за
хвилину;
0вимикає). Клієнт, який перевищив, отримує HTTP 429 і час очікування. - CORS — перелічіть домени ваших фронтендів. Порожньо = «лише той самий домен», що й потрібно магазину без зовнішньої вітрини.
- Залишки — можна віддавати точні числа, а можна лише ознаку «є в наявності».
php spark headless:selftest викликає всі ендпоінти магазину й друкує
результат по рядках — найшвидший спосіб переконатися, що API працює на цьому
сайті після ввімкнення модуля.