POST `/points/{user_id}/exchange`

将积分兑换为指定类型的物品（如优惠券、折扣等）。需要租户开启 ExchangeEnabled 配置。兑换后积分即扣除，不可逆。

积分服务 `bearerAuth` application/json

请求参数

名称	位置	类型	必填	默认值	示例	约束	描述
`user_id`	`path`	`string`	是				用户ID
`X-Idempotency-Key`	`header`	`string`	否				幂等键，推荐UUID

请求体

Schema： service-point/internal/handler/dto.ExchangePointsRequest

字段	类型	必填	示例	约束	描述
`amount`	`integer`	是
`description`	`string`	否
`exchange_type`	`string`	否
`source`	`string`	否

响应

状态	描述	Schema
200	积分兑换成功，返回账户和交易记录	`service-point/internal/handler/dto.PointOperationResponse`
400	请求参数错误或余额不足	`service-core/base/dto.SimpleResponse`
401	未认证	`service-core/base/dto.SimpleResponse`
404	账户不存在	`service-core/base/dto.SimpleResponse`
500	服务器内部错误	`service-core/base/dto.SimpleResponse`

引用的 Schema

service-core/base/dto.SimpleResponse

字段	类型	必填	示例	约束	描述
`code`	`integer`	否
`message`	`string`	否
`timestamp`	`string`	否

service-point/internal/handler/dto.PointAccountResponse

字段	类型	必填	示例	约束	描述
`balance`	`integer`	否	`1500`
`created_at`	`string`	否	`2026-01-15T10:30:00Z`
`exchange_rate`	`integer`	否	`100`
`expired_points`	`integer`	否	`100`
`frozen_balance`	`integer`	否	`200`
`id`	`string`	否	`01ARZ3NDEKTSV4RRFFQ69G5FAV`
`points_type`	`string`	否	`cash_equivalent`
`status`	`string`	否	`active`
`tenant_id`	`string`	否	`tnt_example_001`
`total_earned`	`integer`	否	`5000`
`total_spent`	`integer`	否	`3500`
`updated_at`	`string`	否	`2026-04-10T14:20:00Z`
`user_id`	`string`	否	`usr_example_001`
`version`	`integer`	否	`3`

service-point/internal/handler/dto.PointOperationData

字段	类型	必填	示例	约束	描述
`account`	`service-point/internal/handler/dto.PointAccountResponse`	否
`points_earned`	`integer`	否	`100`
`transaction`	`service-point/internal/handler/dto.PointTransactionResponse`	否

service-point/internal/handler/dto.PointOperationResponse

字段	类型	必填	示例	约束	描述
`code`	`integer`	否
`data`	`service-point/internal/handler/dto.PointOperationData`	否
`message`	`string`	否
`timestamp`	`string`	否

service-point/internal/handler/dto.PointTransactionResponse

字段	类型	必填	示例	约束	描述
`account_id`	`string`	否	`01ARZ3NDEKTSV4RRFFQ69G5FAV`
`amount`	`integer`	否	`100`
`balance_after`	`integer`	否	`1500`
`balance_before`	`integer`	否	`1400`
`created_at`	`string`	否	`2026-04-15T10:30:00Z`
`description`	`string`	否	`每日签到奖励`
`expires_at`	`string`	否	`2027-01-15T10:30:00Z`
`id`	`string`	否	`01ARZ3NDEKTSV4RRFFQ69G5FAV`
`idempotency_key`	`string`	否	`ik_abc123`
`reason`	`string`	否	`签到奖励`
`related_id`	`string`	否	`01ARZ3NDEKTSV4RRFFQ69G5FAV`
`source`	`string`	否	`daily_checkin`
`status`	`string`	否	`completed`
`type`	`string`	否	`earn`
`updated_at`	`string`	否	`2026-04-15T10:30:00Z`
`user_id`	`string`	否	`usr_example_001`

在 Scalar 中试用此 API → 下载 OpenAPI 规范（JSON）↓