批量资金流动

批量资金流动允许您通过单次文件上传处理多笔资金流动，非常适合大批量出款及运营批处理场景。

批量功能常用于：

执行大规模资金拨付（例如：薪资发放、供应商付款、退款）。

通过在单次请求中发送多笔资金流动，减少 API 调用次数。

创建包含资金流动列表的 JSON 文件

第一步是创建 JSON 文件，指明需要处理的资金流动信息。

JSON 文件要求

输入 JSON 文件的关键规则：

载荷必须为 JSON 数组：以 [ 开始，以 ] 结束。

每条资金流动请求必须包含在 { } 中，并以逗号分隔。以下是示例格式：

[ 
   { 
       money_movement_request_1
   },
   {
       money_movement_request_2
   }
]

不允许使用注释（例如 // ...）。示例：

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",     //Comments are not allowed
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"MX Payment - Saldo Crobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    }
]

金额必须以最小货币单位发送（例如：100.00 MXN → 10000）。

输入文件的最大大小约为 4.7 MB。

支持的类型

批量资金流动支持两种资金流动对象类型。

使用已创建的 counterparty_id：以下是包含两条创建资金流动请求体的有效 JSON 格式，可被批量资金流动接受：

[
    {
        "amount":100,
        "source_id":"acc_8NeUKp7B5B",
        "destination_id":"cp_KqiW8WHcaD",
        "metadata":
        {
            "description":"SPEI Payment - Saldo Cobre",
            "reference":100001
        },
        "external_id":"BBM_46995"
    },
    {
        "amount":500,
        "source_id":"acc_aJmUHHWDOB",
        "destination_id":"cp_c0jhj7gn7v",
        "metadata":
        {
            "description":"ACH Payment Bancolombia",
        },
        "external_id":"BBM_32656"
    }
]

不使用已创建的 counterparty_id：该流程允许您通过在目的方中包含创建交易对手方请求体的详细信息，直接创建交易对手方。以下是包含一笔带有有效交易对手方目的地的 SPEI 资金流动的有效 JSON 格式，可被批量资金流动接受：

[
    {
        "amount": 1,
        "source_id": "acc_poyBrvkPRI",
        "destination":
        {
            "geo": "mex",
            "type": "clabe",
            "alias": "cccc",
            "metadata":
            {
                "account_number": "710969000037970288",
                "counterparty_fullname": "Company",
                "counterparty_id_type": "rfc",
                "counterparty_id_number": "ND"
            }
        },
        "metadata":
        {
            "description": "TEST PRO BMM",
            "reference": "009911"
        }
    }

]

支持的交易对手方

通过批量方式进行的出款支持以下目的地类型：

Colombia Payout Counterparties

Mexico Payout Counterparties

目的地类型	交易对手方类型	支付通道
支票账户	`cc`	Fast Pay / ACH
储蓄账户	`ch`	Fast Pay / ACH
电子存款	`dp`	Fast Pay / ACH
BreB Key	`breb_key`	BreB / Fast Pay* / ACH*
Cobre Balance	`cobre_balance`	Fast Pay

批量中的交易对手方幂等性

批量资金流动流程在创建交易对手方之前，会通过确认其是否已被创建来验证其存在性。该验证通过对以下字段进行拼接来检查幂等性：

交易对手方类型	拼接字段
`cc`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 以及 counterparty_phone
`ch`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 以及 counterparty_phone
`dp`	geo、type、account_number、beneficiary_institution、counterparty_fullname、counterparty_id_number、counterparty_id_type、counterparty_email 以及 counterparty_phone
`cobre_balance`	geo、type、cobre_tag、counterparty_email、counterparty_fullname、counterparty_id_number、counterparty_id_type 以及 counterparty_phone

授权工作流（可选）

您可以通过在请求头中将 checker_approval 标志设置为 true，将批量资金流动提交审批。

如果您选择提交批量审批，文件中的所有资金流动都将被提交审批，若未遇到验证或技术错误，资金流动将以 pending_approval 状态创建。

如需了解更多关于审批的信息，请参阅批量资金流动审批。

批量生命周期

通过批量资金流动进行的出款遵循以下简单生命周期：

1. 构建 JSON 文件
构建包含所有待处理资金流动的 JSON 文件。

2. 上传文件
上传文件以创建批量资金流动。

3. 验证流程
Cobre 验证文件并开始处理每笔资金流动，跟踪批量处理状态（例如：验证中、处理中、已完成等）。

4. 资金流动创建
通过批量方式创建的资金流动将包含 batch_id（便于对账）。

5. 接收状态更新
使用查询接口端点和/或 Webhook 跟踪进度。

即使某笔资金流动遇到功能性错误，该资金流动对象仍可被创建，错误信息将反映在其状态描述中。

批量资金流动处理流程

平台将接收并验证包含多笔资金流动的文件。
验证完成后，将更新执行时间戳和付款总数。
随后，流程将执行文件中列出的所有资金流动，并通过更新执行时间和付款总数来完成处理。

批量资金流动状态

验证中（Validating）： 批量资金流动的初始状态，反映流程开始验证文件格式的时刻。

失败（Failed）： 表示验证流程遇到错误的状态。

处理中（Processing）： 表示文件已通过验证，文件中的每笔资金流动将开始处理的状态。

待审批（Pending Approval）： 表示文件正在等待审批的状态。

已取消（Canceled）： 表示批量资金流动流程已被取消的状态。

已完成（Completed）： 表示批量资金流动流程已完成的状态。

批量资金流动仅验证上传文件的格式。如发生功能性错误，资金流动对象仍将被创建，错误信息（来自错误字典）将包含在该资金流动的描述中。

允许的文件格式

随着我们持续完善批量资金流动流程以支持更多可用格式，目前允许的格式如下：

文件格式	对象格式	最大大小
JSON	资金流动请求	4.7 Mb

批量资金流动的操作说明

🔑 Create

🔍 Retrieval

👍 Approval

描述： 创建批量资金流动。
执行操作后的预期结果： 批量资金流动已在 Cobre 中创建。
📘 了解更多：

🔗 创建批量资金流动

快速上手

在开始之前，建议您先阅读以下注意事项。

使用此 API 前的准备

Prepare your JSON file

创建一个包含所有资金流动请求的 JSON 数组。

遵循 JSON 文件格式要求。

确保每条记录使用已有的 destination_id 或内联的 destination 对象。

根据各交易对手方类型的字段拼接规则，合理利用 Counterparties 的幂等性。

Ensure the correct money movement request

请确保资金流动字段的填写准确无误：

请注意，来源与目标的组合必须构成有效的资金流动组合。

source_id 必须有效且已存在。

destination_id（如已提供）必须有效且已存在。

metadata 中的字段需根据来源与目标的资金流动组合进行相应配置。

amount 为货币的最小单位（例如，100.00 MXN 应表示为 10000）。

输入 JSON 文件的最大大小约为 4.7 MB。

建议使用 external_id 将每笔付款关联至外部对象或流程。

建议实现 checker_approval 审批逻辑。

Send your Bulk money movement for approval (optional)

使用批量资金决策接口端点，对批量操作提交审批决策结果。

详情请参阅批量资金流动审批工作流。

Implement Webhooks to track Money Movement status

为及时掌握出款交易状态，强烈建议您实现 Webhook。Webhook 可在付款发起、处理中、已完成或失败时通知您的系统。同时，请订阅所需事件，以接收交易借记和贷记的通知。

详情请参阅通知与订阅。

使用此 API 后的预期结果

Bulk process status updates

批量处理流程将经历 validating（校验中）、processing（处理中）和 completed（已完成）等状态转换。

Reconcile using batch_id

由批量操作创建的资金流动包含 batch_id，可用于关联批次与每笔出款记录。

Handle errors per Money Movement

部分资金流动可能因功能性要求未满足而失败。请使用查询接口端点和 Webhook 识别受影响的条目，并仅对其进行重试。

批量资金流动

创建包含资金流动列表的 JSON 文件#

JSON 文件要求#

支持的类型#

支持的交易对手方#

批量中的交易对手方幂等性#

授权工作流（可选）#

批量生命周期#

批量资金流动处理流程#

批量资金流动状态#

允许的文件格式#

批量资金流动的操作说明#

快速上手#

使用此 API 前的准备#

使用此 API 后的预期结果#