API для телефонных номеров и документов

С помощью API вы можете реализовать подключение и управление виртуальными номерами из собственного интерфейса (админ панели) без необходимости входа в личный кабинет Zadarma.

Все возможности и методы API Zadarma.

В большинстве стран, для подключения номера требуется идентификация конечного пользователя. Пользовательские документы также загружаются по API.

Возможности API:

• выбор и подключение виртуальных номеров
• настройка уже подключенных номеров
• работа с документами для подключения номеров (информация о требованиях для подключения, загрузка документов, проверка ранее загруженных документов для заказа определенного номера)

Последовательность действий для заказа номера через API:

1. Получение актуального списка стран и направлений для заказа, отображение их пользователю;
2. Получение и отображение списка номеров доступных для заказа;
3. Создание группы документов для пользователя (если не была создана ранее) и загрузка документов (если требуются);
4. Подключение выбранного номера на группу документов;
5. Направление номера на SIP логин либо SIP URI (set_sip_id).

Подключение новых номеров

Метод GET /v1/direct_numbers/countries/ получение списка стран в которых можно заказать номер, если запрос отправлен без параметров, ответ будет на языке личного кабинета, добавив необязательный параметр language можно получить ответ на одном из языков личного кабинета.

Метод GET /v1/direct_numbers/country/ для получения списка направлений в стране, в которых можно заказать номер. Обязательный параметр country - iso код страны (ISO 3166-1 alpha-2); Необязательные параметры language и direction_id. В ответе будет предоставлен массив данных с описанием номера: страна, город, стоимость подключения, ежемесячная абонентская плата, особенности, возможность приема смс и тд.

Получение списка номеров доступных для заказа, метод GET /v1/direct_numbers/available/<DIRECTION_ID>/ с параметрами DIRECTION_ID - ID направления или ru495; и mask - необязательный параметр, для поиска совпадений по номерам.

Заказать номер можно с помощью метода POST /v1/direct_numbers/order/ .

Уже подключенный номер можно при необходимости продлить на несколько месяцев вперёд методом POST /v1/direct_numbers/prolong/

Обязательные параметры запроса number и months

Взаимодействие с уже подключенными номерами

Метод GET /v1/direct_numbers/ (без параметров) возвращает массив с информацией об уже подключенных номерах.

Методом GET /v1/direct_numbers/number/ можно получить информацию об определенном подключенном номере, запрос отправляется с параметрами type и number.

Статус автопродления номера (будет ли он автоматически продлен на следующий период или отключится по окончанию срока действия ) можно узнать методом GET /v1/direct_numbers/autoprolongation/ с параметрами запроса type и number .

Для изменения статуса автопродления метод PUT /v1/direct_numbers/autoprolongation/ с параметрами запроса type, number и value

Метод PUT /v1/direct_numbers/set_caller_name/ - установка или включение Имени номера (латиница и цифры, до 30 знаков) текстовое описание номера, также при входящем звонке отправляется в заголовке From в качестве CALLERID(name).

Методом PUT /v1/direct_numbers/set_sip_id/ можно направить звонки с виртуального номера на определенный sip логин, внешний сервер по SIP URI или включить режим теста. Обязательные параметры запроса type, number и sip_id - sip логин или адрес внешнего сервера, например 1234567890@myserver.com test_mode - опционально, (on|off) - для включения тестового режима.

Работа с документами

Группа документов это данные человека или компании который будет использовать виртуальный номер, групп может быть несколько.

Создание новой группы документов - метод POST /v1/documents/groups/create/ .

Обновить данные в уже существующей группе документов можно методом PUT /v1/documents/groups/update/<GROUPID>/ .

Загрузка файла документа для группы документов выполняется методом POST /v1/documents/upload/ .

Методом GET /v1/documents/groups/list/ можно получить список групп документов, а методом GET /v1/documents/groups/get/<ID>/ , где ID это идентификатор группы, 0 - основная группа документов, можно получить информацию об определенной группе документов.

Метод GET /v1/documents/files вернет список ранее загруженных файлов/документов в группе документов. group_id - необязательный параметр, ID группы документов, (0 или не указан - основная группа документов).

Проверка: подходит ли группа документов для заказа номера в конкретном городе/направлении выполняется методом GET /v1/documents/groups/valid/<ID>/ .