Skip to main content
Home
  • 传真技术
  • 传真API集成基础

传真API集成基础概念

#一、核心模型：传真任务是异步任务

传真和普通HTTP上传下载最大区别：提交API ≠ 发送完成。 HTTP请求只是把传真任务提交到平台任务队列；后续拨号、协商、传输、失败重试，全部在平台后台异步执行。

  • 提交接口返回：task_id（任务唯一标识）
  • 开发者依靠两种方式获取最终结果：轮询查询接口 / Webhook回调推送

业务红线：不要在同步HTTP请求里等待传真发送完成，传真呼叫可能持续几十秒甚至数分钟，极易超时。

#二、传真任务完整生命周期

  1. 提交（Submitted） 开发者上传源文件（PDF/TIFF）、传入被叫E.164号码、指定主叫DID、参数（分辨率、ECM开关、重试策略），平台校验文件、号码格式、权限、配额，校验通过生成task_id，入队。 校验失败直接返回错误：文件损坏、格式不支持、号码非法、余额不足、限流。

  2. 排队（Queued） 任务进入调度队列，按路由策略匹配中继、DID；批量任务会做流量削峰，避免短时间大量呼叫触发运营商风控。 平台会维护退避策略：前面失败的号码，重试会延迟，不立即重拨。

  3. 呼叫中（Calling / In Progress） 中继发起呼叫，进入T.30呼叫流程：振铃、协商、图像传输。 这个阶段会产生中间状态：接通、协商中、传输中。

  4. 最终终态（二选一）

    • 成功（Success）：T.30会话正常结束，页面全部传输完成，生成回执元数据+回执TIFF/PDF；
    • 失败（Failed）：呼叫中断，绑定失败码（20/21/34/45等）、失败原因文本，按配置决定是否自动重试。

  5. 重试结束（Retries exhausted） 达到最大重试次数，任务永久关闭，不再自动发起呼叫。

状态流转不可逆：只有进入终态后，才代表本次任务闭环。

#三、API核心入参对象（概念层）

#1. 被叫号码 to

强制使用 E.164格式。多个被叫就是批量任务；平台底层会拆成独立呼叫，每个被叫是独立T.30会话，一个失败不影响其他被叫。

重点：批量传真≠同一通呼叫发给多人；是多通独立呼叫。

#2. 主叫DID caller_id

指定呼出使用的DID号码，决定被叫侧看到的Caller ID、路由线路、拦截概率。

  • 不传：平台自动路由，优先匹配被叫国家本地DID；
  • 传入：强制使用指定DID；该DID必须在客户账号下已开通、允许外发；
  • 合规约束：不能传入未归属你的号码，禁止伪造Caller ID。

#3. 文档源文件

支持两种提交方式：

  • 文件上传：multipart/form-data 上传PDF/TIFF；
  • 远程URL：平台拉取公网可访问文件（很多平台有安全限制，不支持内网URL）。

底层限制：平台会把PDF渲染为G3 TIFF位图，再送入T.38网关；渲染阶段就会固定分辨率、纸张尺寸。 支持格式：PDF、单页/多页TIFF；Word、Excel一般不直接支持，需要业务侧预先转PDF。

#4. 传真协商参数（映射到T.30 B阶段协商）

  • resolution：标准 / Fine / Super Fine（对应之前文档的分辨率）
  • ecm_enabled：布尔值，开启/关闭ECM纠错
  • max_rate：最高调制速率 V.29 / V.34
  • page_size：A4 / Letter（外贸美国客户默认Letter）

这些参数最终下发给T.30协商；远端设备不支持时，协商失败，任务返回失败码。

#5. 重试策略 retry

  • max_retries：最大重试次数
  • retry_interval：重试间隔（秒）
  • 支持按失败类型过滤：比如只对忙线（21）、无应答（20）重试，协议错误（34）、呼叫拒绝（31）不重试

#6. 自定义元数据 metadata

key-value自定义字段，透传给回调、回执记录；用于业务侧关联：订单ID、客户ID、工单编号。

推荐用法：业务系统ID放到metadata，收到回调时直接关联本地业务记录，不用自己维护task_id映射表。

#四、两种结果获取方式：轮询 vs Webhook

#方式A：轮询（Polling）

调用查询接口，传入task_id读取状态。 适用场景：低并发、简单后台、无法暴露公网接收回调的内网系统。 缺点：高频轮询会增加API调用量，容易触发限流；状态更新存在延迟。

#方式B：Webhook 回调（推荐生产集成）

任务到达终态（成功/失败），平台主动POST事件JSON到你配置的公网回调地址。

  • 事件包含：task_id、状态、失败码、回执文件URL、metadata、时间戳；
  • 安全机制：签名校验（Header携带签名，你用平台密钥校验，防止伪造回调）；
  • 重试机制：你的服务返回非200，平台会隔一段时间重试推送回调；

注意：Webhook只推送终态，不会推送中间状态（呼叫中、协商中）。

#五、接收传真（入站传真，Inbound Fax）

DID号码收到外部发来的传真，属于入站事件，也是通过Webhook推送：

  • 事件类型：inbound_fax
  • 携带：主叫号码、接收DID、页面文件、接收时间 业务侧常见场景：自动归档到ERP、OCR识别、转邮件通知、入库工单。

入站是被动事件，不需要你主动发起呼叫；一个DID可以绑定多个回调地址，或者按号码路由到不同业务。

#六、回执（Fax Receipt）概念

无论成功失败，任务都会生成回执记录。

  • 成功回执：包含远端传真机返回的T.30状态信息、传输时长、协商参数、TIFF回执图像（远端收到的位图）；
  • 失败回执：失败码、失败描述、重试历史； 回执文件是审计、合规举证的材料，受监管场景（HIPAA/GDPR）需要留存。

重要边界：回执只能证明T.30会话正常完成，不代表对方经办人已经阅读、确认内容。和纸质签收不是一回事。

#七、平台侧限流、配额与风控（集成高频踩坑）

  1. 并发上限：同一账号同时并发呼叫数量上限；超过上限任务进入排队，不会直接报错；
  2. 速率限制（RPS）：API提交接口每秒请求上限；短时间批量提交被限流返回429；
  3. 号码风控：平台内置退避、黑名单；短时间高频呼叫同一个被叫号码，会触发风控拦截，防止被运营商判定垃圾传真；
  4. 账户配额：按页计费、余额校验；余额不足时任务直接拒绝提交。

业务建议：批量事务传真做分片、错开并发；营销传真必须叠加许可校验，不能只靠API限流。

#八、文件格式关键区分

  • PDF：业务提交源文件，矢量；平台内部渲染转G3 TIFF；
  • TIFF（G3）：传真原生传输格式，位图，T.30/T.38网关只识别G3 TIFF；

误区：提交TIFF不等于绕过协商；依然要走T.30能力协商。

#九、常见集成误区

  1. ❌ 提交API返回成功 = 传真已经发到对方 更正：只是入队，后面依然会协商失败、线路中断。
  2. ❌ Webhook收到成功回执，对方一定看到传真 更正：对方传真机接通接收成功，但可能无人查看、打印后丢弃；回执只代表传输链路层面完成。
  3. ❌ 可以用回调接收中间状态（呼叫中） 更正：绝大多数云传真平台Webhook只推送终态；中间状态只能轮询。
  4. ❌ 批量传入100个号码就是一通呼叫 更正：100个独立呼叫，独立生命周期、独立失败、独立回执。
  5. ❌ 回调是可靠推送，不会丢 更正：你的服务宕机、防火墙拦截都会导致回调丢失；生产方案建议：Webhook为主，辅以定时轮询对账兜底。

#十、业务集成选型参考

业务场景 推荐方案
订单、对账、理赔自动事务传真 Webhook + 自定义metadata，DID按目标国家路由
内网系统、无公网回调地址 轮询模式，控制轮询间隔
入站传真自动归档、OCR DID绑定入站Webhook，自动拉取文件入库
批量导出、报表对账 任务列表查询API，分页拉取历史记录
营销传真 前置许可校验、退订名单校验、控制并发，单独DID隔离