API 参考

概述

GlobFax API V2 是基于 RESTful 架构开发的标准化接口服务，为开发者提供完整的传真自动化能力。支持快速将传真发送、状态监控、账户管理等功能，无缝集成至自有业务系统、办公工作流及各类应用程序，实现批量、定时、智能化传真业务闭环。

核心能力

平台API具备全场景传真服务能力，核心功能如下：

多格式文件支持： 单次任务最多上传3个文件，兼容 PDF、DOC、DOCX、TXT、JPG、PNG 等主流格式
批量群发： 单任务支持最多100个收件人批量发送传真
预约发送： 支持自定义未来时间自动发送，灵活规避业务高峰
双层级状态查询： 支持任务整体、单个收件人两种粒度的状态查询
Webhook实时回调： 配置回调地址后，系统主动推送任务状态变更，无需轮询查询
账户运维管理： 支持查询账户余额、账号状态、Webhook配置等核心信息

接口认证方式

平台所有接口统一采用双请求头认证，保障接口调用安全，所有请求需在请求头携带以下参数：

X-API-Key：你的API密钥
X-API-Secret：你的API秘钥

安全警告：密钥必须严格保密，请勿将密钥泄露给第三方。建议通过环境变量、专业配置管理工具安全存储，并定期轮换秘钥。

标准调用流程

开发者集成传真功能，遵循以下标准化流程即可快速实现业务需求：

上传文件：调用上传文档接口，上传待发送文件，获取唯一文件标识 file_ref
创建任务：携带 file_ref、收件人号码等参数调用发送传真接口，获取任务标识 task_ref、收件人标识 rcpt_ref
状态监控：二选一或组合使用，主动查询（调用任务/收件人状态查询接口）、被动接收（配置Webhook回调接收实时状态推送）
账户运维：通过账户状态查询接口，实时监控账户余额、账号状态，保障业务正常运行

核心接口概览

API访问端点：

http://api.globfax.com

平台接口基于 RESTful 规范设计，请求方式统一为 GET 查询数据、POST 创建资源。除通用认证请求头外，POST 请求默认请求头为 Content-Type: application/json，特殊接口要求将在对应文档单独说明。所有接口统一返回 UTF-8 编码的 JSON 数据，基础固定字段包含 success、message；成功结果返回 data 业务参数，失败结果返回 errors 错误详情，格式统一，便于开发者快速对接解析。

接口功能	方法	路径	说明
账户状态查询	GET	/api/v2/account/status	查询账号UID、名称、余额、Webhook配置及账号状态
上传传真文件	POST	/api/v2/files/upload	支持表单、URL、二进制三种方式上传文件，返回 `file_ref`
提交传真任务	POST	/api/v2/faxes	创建传真任务，支持多文件、多收件人、预约发送
传真任务查询	GET	/api/v2/faxes/{task_ref}	查询整体任务状态及全部收件人详情
传真收件人查询	GET	/api/v2/fax/recipients/{rcpt_ref}	查询单个收件人发送结果、计费信息、失败原因

所有API请求必须携带认证请求头，无认证信息将直接拦截。生产环境推荐配置Webhook回调，实现实时、高效的状态监控。

统一响应格式

所有接口统一返回 UTF-8 编码的 JSON 数据，分为成功、失败两种格式：

成功响应


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

失败响应


{
  "success": false,
  "message": "失败描述信息",
  "errors": {
    // 可选失败详情
  }
}

资源标识符规范

系统通过唯一标识符定位所有资源，标识符支持字母、数字、下划线、短横线，长度≤255位，需开发者妥善保存：

标识符	释义	获取方式
`file_ref`	文件唯一标识	调用上传文档接口返回
`task_ref`	传真任务唯一标识	调用发送传真接口返回
`rcpt_ref`	收件人唯一标识	发送接口返回的收件人列表中获取

常见HTTP状态码

200 OK：请求成功，业务执行正常
400 Bad Request：请求参数格式、范围、类型异常
401 Unauthorized：认证失败、秘钥无效、无接口访问权限
404 Not Found：任务、文件、收件人等资源不存在
500 Internal Server Error：服务器临时异常，建议稍后重试

频率限制与重试规则

查询频率：主动查询接口调用间隔 ≥30秒，发送中任务建议间隔1分钟，避免高频轮询
客户端重试：遇到网络超时、5xx服务异常，建议实现指数退避重试机制
服务端重试：Webhook推送失败，系统内置最多5次递增间隔重试机制

技术资源与支持

适配版本：GlobFax API V2 及以上
管理后台：可登录后台配置Webhook、查看发送记录、管理账号信息
错误查询：详细失败原因与错误码可查阅错误代码参考
技术支持：遇到集成问题、业务异常，可通过官网联系技术团队协助排查