> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 只读接口

> 使用 Portal token 读取用户的账户、支付方式、订单、退款和购买授权。

所有只读接口都使用 [Portal token](https://docs.clinkbill.com/cn/api-reference/agent-portal/portal_token.md)。接口只读，并且只访问 token 的 `sub` 对应用户。

## 认证

```http theme={null}
Authorization: Bearer {PORTAL_TOKEN}
```

Gateway 校验 `aud=clink-agent-platform-portal`、`scope=portal:read`、`token_use=access`，然后把验证后的客户身份传给 cwallet。请求中没有用于指定其他客户或邮箱的参数。

Clink 响应使用统一 envelope：

```json theme={null}
{
  "code": 200,
  "msg": "Success",
  "data": {}
}
```

以下示例展示 `data`。

## 通用行为

* `pageNum` 和 `pageSize` 使用从 1 开始的分页。
* 订单列表支持 `status`、`from`、`to` 过滤。
* 列表按用户隔离，不按 Agent 过滤；该用户下任意 Agent 创建的订单、退款和授权都会返回。
* 记录不存在，或记录属于其他用户时，返回 `404`。
* 该 API 没有写接口。

## 获取账户信息

```http theme={null}
GET {API_BASE_URL}/agent/platform/me
```

```json theme={null}
{
  "customer_id": "ccus_...",
  "email": "user@example.com",
  "name": "Example User",
  "country": "US",
  "status": "READY"
}
```

| 字段 | 含义 |
| - | - |
| `customer_id` | Clink 客户 ID。 |
| `email` | 客户邮箱。 |
| `name` | 客户显示名。 |
| `country` | 账单地址国家，可能为空。 |
| `status` | 钱包就绪状态：`READY`、`NOT_READY` 或 `SUSPENDED`。`NOT_READY` 表示账户存在但没有可用的默认支付方式。 |

## 支付方式列表

```http theme={null}
GET {API_BASE_URL}/agent/platform/payment-methods
```

```json theme={null}
{
  "payment_methods": [
    {
      "payment_instrument_id": "pi_...",
      "payment_method_type": "CARD",
      "payment_instrument_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "card_last_four": "4242",
      "expiry_month": "12",
      "expiry_year": "2030",
      "issuer_bank": "Example Bank",
      "is_default": true,
      "status": "ACTIVE"
    }
  ]
}
```

`status` 为 `ACTIVE` 或 `DISABLED`。不会返回 PAN 或 CVV。

## 订单列表

```http theme={null}
GET {API_BASE_URL}/agent/platform/orders?pageNum=1&pageSize=20&status={STATUS}&from={ISO_DATE}&to={ISO_DATE}
```

| 参数 | 必填 | 含义 |
| - | - | - |
| `pageNum` | 否 | 页码，从 1 开始。 |
| `pageSize` | 否 | 每页数量。 |
| `status` | 否 | 订单状态过滤。 |
| `from` | 否 | 起始时间下界（包含）。 |
| `to` | 否 | 结束时间上界（包含）。 |

```json theme={null}
{
  "total": 2,
  "page_num": 1,
  "page_size": 20,
  "truncated": false,
  "records": [
    {
      "order_id": "order_...",
      "paid_time": "2026-01-01T00:00:00Z",
      "amount": 42.5,
      "currency": "USD",
      "display_amount": "$42.50",
      "status_code": 1,
      "status": "SUCCESS",
      "merchant_name": "Example Merchant",
      "payment_method_type": "CARD",
      "payment_method_label": "Visa •••• 4242",
      "payment_method_icon": "https://...",
      "payment_instrument_last_four": "4242",
      "agent_info": {
        "clientId": "agent_..."
      }
    }
  ]
}
```

`truncated: true` 表示带状态/时间过滤的扫描达到 Clink 内部扫描上限；`total` 描述已扫描记录，不一定是该用户完整匹配历史。不带过滤时只读取一页，不使用有界扫描。

## 订单详情

```http theme={null}
GET {API_BASE_URL}/agent/platform/orders/{orderId}
```

详情包含下单时间、金额拆分、商户、支付方式、卡组织、商品、收货地址和金额、`agent_info` 以及 `refund_summary`：

```json theme={null}
{
  "order_id": "order_...",
  "order_time": "2026-01-01T00:00:00Z",
  "amount": 42.5,
  "display_amount": "$42.50",
  "subtotal_amount": 40.0,
  "display_subtotal_amount": "$40.00",
  "currency": "USD",
  "status_code": 1,
  "status": "SUCCESS",
  "merchant_name": "Example Merchant",
  "merchant_url": "https://merchant.example",
  "payment_method_type": "CARD",
  "payment_method_label": "Visa •••• 4242",
  "payment_instrument_last_four": "4242",
  "card_scheme": "VISA",
  "credit_amount": 2.5,
  "display_credit_amount": "$2.50",
  "paid_amount": 42.5,
  "display_paid_amount": "$42.50",
  "products": [],
  "agent_info": {},
  "refund_summary": {
    "refund_count": 0,
    "refunded_amount": 0,
    "currency": "USD",
    "latest_status": null,
    "refunds": []
  }
}
```

## 退款列表

```http theme={null}
GET {API_BASE_URL}/agent/platform/refunds?pageNum=1&pageSize=20
```

```json theme={null}
{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "refund_order_id": "refund_...",
      "order_id": "order_...",
      "refund_amount": 10.0,
      "refund_currency": "USD",
      "status": "SUCCESS",
      "refund_reason": "Customer request",
      "payment_instrument_id": "pi_..."
    }
  ]
}
```

## 退款详情

```http theme={null}
GET {API_BASE_URL}/agent/platform/refunds/{refundOrderId}
```

返回单条退款，字段同上。退款属于其他用户时返回 `404`。

## 授权列表

```http theme={null}
GET {API_BASE_URL}/agent/platform/authorizations?pageNum=1&pageSize=20&status={STATUS}
```

| 参数 | 必填 | 含义 |
| - | - | - |
| `pageNum` | 否 | 页码，从 1 开始。 |
| `pageSize` | 否 | 每页数量。 |
| `status` | 否 | 授权状态过滤。 |

```json theme={null}
{
  "total": 1,
  "page_num": 1,
  "page_size": 20,
  "records": [
    {
      "instruction_id": "inst_...",
      "client_reference_id": "platform-ref-1",
      "payment_instrument_id": "pi_...",
      "card_last_four": "4242",
      "card_type": "VIRTUAL_CARD",
      "card_scheme": "VISA",
      "title": "Example authorization",
      "description": "Purchase authorization",
      "total_amount_limit": 100.0,
      "currency_code": "USD",
      "effective_until_time": "2026-02-01T00:00:00Z",
      "is_recurring": false,
      "status": "ACTIVE",
      "agent_info": {},
      "mandates": [],
      "usages": []
    }
  ]
}
```

## 授权详情

```http theme={null}
GET {API_BASE_URL}/agent/platform/authorizations/{instructionId}
```

详情包含指令字段、`mandates` 和 `usages`。`usages` 是原始使用记录；Portal 展示已用和剩余金额时由调用方自行汇总。授权属于其他用户时返回 `404`。

## 错误

| HTTP status | 含义 |
| - | - |
| `400` | 查询参数无效。 |
| `401` | Portal token 缺失、过期或无效。 |
| `403` | token audience/scope 不正确，或误用了平台 client token。 |
| `404` | 记录不存在，或不属于 token 对应用户。 |
| `429` | 超过限流。 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.