FAX API

Обработка факса сервисом Аксател

API управления

Внешние системы должны обращаться на адрес http(s)://fqdn_ws_role/api/token/v1/{token}/files/{command}

• fqdn_ws_role - адрес URL роли WS (Веб-сервера управления)

• {token} - значение локального токена из созданного публичного канала

• {command} - команда управления (описаны ниже)

Команды управления

Загрузка файлов в домен

upload

http(s)://fqdn_ws_role/api/token/v1/{token}/files/upload Метод - POST Content-Type - multipart/form-data Body - Form В ответе json приходит результат загрузки файла. Успешный ответ содержит "resultcode": 0, "resultmsg": "OK". Пример успешного ответа:

{
"resultcode": 0,
"resultmsg": "OK",
"data":{
"upload":[
{
"name": "002.mp3",
"res": "ok"
}
]
}
}

Неуспешный ответ содержит код ошибки и ее описание.

Пример неуспешного ответа:

{ 
 "resultcode": 1501,
  "resultmsg": "Not enough free disk space"
 }

Получение списка файлов.

list

http(s)://fqdn_ws_role/api/token/v1/{token}/files/list

Метод - GET

В ответе json с полным списком файлов следующего вида

{
 "resultcode": 0,
  "resultmsg": "OK",
   "data": { "files": [ 
   {
    "file": {
     "name": "205-a10-02.zip"
    }
     },
      { 
      "file": {
       "name": "queue_wait_sgk.mp3" 
       }
      }
    ] 
  } 
}

Скачивание файла в браузере.

download

http(s)://fqdn_ws_role/api/token/v1/{token}/files/download?file={filename}

Метод - GET {filename} - имя файла для скачивания

Пример успешного ответа:

Скачанный файл будет иметь название download и не будет иметь расширения. Чтобы открыть этот файл нужно будет изменить его расширение на указанное в запросе.

Удаление файла.

delete

http(s)://fqdn_ws_role/api/token/v1/{token}/files/delete?file={filename}

Метод - GET {filename} - имя файла для удаления

Хранение файла и получение доступа из сценариев Файл хранится в директории fsync домена в поддиректории /data/tokens/.

Пример .../syncfolder/domains/domain.demo.axatell/data/tokens/205-a10-02.zip Для получения доступа к файлу в IVR/SVC сценарии можно через формирования пути к файлу следующего вида:

путь = syn_domain() файл = tokens/205-a10-02.zip

Пример получения файла в Выражениях Сценария:

makepath(syn_domain(),"tokens/002.mp3")

• 002.mp3- имя файла

• tokens - константа имени каталога

Результат успешного выполнения:

{
"resultcode": 0,
"resultmsg": "OK"
}

Отправка факса

sendfax

http(s)://fqdn_ws_role/api/token/v1/{token} Метод - POST Content-Type - application/json

• action - действие, которое нужно совершить над списком факсов (sendfax — отправить)

• recipient - получатель факса

• voiceDocumentSID- <необязательный параметр> — идентификатор предварительно загруженного голосового файла

• terminalId - идентификатор телефонного номера, который будет назначен в качестве номера-отправителя

• attachment - идентификатор предварительно загруженного файла в формате TIF

• sip - ответ провайдера описан в соответствии с стандартом

SIP ответы и их значения

• status - статус отправки факса

• error - содержит описание ошибок при отправке факса: "файл не найден", "номер не соответствует маске"

Пример:

{
 "action":"sendfax",
 "recipient": 375291554499,
 "voiceDocumentSID":"002.mp3"
 "terminalId": 301
 "attachment":"123123.tif"
 }
 

Пример успешной отправки:

"sip_code": "200",
"success": "true",
"error": "null",
"status": "sent"
}

Допускается отправка сообщения через pop протокол. Для реализации требуется передавать сообщение с темой письма содержащий номер телефона и 1 приложением файла в формате TIF. На сервере предварительно настраивается маска с именем отправителя с которым разрешена отправка сообщения user{mask}@fqdn После отправки приходить ответное сообщение с статусом отправки на обратный e-mail адрес.

Инициализация базы данных

init_fax

Требуется выполнить для первично инициализации

http(s)://fqdn_ws_role/api/token/v1/{token} Метод - POST Content-Type - application/json Body - Text

• action - константа

• domain - имя текущего домена

• drop - true = удалить если ранее было созданы схемы и таблицы, false = не удалять ничего

Пример:

{
  "action":"init_fax",  
  "domain":"domain.a1.axatel.by",    
  "drop":"true"    
}

Ответ успешного выполнения:

{
"received": true
}

Запрос информации по факсам

fax_history

http(s)://fqdn_ws_role/api/token/v1/{token} Метод - POST Content-Type - application/json

Body:

• action - константа

• "type- тип incoming | outgoing

• from_dt:"2020-12-16 20:00", //время UTC начала списка. Может быть дата или дата-время

• till_dt- время UTC окончания списка. Может быть дата или дата-время

• fields- список полей, которые выводить, можно указывать через запятую.

  • * - вывести все поля

  • id

  • type

  • remotenum

  • start_dt

  • stop_dt

  • result

  • url

Пример запроса:

{
  "action":"history", 
  "type":"outgoing",   
  "from_dt":"2020-12-16 20:00", 
  "till_dt":"2020-12-20 23:30",  
  "fields":"*"		
}

Пример успешного вывода:

{
"data":[
{
"id": "940fbbf2-0176-81d6-990b-005056011d6c",
"type": "outgoing",
"remotenum": "3880456",
"start_dt": "2020-12-20T20:28:13.84",
"stop_dt": "2020-12-20T20:28:30.38",
"result": "success",
"url": "https://domain.a1.axatel.by/callrecords/domains/demo.a1.axatel.by/data/fax/outgoing/mtu1otezoty1nw53d5.tiff"
},
]
}

Описание поля Result

success - успешная обработка failed - ошибка receiving - в процессе приемки dialing - набор номера sending - процесс отправки