API · v1
Storeforma API
Два API на домені кожного магазину: Integration API для обліку, ERP і CRM та Storefront API для власних вітрин і мобільних застосунків. Усі методи з прикладами JSON, а праворуч — консоль, що надсилає запити просто у ваш магазин.
https://{store}/api/v1/integrations
Каталог, замовлення, клієнти й контент для зовнішньої системи: обліку, ERP, PIM чи CRM. Авторизація — ключем інтеграції, права якого обирають в адмінці магазину. Доступний на тарифі Pro і вище.
Перший метод →https://{store}/api/v1
Кошик, доставка й оформлення для власної вітрини чи мобільного застосунку. Кошик покупця визначає токен; оформлення на вітрині магазину працює на тому самому ядрі, з тими самими правилами й помилками. Статус: preview.
Перший метод →Автентифікація
Integration API. Створіть ключ в адмінці магазину, у розділі «API-ключі», і оберіть для нього права. Надсилайте ключ у кожному запиті заголовком Authorization: Bearer {key}. Integration API доступний на тарифі Pro і вище.
Storefront API. Ключ не потрібен. POST /carts повертає meta.cart_token; надсилайте його заголовком X-Cart-Token з усіма запитами до кошика, доставки й оформлення.
Магазин визначається доменом запиту: your-store.storeforma.shop або власний домен магазину.
Права ключа
| Право | Методи |
|---|---|
catalog:read | GETСписок товарівGETОдин товар |
catalog:write | PUTСтворити або замінити товарPATCHОновити частину товаруPUTСтворити або перейменувати категоріюPUTСтворити або перейменувати мітку |
orders:read | GETСписок замовленьGETОдне замовлення |
orders:write-status | POSTЗмінити статус замовлення |
customers:read | GETСписок клієнтівGETОтримати клієнта |
inventory:write | PUTОновити залишки |
content:read | GETСписок сторінок і записів |
content:write | PUTСтворити або оновити чернеткуPOSTОпублікувати сторінкуPOSTЗняти сторінку з публікації |
Формат даних
Запити й відповіді — JSON (Content-Type: application/json, Accept: application/json). Гроші — цілі числа в мінорних одиницях валюти: 49000 = 490,00 грн. Час у Integration API — YYYY-MM-DD HH:MM:SS у часовому поясі магазину.
Пагінація
Товари — сторінками: page і limit (до 50), у відповіді total і next_page_url. Замовлення й контент — курсором: передавайте next_cursor попередньої відповіді в cursor, доки він не стане null.
Ідемпотентність
Методи, що змінюють стан замовлення чи публікацію, а також оформлення, вимагають заголовок Idempotency-Key — унікальний ключ спроби (наприклад, UUID). Повтор із тим самим ключем повертає першу відповідь замість другої дії; той самий ключ для іншого запиту — 409 (Integration) або 422 idempotency_key (оформлення). Upsert-методи каталогу й контенту ідемпотентні за вашим external_id.
Помилки
Integration API відповідає однією формою: код, повідомлення й поле, якого стосується помилка.
{
"code": "validation_error",
"message": "name is required.",
"field": "name"
}
Storefront API повертає помилки перевірки у формі Laravel: повідомлення й список помилок за полями.
{
"message": "The quantity field must not be greater than 100.",
"errors": {
"quantity": [
"The quantity field must not be greater than 100."
]
}
}
| 401 | Немає ключа чи токена кошика, або його відкликано. |
| 403 | У ключа немає потрібного права, або тариф магазину без доступу до API. |
| 404 | Запис не знайдено. |
| 409 | Idempotency-Key уже використано для іншого запиту. |
| 422 | Помилка в даних запиту. |
| 429 | Забагато запитів; зачекайте Retry-After секунд. |
Ліміти
Integration API — 60 запитів за хвилину на ключ; кожна відповідь містить X-RateLimit-Limit і X-RateLimit-Remaining. Storefront API — створення кошика 20/хв з IP, запити кошика 120/хв, оформлення 10/хв.
Вебхуки
Замість опитування підпишіться на події в адмінці магазину (розділ «Вебхуки»). Магазин надсилає POST на вашу https-адресу.
| Подія | Коли |
|---|---|
product.created | Товар створено |
product.updated | Товар змінено (назва, опис, ціни, варіанти) |
product.deleted | Товар видалено |
inventory.updated | Змінився залишок варіанта |
order.created | Нове замовлення |
order.status_changed | Змінився статус замовлення |
customer.created | Новий клієнт |
Заголовки: X-Storeforma-Event, X-Storeforma-Delivery (id доставки) і X-Storeforma-Signature: sha256=… — HMAC-SHA256 тіла запиту з секретом підписки. Часті зміни товару й залишків збираються за 30 секунд в одну доставку з останнім станом.
{
"id": "9b2f0c1e-…",
"event": "order.status_changed",
"created_at": "2026-10-12T16:20:45+03:00",
"data": {
"id": 1044,
"reference": "2026-001044",
"status": "dispatched",
"total": 214000,
"currency_code": "UAH"
}
}
// Перевірка підпису (Node.js)
import crypto from 'node:crypto';
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const valid = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-storeforma-signature']));OpenAPI
Повний контракт для Postman, Insomnia чи генераторів клієнтів:
openapi-integration.json openapi-storefront.json
Кожен магазин також віддає свою копію з власною адресою: https://{store}/api/docs/openapi.json і текстову для ШІ-агентів /api/docs.md.
Версії
У v1 можуть з’являтися нові поля й необов’язкові параметри — пишіть клієнти, що ігнорують невідомі поля. Перейменування, вилучення чи новий обов’язковий параметр — лише в /api/v2 із записом у журналі змін.