GlobFax API V2 概述¶

概述¶

GlobFax API 是一套基于 RESTful 架构的接口，为开发者提供完整的传真发送、状态查询和账户管理能力。通过 API，您可以轻松地将传真功能集成到自己的业务系统、工作流或应用中，实现自动化、批量化的传真发送与管理。

API 端点： http://api.globfax.com

核心特性¶

• 多文件支持：单次任务最多支持 3 个文件，支持 PDF、DOC、DOCX、TXT、JPG、PNG 等常见格式
• 批量发送：单次任务最多可向 100 个收件人发送传真
• 预约发送：支持指定未来某个时间点自动发送
• 实时状态查询：提供任务级别和收件人级别的状态查询接口
• Webhook 回调：配置回调地址后，任务状态变化时系统主动推送通知，避免轮询
• 账户管理：查询账户余额、状态及 Webhook 配置

认证方式¶

所有 API 请求均采用 双 Header 认证机制，确保安全可靠。

在请求头中携带以下信息：

X-API-Key: 您的API密钥
X-API-Secret: 您的API秘钥

开通 API 功能、获取和管理 API 凭证的详细步骤，请参阅 用户认证 文档。

API 通用约定¶

请求与响应¶

• 请求方法：遵循 RESTful 风格，使用 GET（查询）、POST（创建）。
• 请求头：除认证头外，通常需指定 Content-Type: application/json（POST 请求）。具体接口如有特殊要求，会在文档中说明。
• 响应格式：统一为 JSON 格式，包含 success、message、data（成功时）或 errors（失败时）字段。
• 字符编码：UTF-8。

标识符格式¶

系统使用以下标识符来唯一标识资源，它们均由字母、数字、下划线（_）和短横线（-）组成，长度不超过 255 个字符：

状态说明¶

任务整体状态¶

收件人发送状态¶

错误处理¶

通用错误响应格式¶

{
  "success": false,
  "message": "错误描述信息",
  "errors": {
    // 可选的详细错误信息
  }
}

常见 HTTP 状态码¶

频率限制与重试¶

• 查询频率：为避免给系统带来不必要的压力，建议主动查询接口的调用间隔不少于 30 秒，发送中的任务可适当延长至 1 分钟。
• 重试策略：对于网络超时、服务器临时错误（5xx），建议客户端实现指数退避重试。系统侧对 Webhook 通知有内置重试机制（最多 5 次，间隔递增），详见 Webhook 回调通知。

基础工作流程¶

典型的传真发送流程分为以下几步：

1. 上传文件 → 通过 上传文档接口 上传待发送的文件，获得 file_ref
2. 创建传真任务 → 使用 file_ref 和收件人传真号码，调用 发送传真接口，获得 task_ref 和 rcpt_ref
3. 监控发送状态 → 可选择以下一种或两种方式：
4. 主动查询：使用 查询任务状态接口 或 查询收件人状态接口 获取实时状态
5. 被动接收：配置 Webhook 回调通知，系统在任务完成或失败时主动推送通知
6. 账户管理 → 随时通过 账户状态查询接口 查看余额、账户状态等信息

接口概览¶

通用响应格式¶

所有接口均遵循统一的 JSON 响应结构：

成功响应¶

{
  "success": true,
  "message": "操作成功描述",
  "data": {
    // 具体返回的数据
  }
}

失败响应¶

{
  "success": false,
  "message": "错误描述信息",
  "errors": {
    // 可选的详细错误信息
  }
}

常见的失败原因包括：

• 401：认证失败（缺少凭证、凭证无效、无 API 访问权限）
• 400：请求参数验证失败（格式、范围、必填项等）
• 404：资源不存在（任务、收件人标识符无效）
• 500：服务器内部错误。

详细的错误处理说明请参考各接口文档的“错误处理”章节。

状态说明¶

任务整体状态¶

收件人发送状态¶

最佳实践与建议¶

1. 认证与安全¶

• 保护 API Secret：切勿将 Secret 硬编码在客户端代码或公开仓库中
• 使用环境变量：将 API Key 和 Secret 存储在环境变量或安全的配置管理中
• 定期更换秘钥：建议每 3-6 个月更换一次 API Secret

2. 文件处理¶

• 格式优先：优先使用 PDF 格式，兼容性最佳
• 控制大小：单个文件建议控制在 2MB 以内，最大不超过 10MB
• 提前上传：在创建传真任务前完成文件上传，确保 file_ref 有效

3. 发送策略¶

• 合理分批：收件人超过 100 个时，拆分为多个任务
• 预约发送：利用 scheduled_at 参数避开业务高峰时段
• 记录标识符：务必保存返回的 task_ref 和 rcpt_ref，用于后续查询

4. 状态监控¶

• 推荐使用 Webhook：避免频繁轮询，减少 API 调用压力，实现实时通知
• 查询频率限制：如主动查询，建议间隔不少于 30 秒，发送中任务可适当延长至 1 分钟
• 处理失败重试：对于失败收件人，可根据 failed_code 决定是否重试（如 BUSY、NO_ANSWER 等可稍后重试）

5. 错误与重试¶

• 实现重试逻辑：对于网络超时、临时性服务器错误（5xx），可加入指数退避重试
• 日志记录：记录所有 API 请求和响应，便于故障排查与对账
• 监控余额：定期查询账户余额，避免因余额不足导致发送失败

技术支持与资源¶

• 适用版本：GlobFax API V2 及以上版本
• 官方文档：本知识库包含详细的使用指南、API 参考和常见问题
• 管理后台：登录 管理后台 进行账户设置、查看发送记录和配置 Webhook
• 错误代码：详细的传真失败原因和错误代码，请参阅 错误代码参考
• 联系我们：如遇技术问题或需要商务支持，请通过官网联系我们的技术支持团队

下一步¶

• 如果您是首次使用，建议从 用户认证 开始，获取 API 凭证
• 准备发送传真？请先阅读 上传文档接口 和 发送传真接口
• 希望实时接收发送结果？立即配置 Webhook回调通知