单据隔离/取消隔离

• 接口：/common/document/isolation
• Method：POST
• 数据格式：application/json，请求和响应字段使用 camelCase。
• 接口说明：根据云简单据号，批量隔离或取消隔离当前企业内的单据，同步返回逐单处理结果。

Base URL 与鉴权

其他云环境域名见附录一 环境接口。请使用所属企业、对应环境的域名，接口可用性以该环境实际发布情况为准。

沿用企业级标准接口访问令牌，获取方式见获取 TOKEN。调用时将 access_token 放在请求 Query 参数中。企业范围由令牌确定，不接收请求方指定的企业 ID、用户 ID、员工号或用户名，也不要求传入员工身份。

资源说明与接口列表

本接口设置单据的隔离标识：Y 表示隔离，N 表示取消隔离；不会变更审批状态、支付状态或单据关联关系。

本接口为同步接口，不创建异步任务，不返回任务编号或任务进度，也不提供隔离状态查询。

请求参数

Query 参数

请求体

参数约束

• 一个请求只能使用一种动作，不支持逐单传入动作，也不允许混合隔离与取消隔离。需要不同动作时请分开请求。
• 请求体外层仅允许 bizId、timestamp、data；data 仅允许 documentNumbers、isolated。多余字段会导致整次请求被拒绝。
• 先校验原始数组长度和全部单号，再按首次出现的顺序去重。即使重复单号去重后不超过 100 个，原始数组超过 100 项仍会被拒绝。
• 单号只匹配令牌所属企业内的云简单据号，不按外部系统单号 external_id 回退查找。已删除单据视为不存在。
• 不自动去除单号首尾空白，也不转换大小写；请传入准确单号。数字、布尔值或对象不会自动转换成单号字符串。
• 请求参数或字段类型错误时，整次请求不执行单据修改。

业务规则与处理边界

隔离与取消隔离

下表中的“主单”指本次按输入单号定位的单据；“普通单据”指非支付单。

直接后续支付单须与主单属于同一企业、未删除，且支付单的单头关联直接指向主单；不递归联动更后续的单据。直接操作支付单时，不反向修改其前序单据。

主单已经是目标隔离值时，仍会检查其直接后续支付单及相应业务规则；不是无条件直接成功。全部规则通过后，同值行不重复更新，本次仍计为成功。

同企业内单号不存在时，该单号失败；若对应多条未删除记录，该单号失败，不会任取一条处理。

事务与计数

• 去重后的单号按输入顺序逐个处理，每个输入单号使用独立事务。
• 一张主单及其隐式联动的直接后续支付单在同一事务中处理；校验失败时不提交本组修改。不同输入单号不共用事务，后续单号失败不会撤销之前已成功的单号。
• 成功数和失败数只统计去重后的显式输入单号，隐式联动支付单不额外计数。如果某支付单也作为显式输入出现，它仍会被单独处理、计数。
• 正常返回完整结果时，successCount + failureCount 等于去重后的输入单号数；失败明细按去重输入顺序返回。
• 成功数包含已提交成功和同值校验通过的单号。失败数也可能包含“处理结果待确认”的单号，不能仅根据失败数推断数据库一定未修改，需结合 reason 判断。
• 100 项限制只针对显式输入单号，不限制实际联动支付单的总数量，也不代表固定的接口处理耗时。

返回参数

全部成功、部分成功、全部单据业务失败，都可能返回 resCode=200000、resMsg=success。这表示已返回完整逐单结果，调用方必须继续检查 failureCount 和 failures，不能只判断 resCode 或 HTTP 状态。

示例

以下单号和结果仅用于说明报文结构，实际结果取决于企业内单据状态及关联关系。

隔离请求与全部成功

{
  "bizId": "isolation-sync-20261113-0001",
  "timestamp": 1794528000000,
  "data": {
    "documentNumbers": ["EXP0000338528", "PAY0000123456", "EXP0000338528"],
    "isolated": "Y"
  }
}

原始数组为 3 项，去重后为 2 个单号，全部通过时返回：

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "isolation-sync-20261113-0001",
  "data": {
    "successCount": 2,
    "failureCount": 0,
    "failures": []
  }
}

取消隔离请求

{
  "bizId": "isolation-sync-20261113-0002",
  "timestamp": 1794528000000,
  "data": {
    "documentNumbers": ["EXP0000338528", "PAY0000123456"],
    "isolated": "N"
  }
}

返回结构与隔离一致。

部分成功

例如第一个单号及其联动单据通过校验，第二个支付单未完成支付：

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "isolation-sync-20261113-0001",
  "data": {
    "successCount": 1,
    "failureCount": 1,
    "failures": [
      {
        "documentNumber": "PAY0000123456",
        "reason": "支付单尚未完成支付"
      }
    ]
  }
}

全部单据业务失败

例如第一个单号不存在，第二个支付单未完成支付；仍返回完整逐单结果：

{
  "resCode": 200000,
  "resMsg": "success",
  "bizId": "isolation-sync-20261113-0001",
  "data": {
    "successCount": 0,
    "failureCount": 2,
    "failures": [
      {
        "documentNumber": "EXP0000338528",
        "reason": "单据号不存在"
      },
      {
        "documentNumber": "PAY0000123456",
        "reason": "支付单尚未完成支付"
      }
    ]
  }
}

参数错误

例如 isolated 传入小写 y，整次请求不执行：

{
  "resCode": 500001,
  "resMsg": "isolated 必须为 Y 或 N，整批只能使用一种操作",
  "bizId": "isolation-sync-20261113-0001"
}

JSON 或字段类型错误

例如 documentNumbers 中传入数字而不是字符串，整次请求不执行；此时可能无法取得 bizId：

{
  "resCode": 500060,
  "resMsg": "请求 JSON 格式或字段类型不正确"
}

调用异常或结果不确定

此类请求级错误不返回可靠的逐单结果，不以 0 成功或全失败代替未知结果：

{
  "resCode": 500000,
  "resMsg": "单据隔离调用异常，可能部分已处理，请核对单据状态后重试",
  "bizId": "isolation-sync-20261113-0001"
}

cURL 调用示例

将域名替换为所属环境，并将 <ACCESS_TOKEN> 替换为有效企业令牌：

curl --request POST \
  'https://topenapi.cloudpense.com/common/document/isolation?access_token=<ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "bizId": "isolation-sync-20261113-0001",
    "timestamp": 1794528000000,
    "data": {
      "documentNumbers": ["EXP0000338528", "PAY0000123456"],
      "isolated": "Y"
    }
  }'

错误与失败原因

请求级响应码

常见参数校验信息：

本接口业务响应沿用标准响应体，业务校验错误不等同于 HTTP 4xx。令牌失效、网关鉴权及其他公共错误沿用平台约定，见附录二 异常代码。

单据级失败原因

以下信息出现在 data.failures[].reason 中，不代表整个请求失败：

幂等与重试建议

• bizId 仅用于追踪和回显，相同 bizId 再次提交仍会处理，不提供基于 bizId 的持久化请求去重。
• 同值请求会重新检查主单与联动规则；规则通过后不重复更新同值行，但业务状态或关联变化仍可能导致失败。
• 网络中断、超时或 500000 不代表全部未执行，服务端可能仍在处理。不要盲目自动整批重放，建议关闭写请求的自动重试。
• 先核对单据实际结果，只对仍需处理的单号重试；每次重试仍须保持整批动作统一。对于明确的参数错误，应先修正报文。
• 本接口不保证相反动作 Y/N 并发请求的最终覆盖顺序，调用方应避免对同一单据并发提交相反动作。