Как настроить API Dropbox Fax

Обновление Oct 17, 2025

In this article

person icon

Данная информация предназначена для пользователей платных тарифных планов Dropbox Fax.

Примечание. Конечные точки Dropbox Fax изменились с v1 на v3. Конечные точки v1 больше не будут поддерживаться. Подробнее о переходе на новые конечные точки v3 и преимуществах для разработчиков.

В этой статье содержится информация о том, как настроить API Dropbox Fax с использованием конечных точек v1, убедиться, что API работает, и при необходимости приобрести дополнительные факсимильные линии.

Как настроить API Dropbox Fax с использованием конечных точек v1

Чтобы приступить к использованию конечных точек v1, выполните следующие действия.

  1. Напишите нам по адресу support@hellosign.com, указав адрес электронной почты, который вы хотите использовать для своего аккаунта Dropbox Fax. Вы получите ответ, как только будет активирован доступ к API Dropbox Fax. Подробнее о тарифах для API Dropbox Fax.
  2. Войдите в аккаунт Dropbox Fax. Запишите GUID своего аккаунта: этот идентификатор потребуется для большинства запросов к API (или конечным точкам).
  3. Выполните свой первый запрос API и получите информацию о конфигурации своего аккаунта:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]"
Пример:
curl -u "myemail@hellofax.com:fakepassword" 
        "https://api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"
Другой пример (не забудьте про кодирование URL-адреса):
curl "https://myemail%40hellofax.com:fakepassword%40api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"

В ответ вы получите файл JSON с настройками вашего аккаунта.

  1. Чтобы снова добавить URL-адреса обратного вызова для входящих и исходящих факсов с помощью метода POST:
curl -u"[your username]:[your password]" \
     -d "DefaultInboundFaxCallbackUrl=https://www.example.com/inboundFax" \
     -d "DefaultOutboundFaxCallbackUrl=https://www.example.com/outboundFax" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]"
highlighter icon

Примечание. Входящие факсы будут отправляться методом POST на ваш URL-адрес обратного вызова, поэтому вам не нужно будет получать их отдельно.

  1. Чтобы посмотреть доступные линии факсимильной связи:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/FaxLines"

Ответ будет включать линии факсимильной связи, выбранные при покупке тарифного плана Premium.

  1. Перед тем как вы сможете купить номер факса, нам нужно будет проверить доступные телефонные коды штата с помощью метода GET:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/AreaCodes?StateCode=CA"
  1. Купите номер факса с одним из доступных кодов города (см. шаг 6):
curl -u "[your username]:[your password]" \
     -d "AreaCode=[area code from step 7]" \ 
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/FaxLines"
  1. Чтобы отправить факс:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]" \ 
     -F "file=@myfile.pdf"

Это действие запустит процесс отправки факса. Если вы получили код ответа HTTP 200, отправка факса не гарантируется, поскольку может возникнуть ошибка при преобразовании файла. Однако, как только статус факса изменится на E (ошибка) или S (успешная отправка), вы получите запрос POST на URL-адрес обратного вызова, указанный на шаге 4. Подробнее о событиях обратного вызова.

Возможные коды состояния перечислены ниже.

  • T = передача/отправка.
  • P = ожидание/преобразование.
  • S = успешная отправка.
  • E = ошибка. Не удалось преобразовать или отправить файл целиком.
  • H = отправка приостановлена. Эта ошибка возникает, если вы не подтвердили данные аккаунта или у вас закончилось количество страниц факса, доступное без покупки месячного тарифного плана.

Возможные коды ошибок (только в случае кода состояния E) перечислены ниже.

  • B = получен сигнал «занято».
  • N = нет ответа.
  • A = неназначенный номер (обычно означает, что он был отключен).
  • D = линия отключена или недоступна.
  • L = номер находится в черном списке (эта ошибка обычно не возникает, если используется номер в США).
  • U = неизвестная ошибка. Обычно она возникает, когда во время передачи факса абонент снимает трубку или происходит ошибка.

Обратите внимание:

  • Если вы отправляете факс и факсимильный аппарат получателя поддерживает идентификатор подписчика (CSID), то в качестве идентификатора вызывающего абонента будет отображаться ваш основной номер факса или номер факса, указанный для параметра «From». Ваш основной номер будет указан на самом факсе. Если у вас несколько линий Dropbox Fax, вы можете выбрать, какую из них использовать в качестве отправляющего факсимильного аппарата, добавив параметр «From» к URL-адресу:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[destination phone number]&From=[your fax line phone number]" \
     -F file=@myfile.pdf`

Формат значения параметра «From» см. в поле «Number», возвращаемом при вызове или выборе линий факсимильной связи (см. шаг 5 выше).

  • Вы можете загрузить несколько файлов и отправить более одного факса за один вызов. Для этого достаточно создать массивы параметров «file» и/или «To»:
curl -u "[your username]:[your password]" \
     -F file[]="@1.pdf" -F file[]="@2.txt" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions?To=[phone number in all digits]"
или
curl -X POST https://[your username]:[your password]@api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions -F 'file[0]=@file1.pdf' \
     -F 'file[1]=@file2.pdf' \
     -F 'To[0]=[destination fax number 0]' \
     -F 'To[1]=[destination fax number 1]'
  • Вы можете добавить титульный лист, созданный Dropbox Fax, указав один или несколько из следующих параметров: CoverPageTo, CoverPageFrom и CoverPageMessage.
  • Факсы, отправленные с помощью API, не сохраняются на наших серверах после отправки — они удаляются. Поэтому вы не можете просматривать их в пользовательском интерфейсе. Однако входящие факсы, отправленные методом POST на ваш URL-адрес обратного вызова, хранятся на наших серверах и доступны для просмотра на экране «Документы».
  • В день вам доступно не более 200 факсов в статусе ожидания отправки. Если вы достигнете этого лимита, отобразится ошибка 429:
Error sending fax. Status: 429; Message: Please wait. You already have at least 200 transmissions that are currently pending or transmitting.

Как проверить статусы факсов?

curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions/[Transmission GUID]"
  1. Вы найдете GUID передачи в ответе JSON, полученном при вызове API на шаге 8. Однако есть и другой способ проверить статус всех отправленных факсов:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions"
Эти результаты разбиты на страницы. Вы сможете получить доступ к разным страницам, указав значение для следующих параметров URL-адреса: Page и PageSize. Ознакомьтесь с элементами ответа FirstPageUri, NextPageUri, PreviousPageUri и LastPageUri, чтобы узнать, как работает разбивка на страницы.
highlighter icon

Обратите внимание:

  • Для факсов, отправленных через API, не приходит подтверждение по электронной почте.
  • Если вы хотите получать уведомления о поступивших факсах, измените настройки уведомлений.

  1. Как только код статуса изменится на S или E, убедитесь, что был задействован URL-адрес обратного вызова исходящего факса. Он должен получить запрос POST с параметром «json», содержащим всю информацию, которую вы получили в ответе на вызов (см. шаг 1).

Если обратный вызов методом POST невозможен из-за ошибки сервера или сети, Dropbox повторит попытку через следующие временные интервалы:

  • 15 минут
  • 45 минут
  • 1 час 30 минут
  • 2 часа 45 минут
  • 4 часа
  • 8 часов 15 минут
  • 16 часов 30 минут

Если не будет получен код ответа 200, Dropbox может выполнить несколько попыток отправки запроса POST в рамках каждого из перечисленных интервалов.

  1. Если вы в целях тестирования отправили факс на собственный номер Dropbox Fax, убедитесь, что также был задействован URL-адрес обратного вызова входящего факса.
  2. Перечислите приобретенные вами линии факсимильной связи:
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines"
  1. Чтобы удалить линию факсимильной связи, отправьте запрос «DELETE» для нужного URL-адреса (см. в ответе, полученном на предыдущем шаге):
curl -u "[your username]:[your password]" 
     -X DELETE "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines/2132935579"
Если операция прошла успешно, вы получите ответ 200.
highlighter icon

Примечание. Существует известная проблема, когда ответ JSON для обратных вызовов содержит значение «Transaction» (а не «Transmission»). Речь идет об опечатке, которая будет исправлена в следующей версии API.

Оказалась ли эта статья полезной?

Расскажите, почему статья вам не помогла:

Спасибо, что поделились своим мнением!

Благодарим за отзыв!