Для партнёров

Партнёрское API

Партнёрское API — это отдельный machine-to-machine доступ для организаций-партнёров ВойсЛайнс. Оно помогает управлять клиентскими организациями через интеграцию: создавать и обновлять Роботов, Базы контактов, контакты и webhook-уведомления без ручной работы в личном кабинете.

OpenAPI JSON PDF-контракт

Доступно только партнёрам. Обычным организациям этот API недоступен. Доступ, лимиты и ключи включаются для партнёрской организации отдельно.

Первый запрос#

Ключ создаётся в кабинете: раздел «Партнёры», вкладка «API». Первый запрос проверяет, что API доступно, а ключ действует.

GEThttps://voicelines.ru/api/v1/partner-api/health

Authorization: Bearer vlp_live_xxxxxxxxxxxxxxxxx

cURL

curl https://voicelines.ru/api/v1/partner-api/health \
  -H "Authorization: Bearer vlp_live_xxxxxxxxxxxxxxxxx"

Ответ:

JSON

{
  "status": "ok",
  "partnerOrgId": "guid",
  "partnerName": "Партнёр",
  "keyId": "guid",
  "keyName": "Основной ключ",
  "timestampUtc": "2026-04-27T10:00:00Z"
}

Базовый адрес всех запросов — https://voicelines.ru/api/v1/partner-api. Заголовок с ключом нужен в каждом.

Что умеет API#

Группа	Операций	Что делает
Проверка ключа	1	Проверить, что API доступно, а ключ действует.
Организации	3	Создать клиентскую организацию, получить список и одну организацию — с балансом и числом исходящих линий.
Финансы	2	Получить финансовые операции за период — в JSON или CSV.
Голоса	1	Получить голоса Робота, доступные организации.
Роботы	5	Получить список и одного Робота, создать, обновить, удалить.
Базы контактов	7	Получить список и одну Базу, создать, обновить, включить и отключить, узнать прогресс.
Контакты	6	Получить контакты Базы и один контакт, добавить по одному или пачкой, заблокировать, разблокировать.
Webhook	7	Получить список и одно уведомление Базы, создать, обновить, удалить, включить или отключить, отправить тестовое.

Всего 32 операции на 22 адресах. Поля запросов и ответов — в OpenAPI JSON и PDF-контракте.

Робота можно удалить только после отвязки от всех неудалённых Баз, включая выключенные. Запрет тестовых звонков блокирует звонок на добавочный номер Робота, но не отключает обычные исходящие звонки и входящие в Базу. Уже начатые разговоры продолжаются.

В финансовой выдаче входящий звонок Роботу без Базы, включая демонстрационный, отмечен как test. Данные звонка могут отсутствовать, а его полная длительность повторяется в каждой связанной операции — это не оплачиваемые минуты. Правила сверки и nullable-поля описаны в PDF.

Лимиты#

Значения по умолчанию. Фактические — в кабинете: раздел «Партнёры», вкладка «API».

Лимит	По умолчанию
Клиентские организации	50 на партнёра, включая отключённые
Роботы	100 на клиентскую организацию
Базы контактов	100 на клиентскую организацию
Контакты	5 000 на Базу, до 1 000 в одном запросе
Read-запросы	60 в минуту на API-ключ
Write-запросы	20 в минуту на API-ключ
Batch-добавление контактов	5 в минуту на API-ключ
Операции с webhook-настройками	20 в минуту на API-ключ

При превышении частоты API возвращает 429 и RATE_LIMIT_EXCEEDED. Прежде чем повторять запрос, учитывайте заголовок Retry-After.

Ошибки#

Ошибки возвращаются простым JSON-объектом. HTTP-статус остаётся основным, а errorCode нужен для программной обработки.

JSON

{
  "errorCode": "PHONE_INVALID",
  "message": "Неверный формат телефона",
  "traceId": "00-...",
  "details": {
    "field": "phoneE164"
  }
}

HTTP	Код	Значение
`401`	`PARTNER_API_KEY_INVALID`	API-ключ отсутствует или неверный.
`403`	`INSUFFICIENT_SCOPE`	У ключа нет нужного права.
`404`	`CLIENT_ORG_NOT_FOUND`	Клиентская организация не найдена или не принадлежит партнёру.
`404`	`RESOURCE_NOT_FOUND`	Робот, база контактов, контакт или webhook-уведомление не найдено.
`400`	`VALIDATION_ERROR`	Некорректные параметры запроса.
`429`	`RATE_LIMIT_EXCEEDED`	Превышен лимит запросов.

Все 29 кодов — в PDF-контракте.

Где взять доступ#

API-ключи создаются в партнёрской панели. Если раздел партнёрского API не отображается или ключи не создаются, обратитесь к администратору ВойсЛайнс: для организации должен быть включён партнёрский режим и доступ к API.