Факс (/fax/)

Owned by Dmitri Savolainen
Last updated: Aug 28, 2020 by Asia Khalitova (Unlicensed)
3 min read

Мы обновили документацию, актуальная версия страницы доступна по ссылке: Факс (/fax/)

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

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

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

Пример

метод
ресурс
данные
ответ
PUT
/extension/122/fax/

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

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

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

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

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

Параметр
Тип
Описание
caller_id

string

Номер отправителя сообщения
client_idinteger

Идентификатор клиента

datetimestringДата и время получения сообщения
destinationstringНомер получателя сообщния
extension_group_idintegerИдентифиатор группы добавочных. Может иметь значение null, если добавочный не состоит ни в одной из групп
extension_idintegerИдентифиатор добавочного
file_sizeintegerРазмер файла сообщения 
uuidstringИдентификатор сообщения

Пример

метод
ресурс
данные
ответ
GET
/extension/122/fax/in/


[
{
"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

да
Номер, на который требуется отправить факс
filefileда

Файл в формате tiff или pdf. Максимальный размер файла – 10 мегабайт.

Пример HTTP-запроса

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

Запрос
Request URL: https://hostname.domain/api/ver1.0/extension/30/fax/out/
Request Method: POST
Authorization:Bearer token
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryuQN99hiRT3XAQXrK
Host: hostname.domain
------WebKitFormBoundaryuQN99hiRT3XAQXrK
Content-Disposition: form-data; name="file"; filename="faxtest.tif"
Content-Type: image/tiff


------WebKitFormBoundaryuQN99hiRT3XAQXrK
Content-Disposition: form-data; name="dst_num"

1234567
------WebKitFormBoundaryuQN99hiRT3XAQXrK--
Ответ
{
 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

метод
ресурс
данные
ответ
GET
/extension/122/fax/out/174

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

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

Параметр
Тип
Описание
dst_num

string

Номер, на который был отправлено факсимильное сообщение
datetime

string

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

integer

Идентификатор факсимильного сообщения
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

 

метод
ресурс
данные
ответ
PUT
/extension/122/fax/out/175?action=retry

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



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

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

Поля ответа

Имя

Тип

uuid

string

destination

string

caller_id

string

datetime

string

file_size

integer

extension_id

integer

client_id

integer

extension_group_id

integer

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

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

Параметры URL

Имя

Тип

fax_uuid

string

client_id

string

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

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

Параметры URL

Имя

Тип

fax_uuid

string

client_id

string

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

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

Параметры URL

Имя

Тип

client_id

string

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

Имя

Тип

start_datetime

string

extension_id

string

end_datetime

string

order

string

Поля ответа

Имя

Тип

id

integer

status

string

dst_num

string

extension_id

integer

datetime

string

Ресурсы раздела "Группа добавочных"

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

Поля ответа

Имя

Тип

uuid

string

destination

string

caller_id

string

datetime

string

file_size

integer

extension_id

integer

client_id

integer

extension_group_id

integer

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

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

Параметры URL

Имя

Тип

ext_group_id

string

fax_uuid

string

Ресурсы раздела "Добавочный"

PUT /extension/{extension_id}/fax/

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

Параметры URL

Имя

Тип

extension_id

string

Параметры JSON

Имя

Тип

Обязательный

fax_mailto

string

нет

Поля ответа

Имя

Тип

fax_mailto

string

GET /extension/{extension_id}/fax/

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

Параметры URL

Имя

Тип

extension_id

string

Поля ответа

Имя

Тип

fax_mailto

string

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

Поля ответа

Имя

Тип

uuid

string

destination

string

caller_id

string

datetime

string

file_size

integer

extension_id

integer

client_id

integer

extension_group_id

integer

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

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

Параметры URL

Имя

Тип

extension_id

string

fax_uuid

string

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

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

Параметры URL

Имя

Тип

extension_id

string

Поля ответа

Имя

Тип

status

string

dst_num

string

id

integer

add_time

string

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

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

Параметры URL

Имя

Тип

extension_id

string

Поля ответа

Имя

Тип

status

string

dst_num

string

id

integer

add_time

string

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

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

Параметры URL

Имя

Тип

extension_id

string

message_id

integer

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

Имя

Тип

action

string

Поля ответа

Имя

Тип

status

string

dst_num

string

id

integer

add_time

string

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

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

Параметры URL

Имя

Тип

extension_id

string

message_id

integer

Поля ответа

Имя

Тип

status

string

dst_num

string

id

integer

add_time

string


Похожие разделы