通过 API 查询订单时处理“执行中”状态

API 响应中的 processing 是什么意思

processing、in_progress 或其他等效状态表示服务商已接单处理，但尚未确定最终结果。对于推广服务而言，这可能是链接校验、排队等待、任务启动或逐步交付所订购的量。

Processing 既不确认成功完成，也不代表出错。此后订单可能转为 completed、partial、canceled 或 failed。只要服务商返回的是中间状态，就不要对同一链接和同一数量重复提交申请。

HTTP 200 加 processing 状态表示 API 响应成功，而不是订单成功完成。 这两类事件需要分别存储和处理。

查询订单需要哪些数据

轮询需要服务商在创建订单时返回的外部订单 ID。请将其与内部 ID、原始数量、服务参数、链接、创建时间和原始 API 响应一并保存。按渠道名称、链接或数量查找订单并不可靠：这些值可能在多个申请中重复。

如果创建后出现超时，不要自动重新提交申请。服务商可能已接收请求，而响应在传输途中丢失。请先使用文档中提供的订单查询方法（如有），或将此情况提交人工核查。

只存储当前状态的缺点在于：发生争议时无法还原订单何时转为 processing、是否有过进展以及此前收到过哪些响应。

通过 curl 查询状态的示例

确切的地址、授权方式和字段名称请以服务商文档为准。以下为模板：尖括号中的值需替换为具体 API 的数据。

单个订单的 GET 请求

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

响应示例：

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значение_времени"

}

completed_quantity 和 remains 字段仅作为结构示例。服务商可能使用 progress、start_count、balance 或其他名称。GET 方式的缺点在于：部分 API 仅接受通过 POST 查询状态。

POST 请求示例与批量查询

单个订单状态的 POST 请求

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

不要在 URL 中传递 API 密钥。请求地址会进入代理日志、分析系统、浏览器历史和技术日志。POST 的缺点在于更难通过地址栏手动检查，但这并不是把密钥放进 URL 的理由。

批量查询活跃订单

如果 API 支持批量查询，可通过一个请求发送多个 ID：

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

请按外部 ID 而非数组元素位置将响应与内部订单对应。批量查询的缺点：服务商可能不返回全部订单、限制列表长度，或仅针对单个 ID 报错。

如何为 processing 安排轮询

收到首次 processing 响应后，将下一次查询加入队列。间隔应根据 API 文档、频率限制和服务特性来选择。对于状态变化较快的任务，初期可以更频繁地查询。对于逐步推进的推广，持续的高频请求通常不会带来新信息。

一种实用的方案是在收到相同 processing 响应后逐步延长间隔。首次查询在初始延迟后进行，随后间隔增长至设定的上限。如果 API 返回进度或新的更新时间，可以从该变化开始重新计时。

• 创建订单后不要立即连续多次查询状态：服务可能需要时间将订单加入队列。
• 当 processing 反复出现时，应延长请求间隔，而不是保持固定频率。
• 为任务启动时间加入少量随机偏移，避免多个订单同时请求 API。
• 如果服务商提供 Retry-After 或类似建议，应优先采用。
• 对于有 Webhook 的订单，保留对照轮询：通知可能无法送达。

轮询过少的缺点：实际完成后界面可能仍显示旧状态。轮询过于频繁的缺点：可能触及 API 限制、收到 429 并造成额外负载。

为监控 processing 需要保存哪些时间

要区分正常执行与卡单，仅凭当前状态是不够的。对于每个活跃订单，请保存创建时间、首次收到 processing 的时间、最后一次成功 API 响应的时间、外部状态最后一次变化的时间以及进度最后一次变化的时间。

此外，建议保存原始数量、已确认完成数量、剩余量和服务商原始状态。如果 API 不返回进度，这并不代表订单已卡住：请以最后一次响应时间和服务条款中注明的预期处理周期为准。

最大等待时间不能对所有服务使用同一个数值。 请使用服务商针对具体服务注明的期限，并预留内部缓冲以应对排队和数据更新。如果未注明期限，请为每类服务制定单独规则，并根据实际处理历史进行复核。

processing 一直不变时该怎么办

长时间 processing 并不能证明出错。首先检查是否收到过成功的 API 响应、completed_quantity 或 remains 是否变化、是否有 Webhook 以及服务规则是否变更。看不到增长可能是平台统计延迟，或服务商仅在最终阶段更新进度。

当超过内部等待期限时，不要自动取消订单。请执行一次额外状态查询，如提供单独方法则请求数据，并检查通知历史。如果服务商仍确认 processing，请将订单转为内部状态“需要核查”，但保留外部状态，不要替换。

• 记录最后一次确认响应的时间和完整的 API 响应。
• 检查自上次轮询以来进度是否发生变化。
• 达到内部阈值后降低自动请求频率。
• 向支持团队提供外部 ID、链接、服务参数、状态历史和技术错误。
• 在服务商回复或出现明确最终状态之前，不要重新启动剩余部分。

手动核查的缺点：订单需要支持人员关注。但自动取消或重复下单更危险：服务商可能仍在执行。

如何区分请求故障与订单状态

网络错误、超时、HTTP 429 和 5xx 响应并不反映订单本身的状态。它们仅表示未能获取新的可靠状态。在这种情况下，请保留最后一次确认的状态，记录技术错误并安排新的查询。

遇到 429 时，如果响应头中包含 Retry-After，请予以考虑。对于临时网络错误和 5xx，请延长重试间隔。对于授权、签名或访问权限错误，不要频繁重试：需要检查密钥、令牌有效期、IP 限制和访问设置。

如果 API 返回 HTTP 200，但 JSON 无法解析或响应中缺少 order_id 和 status，请完整保存响应体并将此次查询标记为异常。不要将缺失状态替换为 completed、canceled 或 processing。

何时停止自动重复请求

轮询不应无限进行。请限制临时错误的技术重试次数，并单独控制订单处于 processing 的总时长。重试次数用尽后，请将查询任务转入人工处理队列，而不是每分钟无结果地发起新请求。

如果方法仅读取数据，重复状态请求通常是安全的。创建、取消、充值、重启和退款等方法在超时后不能机械重试。如果没有幂等键或服务商的明确确认，此类重试可能导致订单被更改两次。

限制重试的缺点：部分更新将变为人工任务。无限重试更糟：它们掩盖故障、消耗限额并使日志分析复杂化。

如何接收 processing 之后的最终状态

不要让 completed 因迟到的轮询响应或旧 Webhook 回退为 processing。每次更新时，请比较服务商的事件时间、版本序号（如有）和当前内部状态。

• new 和 pending 可转为 processing、canceled 或 failed。
• processing 可转为 completed、partial、canceled 或 failed。
• partial 不应自动视为 completed。
• completed、canceled 和 failed 通常视为最终状态，阻止自动回退。
• 未知状态或不允许的转换需要单独核查。

严格的转换表也有缺点：服务商可能新增合法的状态。因此请保存原始状态，不要用内部分类覆盖它。

如何处理 partial 和订单剩余部分

Partial 表示仅确认了原始数量的一部分。API 响应中可能包含实际完成数量、剩余量、原因和补偿数据。请将这些值分开保存：不能用已完成数量替换订单原始数量。

最终响应示例可能如下：

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значение_или_отсутствие_поля"

}

首先要确定 API 具体确认了什么：退款已完成、退款仅已计划、剩余量已取消，还是需要联系支持。如果没有退款字段，不要认为剩余量已自动补偿。

未经单独决策，不要重新启动未完成部分。服务商可能仍在结算，平台统计可能延迟更新，重复申请可能造成重复推广。等待确认的缺点：剩余部分不会立即关闭，但不会产生多余订单。

Webhook 不能替代对照查询

Webhook 允许在事件发生后立即更新订单卡片，无需等待下一次轮询。在处理程序中按外部 ID 查找订单，校验签名或密钥，保存事件 ID，并在确认转换合法后才应用。

Webhook 的重复投递必须是安全的：同一事件不能被当作新的变更。事件也可能乱序到达，因此不要仅凭迟到的 processing 将最终订单回退。

即使 Webhook 稳定，也需要对照轮询。Webhook 的缺点：配置更复杂，需要可用的处理程序、防伪造请求、去重和事件日志。

processing 和卡单时向客户显示什么

界面中无需输出完整的技​​术 JSON。对于 processing，显示“订单处理中”状态即可。如果 API 返回可靠进度，请将确认数量与原始数量分开显示，不要将其当作最终结果。

对于超过内部监控期限的订单，使用“正在核查执行情况”之类的易懂状态。在服务商响应确认之前，不要通知取消、退款或完全完成。

在接单、最终完成、partial、取消、错误和需要核查时发送通知是有用的。每次轮询后都发送消息会造成干扰，也无助于客户了解申请的真实状态。

处理日志中需要哪些记录

响应历史有助于分析卡住的 processing、丢失的 Webhook、部分执行的争议以及界面与 API 之间的差异。对于每次调用，请保存外部 ID、更新来源、请求和响应时间、HTTP 代码、原始状态、规范化状态、进度、剩余量和技术错误文本。

不要在普通日志中记录 API 密钥、令牌、签名和其他机密。限制对原始响应的访问：其中可能包含不应出现在支持界面中的数据。

上线前请测试以下场景：processing 反复出现、无进度、超时、429、5xx 错误、无效 JSON、迟到 Webhook、重复 Webhook、partial、canceled 和未知状态。测试模式有助于验证集成结构，但其缺点在于可能无法复现真实队列和生产 API 的延迟。