发送传真 | MultiTEL

发送前须知

请使用您有权展示的发送方号码，并确保收件人预期会收到您的传真。此请求会发起真实的传输，并可能产生费用。为尽可能可靠地识别页数，请使用准备好的 PDF 或 TIFF 文档。已加入队列的响应仅确认请求已受理，并不确认传真已送达。

请使用已启用的 MultiTEL API 账户。密码账户需发送 HTTP Basic 身份验证凭据，令牌账户需发送 Bearer 令牌。账户权限和 IP 限制仍然适用。请勿使用内部工作程序的凭据。

上传文档

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --form-string from_number=+12125550123 \
  --form-string to_number=+12125550124 \
  --form fax_file=@./document.pdf \
  https://api.multitel.net/v3/send_fax

请求字段
字段	是否必填	含义
`from_number`	是	您获准使用的发送方号码。请使用以 + 和国家代码开头的国际格式。
`to_number`	是	接收传真的号码，使用国际格式。
`fax_file`	多部分请求中必填	上传的文档。请让 curl 设置多部分请求的 Content-Type 和分隔边界。
`webhook_url`	否	可选的 HTTP 或 HTTPS 回调网址；建议使用 HTTPS。回调数据内容及送达保证仍在审查中：请轮询 fax_status，按文档所述流程查询状态。

也接受 JSON 请求，需使用 Content-Type: application/json、相同的号码字段及可选的 webhook_url，另外还需提供 file_name 和 file_b64。file_b64 包含严格按 Base64 编码的文档字节，不带 data: 前缀。有效的多部分请求 fax_file 字段优先使用。此 API 不会通过文件网址获取文件。

文档和提交限制

应用最多接受解码后大小为 15,728,640 字节（15 MiB）的文档，扩展名可为 pdf、tif、tiff、jpg、jpeg、png、doc、docx 或 txt。扩展名获准使用并不保证服务能够统计页数或转换页面。基础设施的请求大小限制可能更低，而 Base64 会增大请求体积。

对于每个账户，当前应用允许同一目标号码有一个排队中或发送中的任务；过去一小时内向该号码最多提交五次，过去一小时内所有号码合计最多提交 50 次。触发频率限制时，响应使用 API 代码 429。请等待后再重试，不要尝试绕过限制。

保留任务标识

请同时检查 HTTP 结果和 JSON 中的 status.code。JSON 中的失败结果也可能随 HTTP 200 返回。成功的 JSON 响应包含 status 和 response；示例使用虚构数据。

{
  "status": {
    "code": 200,
    "msg": "Fax queued"
  },
  "response": {
    "job_id": "0123456789abcdef0123456789abcdef"
  }
}

轮询 fax_status，使用 response.job_id 查询。如果发送请求的响应丢失，请先检查门户的发件箱再重新发送：重复请求可能发起多次独立传输。此处理程序不提供客户端幂等参数。

错误和余额检查

API 代码包括：400 表示缺少字段、回调网址无效、文档被拒绝或页数识别失败；401 表示缺少身份验证；402 表示传真预计费用加上排队中或发送中传真的预计费用后，超过账户可用余额；429 表示触发频率限制；500 表示发送准备阶段失败。请查看 status.msg 了解具体原因。

队列会在传输前记录预计费用。请勿将请求受理、余额检查或此费用估算视为已完成扣费的确认。最终计费和回调详情仍有待核实。