如何設定 Dropbox Fax API

已更新 Dec 04, 2025

In this article

person icon

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

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

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

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

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

  1. 傳送電子郵件至 [email protected]，內容註明您要用於 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 "[email protected]: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 "[email protected]"

此操作將開始傳真傳送流程。收到 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 [email protected]`

針對「來電者」值的格式，請參閱撥號/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][email protected]' \
     -F 'file[1][email protected]' \
     -F 'To[0]=[destination fax number 0]' \
     -F 'To[1]=[destination fax number 1]'
  • 您可以設定以下一個或多個參數來新增 Dropbox Fax 產生的封面：CoverPageTo、CoverPageFrom 和 CoverPageMessage。
  • 一旦傳真成功發送，API 發送的傳真就會移除，不會儲存在我們的伺服器上。因此，您無法在使用者介面中檢視傳真。不過，成功將接收到的傳真以 POST 方式發送到您的 Callback 後，傳真會儲存在我們的伺服器上，並可在您的「文件」畫面中檢視。
  • 每天最多只能有 200 份待處理的傳真。如果達到此限制，您將看到 429 錯誤提示：