期初与期末余额对账

除了单笔 Money Movement 之外，客户通常还需要对账某个 Cobre Balance 某一天的期初余额、期末余额以及每日贷记/扣记总额——无论具体是哪个产品或通道生成了每笔交易。

本指南介绍两种实现方式：通过获取账户交易记录自行计算这些数值，或通过获取账户每日余额历史读取已经预先计算好的结果。

两种实现方式

方式	端点	适用场景
从交易中计算	`GET /accounts/{acct_id}/transactions`	当天/日内数据，或需要交易级别细节时
读取预先计算的结果	`GET /accounts/{acct_id}/daily_balance_history`	日终对账，且当天的历史数据已生成

每日余额历史对象每天生成一次，并在当天结束后至少 5 小时才可用。如果您需要今天仍在变动中的实时余额，请改为从交易中计算。

从交易中计算余额

获取账户交易记录会返回某个账户的每一笔交易，包含其 previous_balance、current_balance、amount、credit_debit_type 和 transaction_date。要计算某一天的数值：

查询该账户筛选到目标日期的交易（使用 date 精确指定某一天，或使用 date_gte/date_lte 指定一个范围）。

按 transaction_date 升序对结果排序。

期初余额是第一笔交易的 previous_balance。

期末余额是最后一笔交易的 current_balance。

贷记总额是所有 credit_debit_type = credit 的交易的 amount 之和；扣记总额是所有 credit_debit_type = debit 的交易的 amount 之和。

在计算期初/期末余额之前，请翻阅所有分页结果 —— 如果某一天的活动超过单页容量，否则您得到的第一笔或最后一笔交易将是错误的。

示例请求：

GET /accounts/acc_hyb36Rp7XS/transactions?date=2025-06-06

示例响应：

{
  "total_items": 3,
  "total_pages": 1,
  "is_last_page": true,
  "page_items": 3,
  "contents": [
    {
      "id": "trx_a1B2c3D4e5F6",
      "type": "col_credit",
      "account_id": "acc_hyb36Rp7XS",
      "amount": 50000,
      "previous_balance": 100000,
      "current_balance": 150000,
      "currency": "COP",
      "credit_debit_type": "credit",
      "transaction_date": "2025-06-06T09:15:00Z",
      "created_at": "2025-06-06T09:15:01Z",
      "metadata": {
        "money_movement_id": "mm_g7H8i9J0k1L2",
        "description": "Sent from Cobre"
      }
    },
    {
      "id": "trx_b2C3d4E5f6G7",
      "type": "col_debit",
      "account_id": "acc_hyb36Rp7XS",
      "amount": -20000,
      "previous_balance": 150000,
      "current_balance": 130000,
      "currency": "COP",
      "credit_debit_type": "debit",
      "transaction_date": "2025-06-06T14:30:00Z",
      "created_at": "2025-06-06T14:30:01Z",
      "metadata": {
        "money_movement_id": "mm_m3N4o5P6q7R8",
        "description": "Sent from Cobre"
      }
    },
    {
      "id": "trx_c3D4e5F6g7H8",
      "type": "col_cb_credit",
      "account_id": "acc_hyb36Rp7XS",
      "amount": 150000,
      "previous_balance": 130000,
      "current_balance": 280000,
      "currency": "COP",
      "credit_debit_type": "credit",
      "transaction_date": "2025-06-06T18:45:00Z",
      "created_at": "2025-06-06T18:45:01Z",
      "metadata": {
        "money_movement_id": "mm_s9T0u1V2w3X4",
        "description": "Sent from Cobre"
      }
    }
  ]
}

根据此响应：期初余额 = 100000（第一笔交易的 previous_balance），期末余额 = 280000（最后一笔交易的 current_balance），贷记总额 = 50000 + 150000 = 200000，扣记总额 = 20000。

期末余额 = 期初余额 + 贷记总额 - 扣记总额 —— 在本例中，100000 + 200000 - 20000 = 280000。

改用每日余额历史

获取账户每日余额历史已经完成了上述计算，并按每个账户每天返回一个对象：

每日余额历史字段	交易中的等价来源
`initial_balance`	当天第一笔交易的 `previous_balance`
`end_balance`	当天最后一笔交易的 `current_balance`
`total_credits`	`credit_debit_type = credit` 的 `amount` 之和
`total_debits`	`credit_debit_type = debit` 的 `amount` 之和
`balance_date`	这些数值所属的日期（`YYYY-MM-DD`）
`offset`	用于确定日期边界的 UTC 偏移量

offset 与获取账户交易记录中用于将 transaction_date 归入某个日历日的 UTC 偏移量相同。每日余额历史与交易记录采用相同的日期边界，因此针对同一天，从交易记录手工计算出的数值始终与该天的每日余额历史对象保持一致。

示例请求：

GET /accounts/acc_pW9hRz2Qxv/daily_balance_history?balance_date=2026-08-19

示例响应：

{
    "total_items": 1,
    "total_pages": 1,
    "is_last_page": true,
    "page_items": 1,
    "contents": [
        {
            "id": "dbh_MpW6uPF9YMAR",
            "offset": "-05:00",
            "balance_date": "2026-08-19",
            "initial_balance": 295500,
            "total_credits": 150000000,
            "total_debits": 0,
            "end_balance": 150295500,
            "created_at": "2026-08-20T08:03:03Z",
            "updated_at": "2026-08-20T08:03:03Z"
        }
    ]
}

这是一个独立的真实示例 —— 账户和日期都与上面的交易示例不同 —— 但同样的公式依然成立：295500 + 150000000 - 0 = 150295500。请注意 initial_balance、total_credits、total_debits 和 end_balance 均为数字类型（而非字符串）。请直接使用此端点，而不是从交易记录中重新计算这些总额；仅在需要交易级别细节或当天数据时才回退使用交易记录。

余额对账允许的操作

🔍 查询 — 交易

🔍 查询 — 每日余额历史

说明： 获取某个账户的每一笔交易，包括 previous_balance 和 current_balance，以便自行计算期初/期末余额。

执行该操作后的预期结果： 返回一份分页的交易列表，可按日期、credit_debit_type、类型和金额进行筛选。

📘 了解更多：

🔗 获取账户交易记录

如何开始

确定是进行当天对账还是日终对账

当天或日内数据请使用交易记录；一旦当天的每日余额历史对象已生成（当天结束后至少 5 小时），则可使用每日余额历史。

将查询限定在目标日期

在交易记录上使用 date / date_gte / date_lte，或在每日余额历史上使用 balance_date / balance_date_gte / balance_date_lte。

在从交易记录计算总额之前，请翻阅所有分页结果

活动量较大的某一天可能跨越多个分页 —— 不要基于不完整的结果集来计算期初/期末余额。

使用此 API 后的预期结果

期初和期末余额可通过两种方式相互验证

从交易记录手工计算得到的数值，与该天预先计算好的每日余额历史对象一致。

每日总额可与您自己的账本进行对账

每天的 total_credits 和 total_debits 为您提供了一个独立于单笔 Money Movement 对账的核对点。

差异可精确定位到某一天和某个账户

任何不匹配之处都会被缩小到某个 account_id 和 balance_date，您可以在交易层面进行排查。

期初与期末余额对账

两种实现方式#

从交易中计算余额#

改用每日余额历史#

余额对账允许的操作#

如何开始#

使用此 API 后的预期结果#

两种实现方式

从交易中计算余额

改用每日余额历史

余额对账允许的操作

如何开始

使用此 API 后的预期结果