---
slug: "mango-office"
name: "MANGO OFFICE — API Виртуальной АТС"
vendor: "MANGO OFFICE"
industry: "communications"
docsUrl: "https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/"
version: 2
updatedAt: "2026-10-24"
---

# MANGO OFFICE — API Виртуальной АТС

Отрасль: Связь и уведомления. Актуально на 2026-10-24.

Основной API MANGO OFFICE для управления виртуальной АТС: команды (звонок от имени сотрудника или группы, завершение, перевод и маршрутизация вызова, SMS, запись разговора, воспроизведение файла), статистика вызовов, записи разговоров, конфигурация (сотрудники, группы, номера, SIP-учётные записи, баланс) и уведомления в реальном времени о событиях. Архитектура REST, данные — JSON.

## Сценарии

### Позвонить клиенту из CRM одной кнопкой

Click-to-call: менеджер нажимает на номер в CRM, АТС сначала звонит ему, потом соединяет с клиентом.

1. В личном кабинете MANGO OFFICE подключи API и возьми vpbx_api_key (уникальный код ВАТС) и vpbx_api_salt (ключ подписи). Ключ подписи никогда не передаётся в запросах.
2. Каждый запрос — POST с тремя полями формы: vpbx_api_key, json (параметры команды строкой) и sign = sha256(vpbx_api_key + json + vpbx_api_salt) в hex.
3. Запусти вызов: POST /vpbx/commands/callback с command_id (твой ID команды), from.extension — внутренним номером менеджера и to_number — номером клиента. При необходимости укажи line_number — линию, с которой звонить.
4. Результат команды придёт на твой адрес /vpbx/result/callback с тем же command_id и кодом result (1000 — успешно). 3102 значит, что подпись не совпала: проверь, что json в подписи и в запросе — одна и та же строка.

```python
import hashlib, json, requests

API_KEY, SALT = "<vpbx_api_key>", "<vpbx_api_salt>"

def mango(path: str, params: dict) -> dict:
    payload = json.dumps(params, ensure_ascii=False, separators=(",", ":"))
    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()
    r = requests.post(f"https://app.mango-office.ru{path}", data={"vpbx_api_key": API_KEY, "sign": sign, "json": payload})
    return r.json()

print(mango("/vpbx/commands/callback", {"command_id": "crm-1042", "from": {"extension": "101"}, "to_number": "79991234567"}))
```

### Показывать карточку клиента при входящем звонке

АТС сообщает о каждом звонке, а CRM открывает менеджеру карточку звонящего.

1. В настройках API укажи адрес своей системы для уведомлений. ВАТС будет присылать POST-запросы на /events/call с полями vpbx_api_key, sign и json.
2. Проверяй подпись каждого уведомления тем же способом: sha256(vpbx_api_key + json + vpbx_api_salt).
3. В событии — call_id, call_state (Appeared, Connected, OnHold, Disconnected), from.number, to.extension и seq. Когда звонок Appeared у сотрудника, найди клиента по from.number и покажи карточку менеджеру с этим внутренним номером.
4. Порядок событий не гарантирован — сортируй их по seq внутри entry_id.
5. Чтобы сопоставить внутренние номера с сотрудниками, получи список: POST /vpbx/config/users/request. Завершить вызов, который ещё в IVR или у абонента, можно командой POST /vpbx/commands/call/hangup с call_id из события.

```python
import hashlib, hmac, json

def handle_event(form: dict) -> None:
    expected = hashlib.sha256((form["vpbx_api_key"] + form["json"] + SALT).encode()).hexdigest()
    if not hmac.compare_digest(expected, form["sign"]):
        return  # чужой запрос
    ev = json.loads(form["json"])
    if ev.get("call_state") == "Appeared" and ev.get("to", {}).get("extension"):
        show_client_card(manager_ext=ev["to"]["extension"], phone=ev["from"].get("number"))
```

### Выгрузить статистику звонков за период

Отчёт по звонкам для аналитики: кто звонил, кому, сколько длился разговор.

1. Запусти формирование: POST /vpbx/stats/request с date_from и date_to в Unix-времени (период — не больше месяца) и fields — нужными полями в нужном порядке. Можно отфильтровать по сотруднику или номеру.
2. В ответе — key. Забирай результат: POST /vpbx/stats/result с этим key.
3. Ответ 204 значит, что данные ещё не готовы — повторяй не чаще раза в 5 секунд. 200 — готово: тело в CSV, разделитель «;», строки через перевод строки. 404 — ключ неверный или устарел.
4. Время в статистике — московское (UTC+3).

```python
import time

job = mango("/vpbx/stats/request", {"date_from": 1761944400, "date_to": 1762549200,
                                    "fields": "start, finish, from_extension, from_number, to_extension, to_number, disconnect_reason"})
while True:
    payload = json.dumps({"key": job["key"]}, separators=(",", ":"))
    sign = hashlib.sha256((API_KEY + payload + SALT).encode()).hexdigest()
    r = requests.post("https://app.mango-office.ru/vpbx/stats/result", data={"vpbx_api_key": API_KEY, "sign": sign, "json": payload})
    if r.status_code == 200:
        rows = [line.split(";") for line in r.text.splitlines()]
        break
    time.sleep(5)
```

### Отправить SMS и проверить баланс

SMS клиенту с номера компании — подтверждение записи, напоминание.

1. Отправь SMS: POST /vpbx/commands/sms с from_extension — внутренним номером сотрудника (с него списываются деньги), to_number, text (до 268 кириллических символов) и sms_sender — именем отправителя из доступных в аккаунте.
2. Результат придёт на /vpbx/result/sms с тем же command_id; код 4300 значит, что SMS не отправлено.
3. Перед рассылкой проверь баланс: POST /vpbx/account/balance с пустым json {}. В ответе balance и currency.

```python
print(mango("/vpbx/commands/sms", {"command_id": "sms-1042", "from_extension": "101", "to_number": "79991234567",
                                   "text": "Вы записаны на 25.10 в 14:00. Ждём вас!", "sms_sender": "<имя отправителя>"}))
print(mango("/vpbx/account/balance", {}))
```

## Базовые URL

- Боевой: `https://app.mango-office.ru`

## Авторизация

Тип: API-ключ

Каждый запрос — POST с тремя полями формы: `vpbx_api_key` (уникальный код ВАТС), `sign` (подпись) и `json` (параметры команды). Подпись: `sign = sha256(vpbx_api_key + json + vpbx_api_salt)`, где `vpbx_api_salt` — ключ создания подписи; сам ключ в запросах не передаётся. Уведомления, которые ВАТС отправляет во внешнюю систему, подписываются так же.

```
sign = sha256(vpbx_api_key + json + vpbx_api_salt)
```

## Методы

### POST /vpbx/commands/callback — Вызов от имени сотрудника

Результат приходит во внешнюю систему на `/vpbx/result/callback` (`command_id`, `result`).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `command_id` | body | string | нет | ID команды во внешней системе, до 128 байт |
| `from.extension` | body | string | да | Внутренний номер сотрудника |
| `from.number` | body | string | нет | Номер сотрудника, с которого звонить (SIP, FMC, ТфОП), до 128 байт |
| `to_number` | body | string | да | Вызываемый номер: сотрудник, группа или любой номер |
| `line_number` | body | string | нет | Линия (SIP UAC, 7-800, DID); для SIP — имя линии |
| `sip_headers` | body | object | нет | SIP-заголовки, например Call-Info/answer-after |

### POST /vpbx/commands/callback_group — Вызов от имени группы

Короткий номер группы указывается в `from` или в `to`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `command_id` | body | string | нет | ID команды, до 128 байт |
| `from` | body | string | да | Вызывающий: внешний номер или короткий номер группы |
| `to` | body | string | да | Вызываемый: внешний номер или короткий номер группы |
| `line_number` | body | string | да | Линия той же ВАТС (SIP UAC, 7-800, DID) |

Пример запроса:

```
{
    "command_id": "cbk1",
    "from": "1234",
    "to": "74955404444",
    "line_number": "74951234567"
}
```

### POST /vpbx/commands/call/hangup — Завершение вызова

Работает, когда вызов находится в IVR или у абонента (`location` = `ivr` или `abonent`).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `command_id` | body | string | нет | ID команды, до 128 байт |
| `call_id` | body | string | да | Внутренний ID вызова (не SIP Call-ID) |

Пример запроса:

```
{
    "command_id": "cmd.888.vpbx.12345.external.system.com.net",
    "call_id": "100500"
}
```

### POST /vpbx/commands/sms — Отправка SMS

Результат — на `/vpbx/result/sms`; код `4300` — SMS не отправлено.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `command_id` | body | string | нет | ID команды, до 128 байт |
| `text` | body | string | да | Текст: до 612 латинских или 268 кириллических символов |
| `from_extension` | body | string | да | Внутренний номер сотрудника (с него списываются средства) |
| `to_number` | body | string | да | Номер получателя, до 128 байт |
| `sms_sender` | body | string | нет | Имя отправителя из доступных в аккаунте |

Пример запроса:

```
{
    "command_id": "smsmsmsm",
    "text": "Hello world!",
    "from_extension": "222",
    "to_number": "74955404444",
    "sms_sender": "PRO-TAXI"
}
```

### POST /vpbx/stats/request — Запуск формирования статистики

Асинхронно: в ответе `key`, по нему затем забирается результат. О готовности ВАТС может уведомить на `/vpbx/result/stat` (`key`, `request_id`).

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `date_from` | body | integer | да | Начало периода, Unix time (UTC+3) |
| `date_to` | body | integer | да | Конец периода; не больше месяца от date_from |
| `fields` | body | string | нет | Поля выгрузки через запятую в нужном порядке |
| `from.extension` | body | string | нет | Сотрудник-инициатор |
| `from.number` | body | string | нет | Номер вызывающего (E.164) |
| `to.extension` | body | string | нет | Вызываемый сотрудник |
| `to.number` | body | string | нет | Вызываемый номер (E.164) |
| `call_party.extension` | body | string | нет | Сотрудник с любой стороны (нельзя вместе с from/to) |
| `call_party.number` | body | string | нет | Номер с любой стороны |
| `request_id` | body | string | нет | ID запроса во внешней системе, до 128 байт |

### POST /vpbx/stats/result — Получение статистики вызовов

`200` — данные готовы (CSV-строка, разделитель `;`, строки — `\n`), `204` — ещё не готовы (повторять не чаще раза в 5 секунд), `404` — ключ неверный или устарел.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `key` | body | string | да | Ключ из stats/request |

Пример запроса:

```
{
    "key": "b3ZvIt8hPJReV8v4MYspQQA=="
}
```

### POST /vpbx/config/users/request — Список сотрудников

В ответе `users`: `extension`, `name`, `email`, `department`, `position`, номера (`number`, `protocol`, `wait_sec`, `order`, `status`) и др.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |
| `extension` | body | string | нет | Внутренний номер; без него — весь список |
| `ext_fields` | body | array | нет | Доп. поля: general.user_id, general.sips, groups, general.access_role_id, telephony.line_id и др. |

Пример запроса:

```
{
    "extension": "1234"
}
```

### POST /vpbx/account/balance — Баланс

Тело — пустой JSON `{}`.

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `vpbx_api_key` | body | string | да | Уникальный код ВАТС |
| `sign` | body | string | да | Подпись запроса |

Пример ответа:

```json
{
    "result": 1000,
    "balance": 963592.45,
    "currency": "RUB",
    "response_at": "2019-01-24 17:55:24"
}
```

## Нюансы

- Уведомления (API Realtime) ВАТС отправляет POST-запросом на адрес внешней системы, например `https://external-system.com/events/call`, с полями `vpbx_api_key`, `sign`, `json`. Есть события о вызове, результате SMS, записи разговора, DTMF, завершении вызова.
- Событие `events/call`: `entry_id` (группа вызовов), `call_id`, `timestamp`, `seq`, `call_state` (`Appeared`, `Connected`, `OnHold`, `Disconnected`), `location` (`ivr`, `queue`, `abonent`), `from.number`, `from.extension`, `to.number`, `to.extension`, `disconnect_reason`.
- Порядок событий не гарантирован — сортируйте по `seq`. Порядок результата команды и событий, которые она порождает, тоже не гарантирован.
- Часть команд требует ID, которые приходят только через API Realtime (например, `call_id`).
- Время в статистике и событиях — UTC+3.
- Есть эмулятор API ВАТС и SHA256-генератор в разделе поддержки; при невозможности использовать API ВАТС предлагается «API Сервер-клиент».

## Ошибки

| Код | Описание |
|---|---|
| `1000` | Действие выполнено успешно |
| `1100` | Вызов завершён в нормальном режиме |
| `2xxx` | Ограничение биллинговой системы |
| `3100` | Неверные параметры команды |
| `3101` | Запрос отправлен не методом POST |
| `3102` | Подпись не совпадает с вычисленной |
| `3103` | Нет обязательного параметра |
| `3200` | Неверный номер абонента |
| `3300` | Объект не существует |
| `4001` | Команда не поддерживается |
| `4290` | Превышено число запросов (HTTP 429) |
| `5001` | Перегрузка: лимит каналов или вызовов в секунду |

## Ограничения

- Период статистики — не больше месяца.
- Результат статистики хранится не меньше минуты после готовности; опрос — не чаще раза в 5 секунд.
- SMS — до 612 латинских или 268 кириллических символов (4 сегмента).

## Источники

- [Методы API Виртуальной АТС](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/)
- [О параметре sign](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/4_obschie_polozheniya_o_vzaimodeystvii_sistem/2_4_unikalnyy_kod_vashey_vats_klyuch_dlya/2_4_3_o_parametre_sign/)
- [Вызов от имени сотрудника](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_1_initsiirovanie_vyzova_ot_imeni/)
- [Вызов от имени группы](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_2_initsiirovanie_vyzova_ot_imeni_gruppy/)
- [Завершение вызова](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_3_zavershenie_vyzova/)
- [Отправка SMS](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/2_2_api_komandy/3_2_4_otpravka_sms/)
- [Запуск формирования статистики](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/4_4_api_statistika/1_4_1_zapros_bazovoy_statistiki/3_4_1_1_zapusk_formirovaniya_statistiki/)
- [Получение статистики](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/4_4_api_statistika/1_4_1_zapros_bazovoy_statistiki/3_4_1_2_poluchenie_statistiki_vyzovov/)
- [Список сотрудников](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/7_7_api_konfiguratsiya/3_7_1_zapros_spiska_sotrudnikov_vats/)
- [Баланс](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/7_7_api_konfiguratsiya/3_7_6_poluchenie_balansa/)
- [Уведомление о вызове](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/1_1_api_realtime/3_1_2_uvedomlenie_o_vyzove/)
- [Коды результатов](https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/7_spisok_kodov_rezultatov/)

---

Если этого недостаточно — официальная документация: https://www.mango-office.ru/support/5_api-i-razrabotka/1_api-mango-office/5_opisanie_metodov_api_virtualnoy_ats_mango/
JSON: https://mcp-everything.ru/api/integrations/mango-office. MCP: https://mcp-everything.ru/mcp