Часто шукають

↑↓ вибрати ↵ відкрити Усі результати →

API · v1

Storeforma API

Два API на домені кожного магазину: Integration API для обліку, ERP і CRM та Storefront API для власних вітрин і мобільних застосунків. Усі методи з прикладами JSON, а праворуч — консоль, що надсилає запити просто у ваш магазин.

Integration API https://{store}/api/v1/integrations

Каталог, замовлення, клієнти й контент для зовнішньої системи: обліку, ERP, PIM чи CRM. Авторизація — ключем інтеграції, права якого обирають в адмінці магазину. Доступний на тарифі Pro і вище.

Перший метод →
Storefront API 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:readGETСписок товарівGETОдин товар
catalog:writePUTСтворити або замінити товарPATCHОновити частину товаруPUTСтворити або перейменувати категоріюPUTСтворити або перейменувати мітку
orders:readGETСписок замовленьGETОдне замовлення
orders:write-statusPOSTЗмінити статус замовлення
customers:readGETСписок клієнтівGETОтримати клієнта
inventory:writePUTОновити залишки
content:readGETСписок сторінок і записів
content:writePUTСтворити або оновити чернетку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Запис не знайдено.
409Idempotency-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 із записом у журналі змін.