# Open API 积分余额与消耗反馈

## 概述

Open API 提供两种积分反馈方式：

1. 通过 `/open-api/v1/credits-balance` 主动查询账户 API 积分和监控积分余额。
2. 在搜索接口、详情接口、监控接口等业务接口的标准响应体中，直接读取本次请求后的剩余积分和本次消耗积分。

这两种方式可用于前端余额展示、调用日志记录、余额监控和低余额告警。

## 余额查询接口

### 接口信息

- **请求方法**: POST
- **接口地址**: `/open-api/v1/credits-balance`
- **接口说明**: 查询当前 API Key 对应账号的 API 积分和监控积分余额明细。
- **价格说明**: 免费查询，不消耗 API 积分或监控积分。
- **限流说明**: 全局约 1000 次/分钟；单个 API Key 约 60 次/分钟。超过限制时返回 444。

**请求头:**

- Content-Type: application/json
- Accept: application/json

### 请求参数

| 参数名 | 类型 | 必填 | 描述 | 示例 |
| ------ | ---- | ---- | ---- | ---- |
| key | string | 是 | 用户申请的外部 API 请求 key | "your_api_key_here" |

### 请求示例

```bash
curl -X POST "https://www.pipispy.com/open-api/v1/credits-balance" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "key": "your_api_key_here"
  }'
```

### 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "total_api_credits": 10000,
    "remaining_api_credits": 8500,
    "purchased_api_credits": 10000,
    "used_api_credits": 1500,
    "total_monitor_credits": 5000,
    "remaining_monitor_credits": 4200,
    "purchased_monitor_credits": 5000,
    "used_monitor_credits": 800
  },
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "success": true,
  "fail": false
}
```

### data 字段说明

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| total_api_credits | Long | API 积分总数。发生扣除后又退还时，该值可能大于 `purchased_api_credits` |
| remaining_api_credits | Long | API 剩余积分数，用于数据搜索、详情等数据查询接口 |
| purchased_api_credits | Long | API 已购买积分总数 |
| used_api_credits | Long | API 已使用积分总数 |
| total_monitor_credits | Long | 广告/店铺监控积分总数。发生扣除后又退还时，该值可能大于 `purchased_monitor_credits` |
| remaining_monitor_credits | Long | 广告/店铺监控剩余积分数 |
| purchased_monitor_credits | Long | 广告/店铺监控已购买积分总数 |
| used_monitor_credits | Long | 广告/店铺监控已使用积分总数 |

## 业务接口积分反馈

除余额查询接口外，搜索接口、详情接口、监控接口等业务接口的标准响应体会返回以下字段：

| 字段名 | 类型 | 描述 |
| ------ | ---- | ---- |
| remaining_credits | Long | 当前账户剩余可用积分。数据查询类接口返回 API 剩余积分；监控类接口返回监控剩余积分 |
| consumed_credits | Long | 本次请求实际消耗积分。免费访问、请求失败或未扣费时返回 0 |

### 业务接口响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "version": "v1",
  "timestamp": null,
  "sign": null,
  "remaining_credits": 9980,
  "consumed_credits": 20,
  "success": true,
  "fail": false
}
```

### 适用接口

| 接口类型 | 入口 | 积分含义 |
| -------- | ---- | -------- |
| 搜索接口 | `/open-api/v1/data` | 返回 API 剩余积分和本次搜索消耗 |
| 详情接口 | `/open-api/v1/data` | 返回 API 剩余积分和本次详情查询消耗 |
| 监控接口 | `/open-api/v1/monitor/data` | 返回监控剩余积分和本次监控操作消耗 |
| 监控任务接口 | `/open-api/v1/ad-monitor-task/*` | 返回监控剩余积分和本次监控任务操作消耗 |

## 错误码

| 错误码 | 描述 |
| ------ | ---- |
| 200 | 成功 |
| 400 | 请求参数错误，API Key 为空或请求体格式不正确 |
| 401 | 认证失败，API Key 无效或已过期 |
| 442 | 积分不足 |
| 444 | 请求过于频繁，已触发限流 |
| 500 | 服务器内部错误，请稍后重试 |

## 使用建议

1. 需要展示完整余额明细时，调用 `/open-api/v1/credits-balance`。
2. 每次业务调用后，可直接读取 `remaining_credits` 和 `consumed_credits` 记录本次消耗。
3. 当 `remaining_credits` 低于内部阈值时，可触发邮件、飞书、钉钉、Slack 等告警。
4. 如果账号未开通某类积分能力，对应余额字段可能返回 `null`。
5. 建议余额监控任务按分钟级或更低频率调用，避免触发限流。