
如果你的应用已经通过其他服务商收发传真,那么迁移到 Fax.Plus 的第一步,是弄清楚目前这套连接是如何工作的。传真 API 是你的软件用来提交文档、获取已接收传真并查看结果的连接。更换它时,你需要确保这些日常任务仍能按预期运行。我们将一步步带你完成迁移,从账户访问和文档处理,到测试和传真号码转移。我们还会解释切换(cutover):即你的应用开始使用新服务商处理真实业务的那个时间点。我们的目标是让开发人员和运营团队拥有一份共同的计划,并能在正式切换前进行测试。
先列出一份简短的清单,供开发人员和负责日常传真工作的人员一起审阅。清单应包括发出的传真、接收号码、文档存储、送达状态更新,以及使用这些文档或更新的所有业务软件。在下面的步骤中,“作业”(job)仅指你的应用需要跟踪的一项传真任务。
针对每个工作流程,记录触发它的条件、文档的来源、接收人,以及送达失败时会发生什么。找出定时作业、手动重发,以及已有人提交但你的应用尚未标记为完成的文档。
将工作分为三类:
规划如何导出并存储历史记录,并将其与号码转移分开处理。例如,你的团队可能需要查找迁移前几个月发送的某份传真的确认报告。请决定该报告存放在哪里、谁可以访问,以及贵组织需要将其保留多长时间。
接下来,约定“可以切换”的标准是什么。这些就是你的验收标准(acceptance criteria):在开始将新集成用于真实业务之前必须通过的检查。例如,文档必须清晰可读,接收的传真必须送达正确的团队,送达结果必须显示在对应的应用记录旁边。请选择能够反映你自己的文档和目的地的检查项。
我们的 API 可在 Enterprise 套餐中使用,详见 Fax.Plus API 快速入门。在规划正式切换之前,请确认你的工作流程所需的账户、已分配的号码和功能。具备号码转移资格并不等同于具备使用 API 的资格。
身份验证是 API 用来检查你的应用可以访问哪个账户的方式。我们的身份验证指南介绍了个人访问令牌和 OAuth 2.0。个人访问令牌是你的应用用来验证请求的密钥。OAuth 2.0 则允许用户通过登录和授权同意流程来授予访问权限。你的开发人员应选择适合该工作流程的方式,并遵循其设置要求。
将用于真实业务的凭据与测试环境的凭据分开保存,并将密钥存放在服务器端,而不是浏览器代码中。将权限限制在应用所需的操作范围内。测试期间,请有意停用某个测试凭据,并检查你的应用是否能清晰地报告该问题。连接问题应当让你的团队有可排查的线索,而不是触发重复发送。
对于受监管的工作流程,在使用真实文档之前,请先确认贵组织的安全和合同要求。仅有技术连接并不能证明整个工作流程符合这些要求,尤其是在由其他应用处理这些文档的情况下。
写下当前集成中的信息与新集成中的信息如何对应。这有时称为字段映射(field map)。它应涵盖目标号码、文档引用、传真 ID 和结果等详细信息。保持你应用自身的作业 ID 不变,并将新旧服务商的 ID 一并保存在其旁边。
例如,你系统中名为 PO-1042 的订单在迁移后仍应保持为 PO-1042。它的传真在新服务商处可能有不同的跟踪 ID,但你的团队仍应能够一并找到该订单、文档及其结果。
使用 Fax.Plus 时,你需要先上传文件。API 会返回一个路径,即你的应用在发送请求中所包含的引用。当你将 设置为 时,发送端点(即接受该请求的 API 地址)可以返回已安排传真的 ID。请保存这些 ID,以便跟踪后续进展。
在你的应用中区分显示“已提交”、“处理中”和最终送达结果。发件箱指南介绍了文档转换和发送等各个阶段。API 请求成功只说明该请求已被接受;你的应用仍需跟踪这份传真,直至得到最终结果。
请确定在传真仅部分发送成功、发送失败或结果需要人工处理时,团队应看到什么信息。一条有用的消息应说明已知情况以及接下来需要检查的内容,以便操作人员判断是应检查文档、核实目的地,还是授权再次尝试。
请使用包含虚构信息的示例文件测试文档的呈现效果,包括多页 PDF、扫描页面、小字号文本,以及你的工作流程所使用的任何封面页版式。请求在技术上成功,并不代表生成的文档便于收件人阅读。
webhook 是在事件发生时(例如传真完成传输)自动发送给你的应用的消息。它可以帮助你的应用更新记录,而无需反复查询是否有变化。对于新的集成,请参阅我们最新的webhook 文档,并使用 。
事件名称 表示出站会话已结束,包括未成功的尝试。在将记录标记为“已送达”之前,请先读取其状态。请检查 webhook 的签名(用于验证消息的加密校验),并及时确认有效消息。将较耗时的工作(例如更新其他系统)安排在后台运行,以便你的接收端能够快速响应。
同一个 webhook 可能会多次到达。其 标头(随消息一同发送的值)用于标识该次投递,并且在该消息重新发送时保持不变。请记录你已处理过的 ID,这样再次收到同一消息时就不会重复执行业务操作。这称为去重。
例如,两次收到相同的送达更新,不应将同一个附件两次添加到订单中。请将此项与防止重复发送传真分开测试:检查重复的更新,并不能告诉你对于结果不确定的发送请求是否应该再次提交。
请从不含客户信息或敏感信息的文档开始,并且仅发送到团队可控的约定测试号码。测试前请确认设置及任何费用。如果你之前使用过沙盒(一种可在不影响正常生产活动的情况下进行测试的隔离环境),请确认此处提供何种测试方案,而不要假定其工作方式相同。
| 测试 | 上线前需要验证的内容 |
|---|---|
| 账户访问 | 应用能够完成其预期的工作。无效或已停用的凭据会产生明确的错误。 |
| 文档准备 | 典型文件在接收时依然清晰可读、内容完整,且顺序符合预期。 |
| 发送成功 | 文档成功送达,其最终结果与对应的业务记录保存在一起。 |
| 失败与部分送达 | 应用保留足够的信息以供审查,并且不会过早地将作业标记为已送达。 |
| 重复的 webhook | 两次收到相同的更新,不会产生重复的附件或通知。 |
| 更新中断 | 如果你的应用暂时无法接收更新,团队可以查看传真记录并恢复处理,而无需猜测是否应该重新发送。 |
| 接收传真 | 发送到每个测试号码的传真都能到达应用中的正确位置和正确的团队。 |
| 再次尝试发送 | 团队清楚哪些重试由服务商处理,哪些需要由应用或操作人员来决定。 |
| 留存的证据 | 团队可以从原始业务作业中调取传真记录和所需的报告。 |
| 切换演练 | 团队能够识别未完成的工作,在需要时暂停新的提交,并遵循恢复计划。 |
请为每次测试保留一份结果记录,包括文档类型、可控的目的地、预期行为、实际观察到的行为以及未解决的问题。在扩大上线范围之前,先修复未通过的验收检查项。
如果你的工作流程需要确认文档,Fax.Plus 提供PDF 确认报告端点。请验证你的应用获取的报告及其存储方式。传输结果并不能证明有人审阅或接受了该文档。
号码转移是将你现有的号码从一个服务商转到另一个服务商,使他人可以继续使用该号码联系你。如果你希望保留现有号码,请先确认这些号码是否可以转移。请遵循最新的 Fax.Plus 号码转移流程,包括所需的账户详情和授权文件。
在 Fax.Plus 确认转移完成之前,请保持当前线路处于启用状态。提前取消可能会导致转移失败,并使该号码面临丢失的风险。
号码转移流程会说明如何使用临时号码,让你在转移尚未完成时就开始收发传真。请在转移前用它测试你的接收工作流程。请确认哪个号码将被替换,尤其是账户下有多个号码时。转移完成后,再检查传入的传真是否重新送达正确的位置。
请将应用变更与号码转移一并规划,但分开跟踪。API 集成能正常工作,并不意味着号码已经转移完成。同样,号码转移完成也不能证明你的应用接收端和路由规则是正确的。
在确定切换日期之前,请先确认号码转移的安排,并约定某项检查未通过时的应对方案。开发者有时把回到之前的设置称为回滚。但是,把应用设置改回去,并不会自动把已转移的号码移回原服务商。请将软件和号码的恢复方案分开规划。
当你开始通过 Fax.Plus 处理生产环境的工作时,请明确区分提交给旧服务商的作业和提交给新服务商的作业。不要仅仅为了对比结果,就把同一份生产文档同时通过两个服务商发送。
切换时,请列出未完成的发送、已排程的作业、尚未解决的失败,以及仍需处理的传入文档。将这份清单与两个服务商的记录进行比对。这种对账有助于你发现可能被遗漏或被重复发送的工作。如果某次发送的结果不确定,请先查看其记录,再决定是否通过另一个服务商重试。
请对照你的验收标准,检查最初的生产事务。跟踪对运营有影响的异常现象:未处理的传入文档、缺失的最终状态、无法阅读的页面、重复执行的操作,以及你的应用与服务商记录之间的差异。
检查通过后,请核对未完成的工作,保存你需要的记录,并确认所有号码转移均已完成。然后按照约定的计划关闭旧服务。停用不再使用的凭据,并移除旧的 webhook 目标地址,以免它们不必要地继续保持有效。
请从团队熟悉的一个工作流程开始。列出它需要完成的功能,约定用来证明它能正常运行的检查项,并参考Fax.Plus API 快速入门了解实施步骤。
如果你仍在评估各种方案,我们的 Fax.Plus API 页面会介绍该服务以及联系方式。沟通时请带上你的工作流程、预计用量和号码需求,这样就能根据团队的实际需要来规划迁移。
通常,你需要检查的不只是连接地址。请比较两个 API 在账户访问、文档上传、跟踪 ID、结果和自动更新方面的处理方式。这样你的开发人员就能确定并测试应用所需的变更。
不是。请把请求响应视为提交步骤。请跟踪传真直到最终结果,并在工作流程需要凭证时使用相关记录或确认报告。
请先使用虚构的文档和团队可控的测试号码。只有在确认满足必要的安全、访问、合同和运营要求之后,才使用真实文档。
切换之前,请先检查号码是否符合转移条件。在确认转移完成之前,请保持现有服务处于启用状态,并在号码转移后测试入站路由。
不一定。将业务工作流程与服务商特有的请求和事件处理分开,可以减少你需要做的变更。实际工作量取决于你现有的集成方式及其所依赖的行为。
