如何設定 Dropbox Fax API

已更新 Sep 22, 2025

In this article

person icon

本文資訊適用於付費版 Dropbox Fax 方案用戶。

請注意：Dropbox Fax 端點已從 v1 更新為 v3。v1 端點將停止維護。進一步瞭解升級至新版 v3 端點的相關內容及其對開發人員的好處。

本文同時說明如何使用 v1 端點設立 Dropbox Fax API、確認其運作正常，以及在需要時購買額外的傳真線路。

如何使用 v1 端點設定 Dropbox Fax API

若要開始使用 v1 端點，請按照以下方式操作：

  1. 傳送電子郵件至 support@hellosign.com，內容註明您要用於 Dropbox Fax 帳戶的電子郵件地址。待 Dropbox Fax API 存取權啟用後，您會收到回覆。進一步瞭解 Dropbox Fax API 價格。
  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"
另一個例子（請記得進行網址編碼）： 
curl "https://myemail%40hellofax.com:fakepassword%40api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"

回應內容將是您帳戶設定的 JSON 表示形式。

  1. 若要使用 POST 再次為您接收和傳送的傳真新增 Callback 網址，請按照以下方法操作：
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 方式傳送到您的 Callback 網址，因此您不需要分開擷取。

  1. 如要檢視可用的傳真線路，請按照以下方法操作：
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/FaxLines"

回應內容將包含您在註冊付費版方案時所選擇的 FaxLine。

  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"

此操作將開始傳真傳送流程。收到 200 HTTP 回應並不保證傳真會傳送成功，且可能會發生檔案轉換錯誤。不過，一旦傳真的 StatusCode 變成 E（即錯誤）或 S（即成功），您將在步驟 4 中提供的 Callback 網址收到一個 POST。深入瞭解 Callback 事件。

可能的 StatusCode 值：

  • T = 傳輸中/傳送中。
  • P = 待處理/轉換中。
  • S = 已成功傳送。
  • E = 錯誤。無法轉換或完整傳送。
  • H = 暫停中。如果您有未確認的帳戶，或者您沒有訂購月繳方案，且傳真頁數已用完，就會發生此錯誤。

可能的 ErrorCode 值（僅在 StatusCode 設為 E 時可供參考）：

  • B = 收到忙線信號。
  • N = 無回應。
  • A = 未分配的號碼（通常表示已中斷連線）。
  • D = 線路中斷或無法連線。
  • L = 此號碼已被列入黑名單（美國號碼不會列入黑名單）。
  • U = 未知錯誤。這通常發生在有人接聽來電，或傳真傳輸過程中發生錯誤時。

備註 ：

  • 如果您發送傳真，而接收者的傳真機支援訂購者識別碼 (CSID)，則來電顯示將顯示您的主要傳真號碼，或您在「來電者」參數中設的傳真號碼。您的主要傳真號碼會顯示在傳真上。如果您有多條 Dropbox 傳真專線，您可以在網址中加入「來電者」參數，選擇要用作發送傳真的專線：
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`

針對「來電者」值的格式，請參閱撥號/FaxLines 傳回的「號碼」欄位（請參閱上述步驟 5）。

  • 只需建立「檔案」和/或「發送至」參數陣列，您便可以上傳多個檔案，並在一次撥號中發送多份傳真：
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 方式發送到您的 Callback 後，傳真會儲存在我們的伺服器上，並可在您的「文件」畫面中檢視。
  • 每天最多只能有 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. 您可以在步驟 8 的 API 撥號傳回的 JSON 回應中找到傳輸 GUID。此外，您可以略過傳輸 GUID，以檢查所有傳輸的狀態：
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions"
這些結果會分頁顯示。您可以設定 Page 和 PageSize 網址參數來取得不同的頁面。請參閱 FirstPageUri、NextPageUri、PreviousPageUri 和 LastPageUri 回應元素，以瞭解分頁的運作方式。
highlighter icon

備註 ：

  • 針對透過 API 發送的傳真，您不會收到電子郵件確認。
  • 針對已接收的傳真，您可能會收到電子郵件通知（取決於通知設定）。

  1. 一旦傳真的狀態代碼設為 S 或 E，請確認您發送傳真的 Callback 網址已觸發，接著應該會收到一個包含 [json] 參數的 POST，其中包含您會收到的所有撥號回應內容（請參閱步驟 1）。

若因伺服器或網路問題導致 POST Callback 失敗，Dropbox 會依下列時間間隔重試：

  • 15 分鐘
  • 45 分鐘
  • 1 小時 30 分鐘
  • 2 小時 45 分鐘
  • 4 小時
  • 8 小時 15 分鐘
  • 16 小時 30 分鐘

在每個間隔期間，如果未收到 200 回應代碼，Dropbox 可能會多次嘗試該 POST。

  1. 如果您將傳真發送到自己的 Dropbox 傳真號碼（適用於測試），請確認您接收傳真的 Callback 網址也已觸發。
  2. 列出您購買的 FaxLine：
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines"
  1. 如要刪除 FaxLine，請對該 FaxLine 的網址執行 DELETE 呼叫（在上一步驟的回應中設定）：
curl -u "[your username]:[your password]" 
     -X DELETE "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines/2132935579"
如果操作成功，您會收到 200 回應提示。
highlighter icon

請注意：Callback 中的 JSON 包含 [交易] 而不是 [傳輸]，這是已知的問題。在下一個版本的 API 將會修正此錯誤。

這篇文章對您有幫助嗎?

Let us know how why it didn't help:

Thanks for letting us know!

感謝您的意見。

相關文章

Dropbox Sign API 中的終端使用者帳戶

Dropbox Sign API 方案的工作團隊身分

Dropbox Sign API 說明書

Dropbox Sign API 額度使用量說明

Відповіді спільноти

其他取得協助的方式

雙人圖示
社群
Twitter Icon
X
對話框圖示
聯絡支援團隊