# API 参考

Monetarie PIX Settlement Service（API 网关）端口 4003 的完整 REST API 参考。

## 前提条件

- Monetarie PIX 后端运行中
- 有效的认证凭据
- HTTP 客户端（curl、Postman 或应用代码）

## 认证

所有 API 端点需要通过登录获取的有效 JWT 会话 Cookie（`pix_session`）：

```bash
# 登录
curl -X POST http://localhost:4003/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{"username":"admin","password":"Admin@2026!"}'

# 已认证请求
curl http://localhost:4003/api/v1/transactions \
  -b cookies.txt
```

对于修改数据的请求，需包含 `pix_csrf` Cookie 中的 CSRF Token。

## 基础 URL

| 服务 | URL | 端口 |
|------|-----|------|
| Settlement（网关） | `http://localhost:4003` | 4003 |
| Dict（内部） | `http://localhost:4001` | 4001 |
| SPI（内部） | `http://localhost:4002` | 4002 |

## 认证端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/auth/public-key` | 用于登录加密的 RSA 公钥 |
| POST | `/api/v1/auth/login` | 登录（返回 HttpOnly JWT Cookie） |
| POST | `/api/v1/auth/mfa/verify` | 验证 MFA 代码 |
| POST | `/api/v1/auth/logout` | 注销（将 JWT 加入黑名单） |
| GET | `/api/v1/auth/me` | 当前用户信息 |

## 交易端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/transactions` | 列出交易（分页、可过滤） |
| GET | `/api/v1/transactions/:id` | 交易详情 |
| POST | `/api/v1/transactions` | 创建交易（支持幂等性） |
| GET | `/api/v1/transactions/:id/history` | 状态历史 |
| GET | `/api/v1/transactions/summary` | 聚合统计 |
| GET | `/api/v1/transactions/export` | CSV 导出 |

### 查询参数（列表）

| 参数 | 类型 | 描述 |
|------|------|------|
| `status` | string | 按状态过滤（PDNG、ACSP、STLD、RJCT、CANC） |
| `e2e_id` | string | 按端到端 ID 搜索（三元组模糊匹配） |
| `start_date` | date | 起始日期过滤（YYYY-MM-DD） |
| `end_date` | date | 结束日期过滤（YYYY-MM-DD） |
| `instrument_type` | string | 按工具类型过滤 |
| `page` | integer | 页码（默认 1） |
| `per_page` | integer | 每页条数（默认 20） |

## DICT 代理端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/keys` | 列出 PIX 密钥 |
| POST | `/api/v1/keys` | 创建 PIX 密钥 |
| GET | `/api/v1/keys/:key` | 查询 PIX 密钥 |
| DELETE | `/api/v1/keys/:key` | 删除 PIX 密钥 |
| POST | `/api/v1/claims` | 创建认领 |
| GET | `/api/v1/claims/:id` | 获取认领详情 |
| POST | `/api/v1/claims/:id/respond` | 响应认领 |
| POST | `/api/v1/claims/:id/cancel` | 取消认领 |

## MED 2.0 端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v2/infraction-reports` | 列出违规报告 |
| GET | `/api/v2/infraction-reports/:id` | 报告详情 |
| PUT | `/api/v2/infraction-reports/:id/acknowledge` | 确认收到 |
| PUT | `/api/v2/infraction-reports/:id/analyse` | 分析（同意/不同意） |
| PUT | `/api/v2/infraction-reports/:id/close` | 关闭报告 |

## 清算端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/settlement/cycles` | 列出清算周期 |
| GET | `/api/v1/settlement/balances` | 参与者余额 |
| GET | `/api/v1/settlement/reconciliation` | 对账结果 |

## 会计端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/accounting/chart-of-accounts` | 44 个 COSIF 账户 |
| GET | `/api/v1/accounting/journal-entries` | 复式记账日记账 |
| GET | `/api/v1/accounting/events` | 会计事件 |
| POST | `/api/v1/accounting/events` | 创建会计事件 |
| GET | `/api/v1/accounting/cost-centers` | 列出成本中心 |
| POST | `/api/v1/accounting/cost-centers` | 创建成本中心 |
| PUT | `/api/v1/accounting/cost-centers/:id` | 更新成本中心 |
| POST | `/api/v1/accounting/cost-centers/:id/toggle-status` | 切换状态 |

## 系统配置

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/system/config` | 列出系统参数 |
| PUT | `/api/v1/system/config/:key` | 更新参数 |
| GET | `/api/v1/system/config/categories` | 列出类别 |
| GET | `/api/v1/system/config/schedules` | 列出调度 |

## 监控端点

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | `/api/v1/monitoring/health` | 详细健康状态 |
| GET | `/api/v1/monitoring/metrics` | BEAM VM 指标 |
| GET | `/api/v1/monitoring/alerts` | 基础设施告警 |

## 错误响应格式（RFC 7807）

所有错误遵循 RFC 7807 `application/problem+json`：

```json
{
  "type": "https://api.fluxiq.com/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or expired token",
  "instance": "/api/v1/transactions"
}
```

## 幂等性

`/api/v1/transactions` 下的 POST 端点支持 `Idempotency-Key` 头：

```bash
curl -X POST http://localhost:4003/api/v1/transactions \
  -H "Idempotency-Key: unique-request-id-123" \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"amount": 10000, "creditor_key": "email@example.com"}'
```

- 每个幂等性键 24 小时 TTL
- 原子 SET NX 防止重复处理
- 最大请求体：64 KB

## 预期结果

查阅本 API 参考后：

- 可以认证并调用所有端点
- 交易 CRUD 操作可通过适当过滤访问
- DICT 代理支持通过网关管理 PIX 密钥
- 错误响应遵循 RFC 7807 实现一致的错误处理