使用 Cobre Reports 在哥伦比亚进行对账

curl --request POST \
  --url https://api.cobre.co/v1/money_movements \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'idempotency: ' \
  --data '{
  "source_id": "acc_1232145215",
  "destination_id": "cp_5YFeIDhNkz",
  "amount": 1000,
  "external_id": "clientUser1234",
  "metadata": {
    // Will change according to the money movement type
  },
  "checker_approval": false
}'

{
  "id": "mm_0987654321",
  "batch_id": "bat_0987654321" || "chk_0987654321",
  "external_id": "clientUser1234",
  "mm_approval_id": "",
  "creator": "usr_bGcdf26rR4",
  "type": "fast_pay",
  "geo": "col",
  "status": {
    "state": "initiated",
    "code": "string",
    "description": "string"
  },
  "source_id": "acc_KJnAkypWSc",
  "source": {},
  "destination_id": "cp_5YFeIDhNkz",
  "destination": {},
  "currency": "cop",
  "amount": 100,
  "metadata": {
    // Will change according to the money movement type
  },
  "created_at": "2026-06-24T15:37:37Z",
  "updated_at": "2026-06-24T15:37:38Z",
  "checker_approval": false
}

┌─────────────────────────────────────┐
│  1. Create PayOut Money Movement    │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: INV-2025-001        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_ady1n4g4ud             │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Debit Transaction Created       │
│  • TRX ID: trx_sjrirldkmk           │
│  • Type: debit                      │
│  • Amount: -10,000 COP              │
│  • Account: Source Balance          │
│  • Instant application              │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Funds Sent Successfully         │
│  • MM Status: completed             │
│  • Destination received funds       │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  1. Create PayOut Money Movement    │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: INV-2025-002        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_xyz789def              │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Debit Transaction Created       │
│  • TRX ID: trx_abc123first          │
│  • Type: debit                      │
│  • Amount: -10,000 COP              │
│  • Account: Source Balance          │
│  • Instant application              │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Destination Rejects Payment     │
│  • MM Status: rejected              │
│  • Reason: Invalid account, etc.    │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_abc123second         │
│  • Type: credit (reversal)          │
│  • Amount: +10,000 COP              │
│  • Account: Source Balance          │
│  • Funds returned to origin         │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  1. Create Direct Link              │
│  POST /v1/money_movements           │
│  • Amount: 10,000 COP               │
│  • External ID: ORDER-2025-050      │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Direct Link Created             │
│  • MM ID: mm_payin123abc            │
│  • Payment link URL generated       │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Opens Link                │
│  • Chooses payment method           │
│  • Completes payment                │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Confirmed               │
│  • MM Status: completed             │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_credit999xyz         │
│  • Type: credit                     │
│  • Amount: +10,000 COP              │
│  • Account: Destination Balance     │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  1. Create CheckOut                 │
│  POST /v1/checkouts                 │
│  • Amount: 10,000 COP (or open)     │
│  • External ID: INV-2025-150        │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. CheckOut Created                │
│  • CheckOut ID: chk_809821845       │
│  • Payment page URL generated       │
│  • Status: pending                  │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Opens CheckOut            │
│  • Chooses payment method           │
│  • Enters amount (if open)          │
│  • Completes payment                │
│   MM ID: mm_checkout456def          │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Confirmed               │
│  • MM Status: completed             │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  5. Credit Transaction Created      │
│  • TRX ID: trx_checkout888ghi       │
│  • Type: credit                     │
│  • Amount: +10,000 COP              │
│  • Account: Destination Balance     │
└─────────────────────────────────────┘

┌─────────────────────────────────────┐
│  1. Create Direct Link/CheckOut     │
│  • Amount: 10,000 COP               │
│  • External ID: ORDER-2025-999      │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  2. Money Movement Created          │
│  • MM ID: mm_failed777ghi           │
│  • Status: processing               │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  3. Payer Attempts Payment          │
│  • Payment method fails             │
│  • Insufficient funds, etc.         │
└──────────────┬──────────────────────┘
               │
               ↓
┌─────────────────────────────────────┐
│  4. Payment Rejected                │
│  • MM Status: rejected              │
│  • NO transaction created           │
└─────────────────────────────────────┘

GET /v1/reports

{
  "id": "repo_kJs8GO03vC",
  "resource": "string",
  "start_date": "2024-09-28T00:00:00Z",
  "end_date": "2024-10-05T00:00:00Z",
  "offset": "-05:00",
  "requested_at": "2024-10-28T12:39:11Z",
  "created_at": "2024-10-28T12:39:11Z",
  "metadata": {
    "account_id": "acc_123456",
    "statement_date": "2025-05"
  },
  "file_name":"20240928_20241028_transactions_repo_kjs8go03vc.csv",
 "file_format": "csv",
 "file_layout": "transactions_csv_v1",
 "sensitive_data": false
}

Money Movement: mm_ady1n4g4ud
├─ Transaction 1: trx_sjrirldkmk (debit: -10,000 COP)
   
Money Movement: mm_xyz789def  
├─ Transaction 1: trx_abc123first (debit: -10,000 COP)
├─ Transaction 2: trx_abc123second (credit: +10,000 COP)

Cobre External ID: INV-2025-001
→ Matches Internal Invoice: INV-2025-001
→ Money Movement: mm_ady1n4g4ud
→ Net Impact: -10,000 COP

---

## Reconciliation Formulas

### Expected Balance Calculation

**Example:**

### Money Movement Transaction Count

**PayOut:**
- Completed: 1 transaction (debit)
- Rejected: 2 transactions (debit + credit reversal)

**PayIn:**
- Completed: 1 transaction (credit)
- Rejected: 0 transactions

---

## Common Reconciliation Scenarios

### Scenario 1: All PayOuts Successful

### Scenario 2: PayOut with Rejection

### Scenario 3: PayIn Completed

### Scenario 4: PayIn Pending (No Payment Yet)

---

## Troubleshooting

### Issue 1: Missing External ID in Report
**Problem:** Transaction shows null `external_id`  
**Cause:** External ID not provided in money movement creation  
**Solution:** Always include `external_id` in your API requests

### Issue 2: Balance Mismatch
**Problem:** Calculated balance doesn't match actual balance  
**Cause:** Missing transactions or unreported reversals  
**Solution:** 
1. Query full transaction history for the period
2. Check for rejected money movements (2 transactions each)
3. Verify all money movement statuses

### Issue 3: Duplicate Reconciliation
**Problem:** Same transaction reconciled twice  
**Cause:** Using non-unique `external_id`  
**Solution:** Ensure `external_id` is unique per money movement

### Issue 4: PayIn with No Transaction
**Problem:** Completed PayIn has no credit transaction  
**Cause:** Money movement status is not `completed`  
**Solution:** Check money movement status; transactions only created on `completed`

---

## API Endpoints Reference

### Create PayOut

### Create Direct Link (PayIn)

### Create CheckOut (PayIn)

### Get Money Movement Status

### Get Transaction Details

### Download Transaction Report

---

## 核心要点

✅ **每笔资金流动均有唯一 ID** — 使用 `money_movement_id` 作为主要标识符
✅ **外部 ID 至关重要** — 始终提供 `external_id` 以便对账
✅ **交易时间不同** — PayOuts 立即生成借记；PayIns 仅在完成时生成贷记
✅ **拒绝操作会生成冲正** — PayOut 拒绝会产生 2 笔交易（借记 + 贷记）
✅ **使用交易报告** — 按日期范围下载报告以进行批量对账
✅ **监控状态变更** — 订阅 Webhook 以获取实时对账更新
✅ **净余额公式** — 已完成 PayOuts = -金额，已完成 PayIns = +金额，拒绝 = 0

---