Skip to main content
Home
  • API 参考
  • API 概述

API 概述

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

#核心能力

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

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

#接口认证方式

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

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

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

#标准调用流程

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

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

#核心接口概览

API访问端点：

code 
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 数据，分为成功、失败两种格式：

#成功响应

json 
{
  "success": true,
  "message": "操作成功",
  "data": {
    "key": "value"
  }
}

#失败响应

json 
{
  "success": false,
  "message": "错误描述",
  "errors": "详细错误信息"
}