Начало работы с API

REST API находится по пути /api/v1. Веб-клиент использует те же конечные точки, что и интеграторы, и никаких закрытых, поэтому всё, что может делать консоль администратора, доступно через API.

Справочник генерируется из кода: документ OpenAPI 3.1 по адресу /api/v1/openapi.json и интерфейс Scalar по адресу /api/docs. По умолчанию для обоих нужен прошедший аутентификацию вызывающий (http.docs может быть authenticated, public или disabled). Каждая операция указывает право, которое ей нужно, как свою область.

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

Есть два вида учётных данных. Оба передаются одинаково:

Authorization: Bearer <access token or API key>

Токен доступа (пользователи)

Войдите с помощью адреса электронной почты и пароля:

curl -sS https://pbx.example.com/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"...","client":"my script"}'

Ответ:

{
  "access_token": "eyJhbGciOiJFZERTQSIs...",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "mpbx_rt_...",
  "refresh_expires_at": 1790000000,
  "session_id": "0199b5a2-6c1e-7d3a-9f00-3c8e1b2a4d55"
}

• Токен доступа — это короткоживущий JWT с подписью EdDSA (по умолчанию 15 минут).
• Если для учётной записи включена двухфакторная аутентификация и вы не передали totp_code, после правильного пароля вы получите 401 с кодом MPBX-AUTH-TOTP-REQUIRED. Повторите запрос с "totp_code":"123456".
• Обновляйте токен через POST /api/v1/auth/refresh и {"refresh_token":"..."}. Каждый токен обновления работает один раз. Предъявление уже использованного завершает всю сессию (MPBX-AUTH-REFRESH-REUSED), поэтому выполняйте не более одного обновления одновременно в одной сессии и всегда сохраняйте самый новый токен.
• POST /api/v1/auth/logout завершает сессию.
• Браузеры могут запросить "refresh_delivery":"cookie": тогда токен обновления хранится в cookie HttpOnly, а не в теле ответа.

Ключи API (интеграции)

Ключ API имеет вид mpbx_k1_<company>_<id>_<secret> и передаётся напрямую как bearer-токен. Обмена ключа на токен нет. Ключ действует от имени пользователя, который его создал, и имеет только те области, которые ему выданы, в пересечении с текущими правами этого пользователя, поэтому понижение пользователя сразу сокращает ключ. Ключи не могут создавать другие ключи. Полный ключ показывается один раз при создании.

Кто я

GET /api/v1/me возвращает вызывающего, компанию и каждое право, которое он имеет, с его охватом (вся компания или список отделов). Используйте его, чтобы проверить, что может делать учётное данное.

Выбор компании

Компания всегда определяется учётными данными, но никогда не берётся из URL или тела запроса. Системный администратор (System Owner или System Admin, с токеном системной области) выбирает компанию для работы через заголовок X-Mpbx-Tenant: <company id>. Это действие попадает в аудит.

Соглашения

• Постраничный вывод: ?limit=50&cursor=.... limit — от 1 до 200 (по умолчанию 50), значение вне диапазона даёт 400. Ответ имеет вид {"items":[...],"next_cursor":"..."}, а next_cursor отсутствует на последней странице. Курсоры привязаны к фильтру и сортировке, для которых они выданы.
• Фильтрация и сортировка: filter=field:op:value, можно повторять, с операторами eq ne gt gte lt lte contains starts_with in, и sort=-created_at,name. Принимаются только поля, которые объявляет конечная точка.
• Оптимистичная конкурентность: GET одного ресурса возвращает ETag. PATCH, PUT и DELETE требуют If-Match с ним: если его нет, ответ 428 (MPBX-PRECONDITION-REQUIRED), если он устарел, — 412 (MPBX-PRECONDITION-FAILED).
• PATCH: меняются только переданные поля. null означает «без изменений», так же как отсутствующее поле. Чтобы очистить текстовое поле, передайте пустую строку.
• Идемпотентность: передавайте Idempotency-Key (от 1 до 255 видимых ASCII-символов, подойдёт UUID) в POST, чтобы его было безопасно повторять. Повтор тем же вызывающим с тем же телом возвращает сохранённый ответ 2xx с заголовком Idempotent-Replayed: true. Тот же ключ с другим запросом даёт 422 (MPBX-IDEMPOTENCY-KEY-REUSED). Тот же ключ, пока первый запрос ещё выполняется, даёт 409 (MPBX-IDEMPOTENCY-IN-PROGRESS). Маршруты, которые передают секреты (все маршруты /auth/*, создание пользователей, сброс паролей, загрузка сертификатов), игнорируют этот заголовок.

Ошибки

Каждая ошибка имеет тип application/problem+json (RFC 9457):

{
  "type": "https://mpbx.example/errors/MPBX-NOT-FOUND",
  "title": "Not Found",
  "status": 404,
  "detail": "extension 1001 does not exist",
  "code": "MPBX-NOT-FOUND",
  "errors": [{"field": "filter", "message": "unknown field `colour`"}]
}

code — стабильное машиночитаемое значение. Ветвите логику по code, а не по detail. errors появляется, только если поля некорректны. URI в type использует заглушку хоста (mpbx.example), пока не решено настоящее доменное имя. Retry-After отправляется с 429 и 503. Внутренние ошибки никогда не содержат своего сообщения. Коды всех областей см. в разделе Коды ошибок.

С этими примерами вы встретитесь первыми:

Код	Статус	Значение
MPBX-AUTH-INVALID-CREDENTIALS	401	Вход не выполнен. Один код для любой причины, поэтому не раскрывает, какие учётные записи существуют.
MPBX-AUTH-TOKEN-EXPIRED	401	Срок действия токена доступа истёк. Обновите его.
MPBX-APIKEY-INVALID	401	Ключ API неизвестен, отозван, просрочен или неверен.
MPBX-RBAC-FORBIDDEN	403	У вас нет права, которое нужно для операции. GET /api/v1/me показывает, что у вас есть.
MPBX-RATE-LIMITED	429	Слишком много попыток входа, обновления или TOTP. Подождите Retry-After.
MPBX-INVALID-QUERY, MPBX-INVALID-CURSOR	400	Некорректный filter, sort, limit или cursor.

Ограничения частоты

Маршруты аутентификации ограничены по частоте для каждой клиентской сети и в минуту: по умолчанию 10 входов, 60 обновлений и 10 вызовов TOTP (http.login_rate_per_min, http.refresh_rate_per_min, http.totp_rate_per_min). Учётные записи также блокируются после повторных неудачных входов (по умолчанию 5 неудач за 15 минут). У некоторых других маршрутов есть собственные ограничения, например 10 запросов звонка по клику в минуту на пользователя, 60 запросов управления звонками в минуту на пользователя и 120 сообщений чата в минуту на пользователя. Каждое ограничение отвечает 429 с MPBX-RATE-LIMITED и заголовком Retry-After. У большинства других маршрутов нет ограничения по ключу или пользователю; администратор может ограничить, кто обращается к API, по адресу (см. Безопасность и сетевой доступ).

События и интеграции

• Исходящие вебхуки: MonoPbx может обращаться к вашему URL по событиям, с подписанными запросами, повторами и недоставленными сообщениями. См. Исходящие вебхуки.
• WebSocket событий: для потока в реальном времени в клиенте см. WebSocket событий.
• Звонок по клику: POST /api/v1/calls/click-to-call вызывает одно или все устройства вошедшего пользователя и, когда одно из них отвечает, набирает адрес назначения от имени этого пользователя через план набора. Передавайте Idempotency-Key.

Что пока недоступно

• Клиентские SDK не публикуются. Клиенты TypeScript и Dart генерируются из документа OpenAPI внутри репозитория.