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

В этой статье содержится информация о том, как настроить 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 и получите информацию о конфигурации своего аккаунта:

Пример:

Другой пример (не забудьте про кодирование URL-адреса):

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

4. Чтобы снова добавить URL-адреса обратного вызова для входящих и исходящих факсов с помощью метода POST:

5. Чтобы посмотреть доступные линии факсимильной связи:

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

6. Перед тем как вы сможете купить номер факса, нам нужно будет проверить доступные телефонные коды штата с помощью метода GET:

7. Купите номер факса с одним из доступных кодов города (см. шаг 6):

8. Чтобы отправить факс:

Это действие запустит процесс отправки факса. Если вы получили код ответа 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-адресу:

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

• Вы можете загрузить несколько файлов и отправить более одного факса за один вызов. Для этого достаточно создать массивы параметров «file» и/или «To»:

или

• Вы можете добавить титульный лист, созданный Dropbox Fax, указав один или несколько из следующих параметров: CoverPageTo, CoverPageFrom и CoverPageMessage.
• Факсы, отправленные с помощью API, не сохраняются на наших серверах после отправки — они удаляются. Поэтому вы не можете просматривать их в пользовательском интерфейсе. Однако входящие факсы, отправленные методом POST на ваш URL-адрес обратного вызова, хранятся на наших серверах и доступны для просмотра на экране «Документы».
• В день вам доступно не более 200 факсов в статусе ожидания отправки. Если вы достигнете этого лимита, отобразится ошибка 429:

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

1. Вы найдете GUID передачи в ответе JSON, полученном при вызове API на шаге 8. Однако есть и другой способ проверить статус всех отправленных факсов:

Эти результаты разбиты на страницы. Вы сможете получить доступ к разным страницам, указав значение для следующих параметров URL-адреса: Page и PageSize. Ознакомьтесь с элементами ответа FirstPageUri, NextPageUri, PreviousPageUri и LastPageUri, чтобы узнать, как работает разбивка на страницы.

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

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

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

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

3. Если вы в целях тестирования отправили факс на собственный номер Dropbox Fax, убедитесь, что также был задействован URL-адрес обратного вызова входящего факса.
4. Перечислите приобретенные вами линии факсимильной связи:

5. Чтобы удалить линию факсимильной связи, отправьте запрос «DELETE» для нужного URL-адреса (см. в ответе, полученном на предыдущем шаге):

Если операция прошла успешно, вы получите ответ 200.