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

Перед отправкой

Используйте номер отправителя, который вы вправе указывать, и отправляйте факс получателю, который его ожидает. Этот запрос создаёт реальную передачу, за которую может взиматься плата. Для наиболее предсказуемого определения страниц используйте подготовленный документ PDF или TIFF. Ответ о постановке в очередь подтверждает принятие запроса, а не доставку.

Используйте активную учётную запись API MultiTEL. Для учётной записи с паролем передавайте учётные данные по схеме HTTP Basic, а для учётной записи с токеном — токен Bearer. Права учётной записи и ограничения по IP-адресам продолжают действовать. Не используйте внутренние учётные данные фонового обработчика.

Загрузите документ

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

Поля запроса
Поле	Обязательное	Назначение
`from_number`	Да	Номер отправителя, который вы вправе использовать. Укажите его в международном формате, начиная с + и кода страны.
`to_number`	Да	Номер факса получателя в международном формате.
`fax_file`	Да, для составного запроса	Загружаемый документ. Предоставьте curl возможность установить Content-Type и разделитель частей составного запроса.
`webhook_url`	Нет	Необязательный URL обратного вызова по протоколу HTTP или HTTPS; предпочтителен HTTPS. Содержимое обратных вызовов и гарантии их доставки ещё проверяются: для отслеживания статуса по описанной в документации процедуре периодически запрашивайте fax_status.

Также принимается JSON с Content-Type: application/json, теми же полями номеров и необязательным полем webhook_url, а также полями file_name и file_b64. Поле file_b64 содержит байты документа, закодированные со строгим соблюдением формата Base64, без префикса data:. Корректное поле fax_file в составном запросе имеет приоритет. Этот API не предназначен для загрузки файлов по URL.

Ограничения на документы и запросы на отправку

Приложение принимает документы размером не более 15,728,640 байт после декодирования (15 MiB) с расширениями pdf, tif, tiff, jpg, jpeg, png, doc, docx или txt. Допустимое расширение не гарантирует, что сервис сможет подсчитать или преобразовать страницы. Ограничения инфраструктуры на размер запросов могут быть ниже, а кодирование Base64 увеличивает размер запроса.

Для каждой учётной записи приложение в настоящее время допускает одно задание в очереди или в процессе отправки на один и тот же номер, не более пяти запросов на отправку на этот номер за предыдущий час и не более 50 запросов на отправку всего за предыдущий час. Ответ о превышении частотного ограничения содержит код API 429. Подождите перед повторной попыткой; не пытайтесь обходить ограничения.

Сохраните идентификатор задания

Проверяйте как результат HTTP, так и поле status.code в JSON. Ошибки в JSON могут возвращаться с HTTP 200. Успешный ответ в формате JSON содержит status и response; в примерах используются вымышленные данные.

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

Периодически запрашивайте fax_status с использованием response.job_id. Если ответ на запрос отправки потерян, перед повторной отправкой проверьте исходящие сообщения в портале: повторные запросы могут создавать отдельные передачи. Этот обработчик не предоставляет клиентского параметра идемпотентности.

Ошибки и проверки баланса

Коды API включают 400 при отсутствии полей, некорректном URL обратного вызова, отклонении документа или ошибке определения страниц; 401 при отсутствии аутентификации; 402, когда предварительная стоимость факса вместе с предварительной стоимостью заданий в очереди и в процессе отправки превышает доступный баланс учётной записи; 429 при превышении частотных ограничений; и 500 при сбое подготовки к отправке. Конкретную причину смотрите в status.msg.

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