# MANGO OFFICE — API Виртуальной АТС: Выгрузить статистику звонков за период

Сценарий из mcp-everything. Актуально на 2026-10-24.

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

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)
```

## Базовые 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/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=="
}
```

## Нюансы

- Уведомления (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 Сервер-клиент».

## Другие сценарии

- [Позвонить клиенту из CRM одной кнопкой](https://mcp-everything.ru/integrations/mango-office/scenarios/pozvonit-klientu-iz-crm-odnoy-knopkoy.md)
- [Показывать карточку клиента при входящем звонке](https://mcp-everything.ru/integrations/mango-office/scenarios/pokazyvat-kartochku-klienta-pri.md)
- [Отправить SMS и проверить баланс](https://mcp-everything.ru/integrations/mango-office/scenarios/otpravit-sms-i-proverit-balans.md)

---

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