External API

External API — это публичный интерфейс платформы для интеграций. Через него внешние сервисы (учётные системы, маркетплейсы, BI-инструменты, CRM, кастомные скрипты) могут читать и менять данные компании.

API работает в контексте одной компании, всегда. Токен принадлежит компании, и любые запросы возвращают/изменяют только её данные.

Базовый URL и версионирование

https://easymb.ru/api/external/v1

Версия зашита в путь. Несовместимые изменения попадут в v2; в v1 мы делаем только аддитивные правки (новые поля, новые endpoint'ы).

Аутентификация

Используется Bearer-токен. Создаётся в админке: «Администрирование → Разработчикам → API-токены → Создать».

GET /api/external/v1/catalog/products HTTP/1.1
Authorization: Bearer emb_live_a8f3b2c4d5e6f7…

Токен показывается один раз в момент создания. Сохраните его в секретном хранилище — повторно увидеть значение нельзя; если потеряли — отзовите старый и создайте новый.

Scopes

Каждый токен ограничен набором scope-строк. Формат: <module>:<action>, action ∈ {read, write}. Пример: catalog:read, orders:write.

<module>:write всегда подразумевает <module>:read. Wildcard *:write подразумевает *:read.

Бизнес-модули и активность

Endpoint работает только если соответствующий модуль активен у компании или является системным. Системные модули (core, catalog, calendar) доступны всегда. Остальные (cashier, warehouse, orders, clients) — только если включены в админке.

Если интегратор пытается обратиться к ресурсу выключенного модуля, ответ — 403 Forbidden с понятным сообщением.

Ресурсы и пагинация

Все списочные endpoint'ы поддерживают единый формат query-параметров:

Ответ:

{
  "items": [...],
  "total": 1234,
  "page": 1,
  "pageSize": 20
}

Примеры

Получить список товаров

curl -H "Authorization: Bearer $MBS_TOKEN" \
"https://easymb.ru/api/external/v1/catalog/products?page=1&pageSize=50"

Создать клиента

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"kind":"individual","displayName":"Иван Петров","phone":"+79991234567"}' \
https://easymb.ru/api/external/v1/clients

Изменить статус заказа

curl -X POST \
-H "Authorization: Bearer $MBS_TOKEN" \
https://easymb.ru/api/external/v1/orders/123e4567-e89b-12d3-a456-426614174000/status/completed

Ошибки

API возвращает JSON в формате { "statusCode": <code>, "message": <string|string[]>, "error": <string> }. Распространённые коды:

Аудит-лог

Все write-операции через external API попадают в журнал действий с actorId = ID сервис-аккаунта интеграции. В админке вы можете отфильтровать журнал по actorId, чтобы увидеть, что делал конкретный токен.

См. также: Webhooks.