Факс (/fax/)

_{Протестировать методы API можно на странице}_{интерактивного обозревателя API}_{и без написания кода}
_{Некоторые ресурсы, описанные на странице, по умолчанию могут быть не доступны из-за типа приложения (см.}_{Создание и авторизация приложений}₎

Данный ресурс позволяет настраивать параметры внутренних номеров типа "факс", а также получать и отправлять факсимильные сообщения.

Конфигурация факса

Параметр	Тип	Обяза-тельный	Значение по умолчанию	Описание
fax_mailto	string	нет	null	Адрес электронной почты, на который будут отправлены полученные внутренним номером факсимильные сообщения. Возможно перечисление нескольких адресов через запятую

Пример

У внутреннего номера типа “факс” добавим адреса электронной почты, на которые будут отправляться полученные данным внутренним номером факсимильные сообщения:

Ответ системы:

{
  "fax_mailto": "admin@host.com,user@host.com"
}

Получение факсимильных сообщений

Существует возможность получать и управлять сообщениями, полученными внутренними номерами типа "факс".

Описание полей

Параметр	Тип	Описание
caller_id	string	Номер отправителя сообщения
client_id	long	Идентификатор клиента
datetime	string	Дата и время получения сообщения
destination	string	Номер получателя сообщения
extension_group_id	long	Идентификатор группы внутренних номеров. Может иметь значение ‘null’, если внутренний номер не состоит ни в одной из групп
extension_id	long	Идентификатор внутреннего номера
file_size	long	Размер файла сообщения
uuid	string	Идентификатор сообщения

Пример

Ответ системы:

[
  {
    "caller_id": "1844*001",
    "client_id": 12,
    "datetime": "2015-11-25 15:08:06",
    "destination": "78123092631",
    "extension_group_id": null,
    "extension_id": 122,
    "file_size": 23142,
    "uuid": "1a66f8c6-936d-11e5-8563-d3163e2a7e2d"
  },
  {
    "caller_id": "1844*002",
    "client_id": 12,
    "datetime": "2015-11-25 15:16:10",
    "destination": "78123092631",
    "extension_group_id": null,
    "extension_id": 122,
    "file_size": 23138,
    "uuid": "3ae42208-936e-11e5-85a2-d3163e2a7e2d"
  }
]

Отправка факсимильных сообщений

^{Content-Type при загрузке файлов}
^{При загрузке файлов через метод POST следует установить заголовок}^Content-Type^{в значение}^{multipart/form-data}^{с указанием параметра}^boundary^{, который содержит последовательность символов, разделяющую части тела запроса. Параметры звукового файла и сам файл передаются как}^{поля формы}^{. Во всех остальных методах, в том числе и обновлении информации о звуковом файле, следует использовать обычный}^{Content-Type: application/json}^{и передавать информацию в JSON-формате. Стоит отметить, что в большинстве случаев различные библиотеки для работы с веб-ресурсами генерируют тело запроса и заголовок}^Content-Type^{с параметром}^boundary^{автоматически.}

Описание полей запроса

Параметр	Тип	Обяза-тельный	Значение по умолчанию	Описание
dst_num	string	да		Номер, на который требуется отправить факс
file	file	да		Файл в формате tiff или pdf. Максимальный размер файла – 10 мегабайт

Пример

Отправка файла faxtest.tif на номер 1234567

Ответ системы:

{
  datetime: "2016-04-07 20:08:54",
  dst_num: "1234567",
  id: 174,
  status: "ready_to_send"
}

С точки зрения загрузки файлов, отправка факса производится так же, как и добавление звука, поэтому примеры запросов, содержащих файлы, можно посмотреть на странице “Звуковые файлы”.

Получение информации о состоянии отправки

Для получении о статусе отправки факсимильного сообщения необходимо воспользоваться соответствующим ресурсом:

для получения списка всех отправленных с внутреннего номера факсимильных сообщений: GET /extension/{extension_id}/fax/out/

для получения информации о конкретном отправленном факсимильном сообщении: GET /extension/{extension_id}/fax/out/{message_id}

Пример

Запросим информацию о сообщении с id 175, отправленном с внутреннего номера с id 122:

Ответ системы:

{
  "status": "sent",
  "dst_num": "1234567",
  "id": 175,
  "datetime": "2016-04-11 18:07:53"
}

Описание полей

Параметр	Тип	Описание
datetime	string	Дата и время отправки факсимильного сообщения
dst_num	string	Номер, на который был отправлено факсимильное сообщение
id	long	Идентификатор факсимильного сообщения
status	string	Статус отправки факсимильного сообщения. Описание см. ниже

Статус отправки

Статус	Описание
ready_to_send	Сообщение поставлено в очередь на отправку. Отправку сообщения, имеющего данный статус, можно отменить
sending	Сообщение в процессе отправки
failed	Сбой отправки сообщения. Сообщение, имеющее этот статус, можно отправить заново или отменить отправку
canceled	Отправка отменена
error	Возникла ошибка отправки

Повтор и отмена отправки

Сообщение, отправка которого завершилась неудачно (статус failed), можно отправить заново или отменить его отправку. Также возможна отмена отправки сообщения со статусом ready_to_send.

Для повтора отправки сообщения или отмены отправки необходимо осуществить PUT-запрос на ресурс /extension/{extension_id}/fax/out/{message_id}?action={action},
где параметр URL “action” может принимать значения retry и cancel для повтора отправки и отмены отправки сообщения соответственно.

Пример

Повторим отправку сообщения c id 175 с внутреннего номера с id 122:

Ответ системы:

{
  "status": "ready_to_send",
  "dst_num": "123",
  "id": 175,
  "datetime": "2016-04-11 18:07:53"
}

Ресурсы раздела "Клиент"

GET /client/{client_id}/fax/in/

GET /client/{client_id}/fax/in/

Получить список входящих факсимильных сообщений для клиента

Параметры URL

Имя	Тип
client_id	string

Параметры запроса

Имя	Тип
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
extension_group_id	integer
order	string
extension_id	integer

Поля ответа

Имя	Тип
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /client/{client_id}/fax/in/{fax_uuid}

GET /client/{client_id}/fax/in/{fax_uuid}

Получить файл входящего факсимильного сообщения

Параметры URL

Имя	Тип
fax_uuid	string
client_id	string

DELETE /client/{client_id}/fax/in/{fax_uuid}

DELETE /client/{client_id}/fax/in/{fax_uuid}

Удалить входящее факсимильное сообщение

Параметры URL

Имя	Тип
fax_uuid	string
client_id	string

GET /client/{client_id}/fax/out/

GET /client/{client_id}/fax/out/

Получить список исходящих факсимильных сообщений

Параметры URL

Имя	Тип
client_id	string

Параметры запроса

Имя	Тип
start_datetime	string
extension_id	integer
end_datetime	string
order	string

Поля ответа

Имя	Тип
id	long
status	string
dst_num	string
extension_id	long
datetime	string

Ресурсы раздела "Группа внутренних номеров”

GET /extension_group/{ext_group_id}/fax/in/

GET /extension_group/{ext_group_id}/fax/in/

Получить список входящих факсимильных сообщений для группы внутренних номеров

Параметры URL

Имя	Тип
ext_group_id	string

Параметры запроса

Имя	Тип
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
order	string
extension_id	integer

Поля ответа

Имя	Тип
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /extension_group/{ext_group_id}/fax/in/{fax_uuid}

GET /extension_group/{ext_group_id}/fax/in/{fax_uuid}

Получить файл входящего факсимильного сообщения

Параметры URL

Имя	Тип
ext_group_id	string
fax_uuid	string

Ресурсы раздела "Внутренний номер”

PUT /extension/{extension_id}/fax/

PUT /extension/{extension_id}/fax/

Обновить конфигурацию факса

Параметры URL

Имя	Тип
extension_id	string

Параметры JSON

Имя	Тип	Обязательный
email_to_fax_accept	string	нет
fax_in_format	string	нет
fax_mailto	string	нет
fax_out_greeting	long	нет

Поля ответа

Имя	Тип
email_to_fax_accept	string
fax_in_format	string
fax_mailto	string
fax_out_greeting	long

GET /extension/{extension_id}/fax/

GET /extension/{extension_id}/fax/

Получить конфигурацию факса

Параметры URL

Имя	Тип
extension_id	string

Поля ответа

Имя	Тип
email_to_fax_accept	string
fax_in_format	string
fax_mailto	string
fax_out_greeting	long

GET /extension/{extension_id}/fax/in/

GET /extension/{extension_id}/fax/in/

Получить список входящих факсимильных сообщений для внутреннего номера

Параметры URL

Имя	Тип
extension_id	string

Параметры запроса

Имя	Тип
start_datetime	string
uuid	array [string]
destination	array [string]
caller_id	array [string]
end_datetime	string
order	string

Поля ответа

Имя	Тип
caller_id	string
client_id	long
datetime	string
destination	string
extension_group_id	long
extension_id	long
file_size	long
uuid	string

GET /extension/{extension_id}/fax/in/{fax_uuid}

GET /extension/{extension_id}/fax/in/{fax_uuid}

Получить файл входящего факсимильного сообщения

Параметры URL

Имя	Тип
extension_id	string
fax_uuid	string

POST /extension/{extension_id}/fax/out/

POST /extension/{extension_id}/fax/out/

Отправить факсимильное сообщение

Параметры URL

Имя	Тип
extension_id	string

Поля ответа

Имя	Тип
datetime	string
dst_num	string
id	long
status	string

GET /extension/{extension_id}/fax/out/

GET /extension/{extension_id}/fax/out/

Получить список исходящих факсимильных сообщений

Параметры URL

Имя	Тип
extension_id	string

Параметры запроса

Имя	Тип
start_datetime	string
order	string
end_datetime	string

Поля ответа

Имя	Тип
datetime	string
dst_num	string
id	long
status	string

PUT /extension/{extension_id}/fax/out/{message_id}

PUT /extension/{extension_id}/fax/out/{message_id}

Повторить или отменить отправку факсимильного сообщения

Параметры URL

Имя	Тип
extension_id	string
message_id	integer

Параметры запроса

Имя	Тип
action	string

Поля ответа

Имя	Тип
datetime	string
dst_num	string
id	long
status	string

GET /extension/{extension_id}/fax/out/{message_id}

GET /extension/{extension_id}/fax/out/{message_id}

Получить информацию об исходящем факсимильном сообщении

Параметры URL

Имя	Тип
extension_id	string
message_id	integer

Поля ответа

Имя	Тип
datetime	string
dst_num	string
id	long
status	string