如何设置 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"
另一个示例（请记住进行 URL 编码）： 
curl "https://myemail%40hellofax.com:fakepassword%40api.hellofax.com/v1/Accounts/15da1c48b10c96a903eb1bac3d592fbed24ebc35"

响应将为您帐户设置的 JSON 形式。

  1. 如需使用 POST 再次为您的传入和传出传真添加回调 URL：
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"

响应包括您在订阅高级套餐时选择的 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 步中提供的回调 URL 收到一个 POST。了解有关回调事件的更多信息。

可能的 StatusCode 值：

  • T = 正在传输/正在发送。
  • P = 待处理/转换中。
  • S = 发送成功。
  • E = 错误。转换失败或未能完全发送。
  • H = 暂停。如果您未确认帐户，或者您没有月度订阅且传真页数已用完，则会发生此错误。

可能的 ErrorCode 值（仅在 StatusCode 设置为 E 时参考）：

  • B = 收到占线信号。
  • N = 无应答。
  • A = 未分配号码（通常意味着已断开连接）。
  • D = 线路已断开或无法访问。
  • L = 此号码已被列入拒绝列表（美国号码不会发生此情况）。
  • U = 未知错误。这通常发生在有人接线或传真传输过程中发生错误时。

注意：

  • 如果您发送传真，并且接收者的传真机支持用户识别 (CSID)，则呼叫者 ID 将显示您的主要传真号码或您在 "From" 参数中指定的传真号码。您的主要传真号码将显示在传真中。如果您有多条 Dropbox Fax 线路，则可以在 URL 中添加 "From" 参数，选择传真机发送传真的线路：
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" 值的格式，请参阅通过调用/FaxLines 返回的 "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. 您可以在第 8 步 API 调用所返回的 JSON 响应中找到传输 GUID。此外，您可以省略传输 GUID，查看所有传输的状态：
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Your Account GUID]/Transmissions"
这些结果是分页的。您可以通过指定 Page 和 PageSize URL 参数来获取不同的页面。请参阅 FirstPageUri、NextPageUri、PreviousPageUri 和 LastPageUri 响应元素，了解分页的运作方式。
highlighter icon

注意：

  • 对于通过 API 发送的传真，您不会收到电子邮件确认。
  • 对于接收的传真，您可能会收到电子邮件通知，这取决于您的通知设置。

  1. 传真的状态代码设置为 S 或 E 后，请验证您的传出传真回调 URL 是否已触发。该 URL 应会收到一个带有 "json" 参数的 POST，其中包含调用所应获得的所有响应内容（见第 1 步）。

如果服务器或网络问题导致 POST 回调不成功，Dropbox 将按以下时间间隔重试：

  • 15 分钟
  • 45 分钟
  • 1 小时 30 分钟
  • 2 小时 45 分钟
  • 4 小时
  • 8 小时 15 分钟
  • 16 小时 30 分

在每个间隔期内，如果未收到 200 响应代码，Dropbox 可能会多次尝试 POST。

  1. 如果您将传真发送到您自己的 Dropbox Fax 号码（用于测试），请务必验证您的传入传真回调 URL 是否也被触发。
  2. 列出您购买的 FaxLines：
curl -u "[your username]:[your password]" \
        "https://api.hellofax.com/v1/Accounts/[Account GUID]/FaxLines"
  1. 要删除 FaxLine，请对该 FaxLine 的 Uri 执行 DELETE 调用（在上一步的响应中指定）：
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 中更正拼写错误。

这篇文章有用吗？

请告诉我们为什么它没有帮助：

感谢您告诉我们！

谢谢您的意见！

相关文章

Dropbox Sign API 中的最终用户帐户

Dropbox Sign API 套餐中的团队角色

Dropbox Sign API 文档

Dropbox Sign API 限额使用情况说明

社区答案

获取帮助的其他方式

描绘两个人的图标
社区
Twitter Icon
X
描绘对话泡泡的图标
联系支持人员