Для разработчиков

Документация API и вебхуков для подключения внешней системы к интернет-магазину Mobitsa.

Здесь описан общий контракт. Ключи, разрешения и адрес вебхука настраиваются только в выбранном рабочем пространстве.

Общие сведения

API используется для чтения и изменения данных. Вебхуки сообщают внешней системе о событиях без постоянного опроса.

Базовый URLhttp://mobitsa.pw/api/store/v1

Серверная авторизацияAuthorization: Bearer mbs_live_…

До 120 запросов в минуту на ключ

Методы API

Все запросы ограничены выбранным сайтом и разрешениями ключа. Значения ключей на публичной странице не отображаются.

Заказы

GET/orders Получить список заказов

GET/orders/{id} Получить один заказ

PATCH/orders/{id}/status Изменить статус заказа

Товары и варианты

GET/products Получить страницу товаров

GET/products/{id} Получить товар и его варианты

PATCH/products/{id}/stock Изменить остаток простого товара

GET/products/{id}/variants Получить варианты товара

GET/products/{id}/variants/{variantId} Получить один вариант

PATCH/products/{id}/variants/{variantId}/stock Изменить остаток варианта

Пример изменения статуса

Поддерживаемые статусы: PROCESSING, SHIPPED, COMPLETED, CANCELLED, REFUNDED, FAILED

PATCH /api/store/v1/orders/42/status
Content-Type: application/json

{
  "status": "PROCESSING"
}

События и доставка

Mobitsa отправляет POST-запрос на сохранённый HTTPS-адрес. Единый формат события упрощает обработку и последующее расширение интеграции.

Доступные события

order.createdСоздан новый заказ

order.updatedЗаказ изменён

product.stock_changedИзменился остаток товара

variant.stock_changedИзменился остаток варианта

Заголовки вебхука

X-Mobitsa-Event X-Mobitsa-Delivery X-Mobitsa-Timestamp X-Mobitsa-Signature

При временной ошибке выполняется до 5 попыток доставки.

Единый конверт события

{
  "id": "evt_01J…",
  "schema_version": "1",
  "event": "product.stock_changed",
  "occurred_at": "2026-07-27T12:00:00.000000Z",
  "site": {"id": 42},
  "data": {
    "product": {"id": 314, "sku": "SKU-314", "stock": 18},
    "change": {"previous_stock": 20, "stock": 18}
  }
}

Проверка подписи

Подпись рассчитывается по исходному телу запроса. Не преобразуйте JSON до проверки HMAC SHA-256.

$rawBody = file_get_contents('php://input');
$received = $_SERVER['HTTP_X_MOBITSA_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Безопасность интеграции

Публичная документация объясняет контракт, но не раскрывает настройки конкретного сайта.

Минимальные разрешения

Выдавайте подключению только те права, которые нужны его рабочему сценарию.

Подпись каждого события

Проверяйте HMAC SHA-256 по исходному телу запроса до обработки данных.

Идемпотентная обработка

Используйте идентификатор доставки: одно событие может прийти повторно.

Порядок подключения

01
Выберите сайт магазина
Интеграция всегда относится к одному сайту внутри рабочего пространства.
02
Создайте подключение
Выпустите ключ API, выберите разрешения и при необходимости добавьте URL вебхука.
03
Реализуйте контракт
Настройте серверные запросы, проверку подписи и идемпотентную обработку событий.