JDWA Green-U API接口文档

本文档详细说明了JDWA Green-U平台的API接口规范，包括认证机制、通用参数定义、错误码规范、各功能模块的接口定义及调用示例。本API采用RESTful风格设计，主要用于前端应用与后端服务的数据交互。

接口规范概述

基础信息

基础URL: https://api.green-u.jdwa.com/v1
开发环境URL: https://dev-api.green-u.jdwa.com/v1
测试环境URL: https://test-api.green-u.jdwa.com/v1

通用请求规范

请求头

请求头	说明	是否必须	示例
Authorization	认证令牌，格式为"Bearer {token}"	是	Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type	内容类型	是	application/json
Accept-Language	语言设置	否	zh-CN
User-Agent	客户端标识	否	JDWA-GreenU-App/1.0
X-Request-ID	请求唯一标识	否	550e8400-e29b-41d4-a716-446655440000

通用请求参数

对于GET请求，以下参数可以添加到URL查询字符串中：

参数名	类型	说明	是否必须	示例
pageNum	Integer	页码，从1开始	否	1
pageSize	Integer	每页记录数	否	10
sortField	String	排序字段	否	createTime
sortOrder	String	排序方式：asc/desc	否	desc

通用响应格式

所有API响应均采用JSON格式，基本结构如下：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 响应数据，根据接口定义变化
  }
}

分页响应格式

对于分页数据，响应格式为：

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      // 数据记录数组
    ],
    "total": 100,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 10
  }
}

错误码定义

错误码	说明	HTTP状态码
200	成功	200
400	请求参数错误	400
401	未授权	401
403	权限不足	403
404	资源不存在	404
500	服务器内部错误	500
1001	用户不存在	200
1002	密码错误	200
1003	账号已被锁定	200
2001	积分不足	200
2002	碳积分操作失败	200
3001	活动不存在	200
3002	活动已结束	200
3003	已参与该活动	200
4001	成就未达成	200
5001	奖品库存不足	200
5002	兑换资格不满足	200
5003	订单不存在	200
6001	文件上传失败	200

认证与授权

登录认证

接口URL: /auth/login
请求方式: POST
请求参数:

{
  "username": "user123",
  "password": "password123",
  "deviceId": "A1B2C3D4E5F6",
  "deviceType": "iOS"
}

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "userId": 1001,
    "username": "user123",
    "nickname": "绿色先锋",
    "avatar": "https://example.com/avatar.jpg"
  }
}

刷新令牌

接口URL: /auth/refresh
请求方式: POST
请求参数:

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  }
}

退出登录

接口URL: /auth/logout
请求方式: POST
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "退出成功",
  "data": null
}

用户模块API

获取用户信息

接口URL: /users/info
请求方式: GET
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "userId": 1001,
    "username": "user123",
    "nickname": "绿色先锋",
    "avatar": "https://example.com/avatar.jpg",
    "gender": 1,
    "birthday": "1990-01-01",
    "email": "user@example.com",
    "phone": "13800138000",
    "userLevel": 3,
    "carbonPoints": 5000,
    "registerTime": "2025-01-01 10:00:00",
    "lastLoginTime": "2025-05-25 08:30:00"
  }
}

更新用户信息

接口URL: /users/update
请求方式: POST
请求参数:

{
  "nickname": "环保达人",
  "avatar": "https://example.com/new-avatar.jpg",
  "gender": 1,
  "birthday": "1990-01-01",
  "email": "new-email@example.com"
}

响应结果:

{
  "code": 200,
  "message": "更新成功",
  "data": null
}

修改密码

接口URL: /users/change-password
请求方式: POST
请求参数:

{
  "oldPassword": "password123",
  "newPassword": "newPassword123",
  "confirmPassword": "newPassword123"
}

响应结果:

{
  "code": 200,
  "message": "密码修改成功",
  "data": null
}

获取用户积分历史

接口URL: /users/points/history
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
type	String	积分类型：EARN/SPEND	否	EARN
startDate	String	开始日期	否	2025-01-01
endDate	String	结束日期	否	2025-05-25
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "userId": 1001,
        "pointsType": "EARN",
        "points": 100,
        "source": "DAILY_CHECK_IN",
        "description": "每日签到奖励",
        "createTime": "2025-05-25 08:00:00",
        "relatedId": null
      },
      {
        "id": 2,
        "userId": 1001,
        "pointsType": "SPEND",
        "points": 200,
        "source": "PRIZE_EXCHANGE",
        "description": "兑换环保购物袋",
        "createTime": "2025-05-24 15:30:00",
        "relatedId": "JD2025052412345678"
      }
    ],
    "total": 50,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 5
  }
}

活动模块API

获取活动列表

接口URL: /activities/list
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
type	String	活动类型	否	OFFLINE
status	String	活动状态：NOT_STARTED/IN_PROGRESS/ENDED	否	IN_PROGRESS
keyword	String	搜索关键词	否	植树
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "activityCode": "ACT20250501001",
        "title": "城市公园清洁日",
        "type": "OFFLINE",
        "cover": "https://example.com/activity1.jpg",
        "startTime": "2025-05-01 09:00:00",
        "endTime": "2025-05-01 12:00:00",
        "location": "中央公园",
        "status": "ENDED",
        "participantCount": 120,
        "carbonReduction": 500,
        "rewardPoints": 200,
        "isParticipated": true
      },
      {
        "id": 2,
        "activityCode": "ACT20250510001",
        "title": "线上节能挑战",
        "type": "ONLINE",
        "cover": "https://example.com/activity2.jpg",
        "startTime": "2025-05-10 00:00:00",
        "endTime": "2025-05-17 23:59:59",
        "location": null,
        "status": "IN_PROGRESS",
        "participantCount": 500,
        "carbonReduction": 2000,
        "rewardPoints": 100,
        "isParticipated": false
      }
    ],
    "total": 20,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 2
  }
}

获取活动详情

接口URL: /activities/detail/{activityCode}
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
activityCode	String	活动编码	是	ACT20250501001

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "activityCode": "ACT20250501001",
    "title": "城市公园清洁日",
    "type": "OFFLINE",
    "cover": "https://example.com/activity1.jpg",
    "images": ["https://example.com/activity1_1.jpg", "https://example.com/activity1_2.jpg"],
    "description": "一起来清洁城市公园，保护我们的环境！",
    "content": "<p>活动详细介绍...</p>",
    "startTime": "2025-05-01 09:00:00",
    "endTime": "2025-05-01 12:00:00",
    "registrationDeadline": "2025-04-30 18:00:00",
    "location": "中央公园",
    "address": "北京市海淀区中关村南大街5号",
    "coordinate": {"latitude": 39.9819, "longitude": 116.3092},
    "contactPerson": "张先生",
    "contactPhone": "13800138000",
    "participantLimit": 150,
    "participantCount": 120,
    "carbonReduction": 500,
    "rewardPoints": 200,
    "status": "ENDED",
    "isParticipated": true,
    "requirements": ["年满18岁", "自备劳保手套"],
    "tags": ["环保", "公益", "清洁"]
  }
}

参与活动

接口URL: /activities/participate
请求方式: POST
请求参数:

{
  "activityCode": "ACT20250510001",
  "userInfo": {
    "name": "张三",
    "phone": "13800138000",
    "email": "zhangsan@example.com"
  },
  "extraInfo": {
    "emergencyContact": "李四",
    "emergencyPhone": "13900139000",
    "tShirtSize": "L"
  }
}

响应结果:

{
  "code": 200,
  "message": "参与成功",
  "data": {
    "participationId": "PAR20250525001",
    "qrCode": "https://example.com/qrcode/PAR20250525001.png"
  }
}

提交活动结果

接口URL: /activities/submit-result
请求方式: POST
请求参数:

{
  "activityCode": "ACT20250510001",
  "participationId": "PAR20250525001",
  "carbonReduction": 5,
  "description": "今天减少了5kg碳排放",
  "images": ["data:image/jpeg;base64,...", "data:image/jpeg;base64,..."],
  "location": {"latitude": 39.9819, "longitude": 116.3092}
}

响应结果:

{
  "code": 200,
  "message": "提交成功",
  "data": {
    "submissionId": "SUB20250525001",
    "rewardPoints": 50,
    "achievements": [
      {
        "achievementCode": "ACH20250001",
        "achievementName": "环保新手",
        "description": "首次参与环保活动"
      }
    ]
  }
}

获取我参与的活动

接口URL: /activities/my-participations
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
status	String	活动状态：REGISTERED/COMPLETED/ALL	否	COMPLETED
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "participationId": "PAR20250501001",
        "activityCode": "ACT20250501001",
        "activityTitle": "城市公园清洁日",
        "activityType": "OFFLINE",
        "activityCover": "https://example.com/activity1.jpg",
        "startTime": "2025-05-01 09:00:00",
        "endTime": "2025-05-01 12:00:00",
        "status": "COMPLETED",
        "participationTime": "2025-04-28 15:30:00",
        "completionTime": "2025-05-01 12:05:00",
        "carbonReduction": 5,
        "rewardPoints": 200
      }
    ],
    "total": 5,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

成就系统API

获取用户成就列表

接口URL: /achievements/list
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
achievementType	String	成就类型	否	ENVIRONMENTAL
status	String	成就状态：LOCKED/IN_PROGRESS/COMPLETED	否	COMPLETED
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "achievementCode": "ACH20250001",
        "achievementName": "环保新手",
        "achievementType": "ENVIRONMENTAL",
        "description": "首次参与环保活动",
        "iconUrl": "https://example.com/achievements/novice.png",
        "status": "COMPLETED",
        "progress": 100,
        "completionTime": "2025-05-01 12:05:00",
        "rewardPoints": 50,
        "displayOrder": 1
      },
      {
        "id": 2,
        "achievementCode": "ACH20250002",
        "achievementName": "碳减排先锋",
        "achievementType": "CARBON_REDUCTION",
        "description": "累计减少碳排放达到100kg",
        "iconUrl": "https://example.com/achievements/carbon_pioneer.png",
        "status": "IN_PROGRESS",
        "progress": 65,
        "currentValue": 65,
        "targetValue": 100,
        "completionTime": null,
        "rewardPoints": 100,
        "displayOrder": 2
      }
    ],
    "total": 20,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 2
  }
}

获取成就详情

接口URL: /achievements/detail/{achievementCode}
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
achievementCode	String	成就编码	是	ACH20250001

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "achievementCode": "ACH20250001",
    "achievementName": "环保新手",
    "achievementType": "ENVIRONMENTAL",
    "description": "首次参与环保活动",
    "detailDescription": "参与任意一场环保活动并完成，即可获得此成就。环保活动包括线上和线下的各类活动。",
    "iconUrl": "https://example.com/achievements/novice.png",
    "backgroundUrl": "https://example.com/achievements/novice_bg.png",
    "status": "COMPLETED",
    "progress": 100,
    "currentValue": 1,
    "targetValue": 1,
    "completionTime": "2025-05-01 12:05:00",
    "rewardPoints": 50,
    "rewardBadge": {
      "badgeCode": "BDG20250001",
      "badgeName": "环保新手徽章",
      "badgeUrl": "https://example.com/badges/novice.png"
    },
    "conditions": [
      {
        "conditionCode": "COND001",
        "conditionType": "ACTIVITY_PARTICIPATION",
        "operator": ">=",
        "value": 1,
        "description": "参与环保活动次数 >= 1",
        "isMet": true
      }
    ],
    "unlockPercentage": 80,
    "tips": "可以在"活动"页面查看最新的环保活动并参与",
    "displayOrder": 1
  }
}

刷新用户成就状态

接口URL: /achievements/refresh
请求方式: POST
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "newlyUnlocked": [
      {
        "achievementCode": "ACH20250003",
        "achievementName": "环保达人",
        "iconUrl": "https://example.com/achievements/expert.png",
        "rewardPoints": 100
      }
    ],
    "unlockedCount": 1
  }
}

领取成就奖励

接口URL: /achievements/reward/{achievementCode}
请求方式: POST
请求参数:

参数名	类型	说明	是否必须	示例
achievementCode	String	成就编码	是	ACH20250003

响应结果:

{
  "code": 200,
  "message": "领取成功",
  "data": {
    "rewardPoints": 100,
    "badge": {
      "badgeCode": "BDG20250003",
      "badgeName": "环保达人徽章",
      "badgeUrl": "https://example.com/badges/expert.png"
    }
  }
}

获取用户成就概览

接口URL: /achievements/overview
请求方式: GET
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "totalAchievements": 50,
    "completedAchievements": 15,
    "completionRate": 30,
    "totalPoints": 750,
    "badgeCount": 10,
    "currentBadge": {
      "badgeCode": "BDG20250005",
      "badgeName": "碳中和先锋",
      "badgeUrl": "https://example.com/badges/carbon_neutral.png"
    },
    "typeStatistics": [
      {
        "type": "ENVIRONMENTAL",
        "total": 20,
        "completed": 8
      },
      {
        "type": "CARBON_REDUCTION",
        "total": 15,
        "completed": 5
      },
      {
        "type": "SOCIAL",
        "total": 10,
        "completed": 2
      },
      {
        "type": "EDUCATIONAL",
        "total": 5,
        "completed": 0
      }
    ]
  }
}

获取用户已解锁徽章列表

接口URL: /achievements/badges
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "badgeCode": "BDG20250001",
        "badgeName": "环保新手徽章",
        "badgeUrl": "https://example.com/badges/novice.png",
        "achievementCode": "ACH20250001",
        "achievementName": "环保新手",
        "unlockTime": "2025-05-01 12:05:00",
        "isDisplayed": true
      },
      {
        "badgeCode": "BDG20250003",
        "badgeName": "环保达人徽章",
        "badgeUrl": "https://example.com/badges/expert.png",
        "achievementCode": "ACH20250003",
        "achievementName": "环保达人",
        "unlockTime": "2025-05-10 18:30:00",
        "isDisplayed": false
      }
    ],
    "total": 10,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

设置展示徽章

接口URL: /achievements/badge/display
请求方式: POST
请求参数:

{
  "achievementCode": "ACH20250003",
  "display": true
}

响应结果:

{
  "code": 200,
  "message": "设置成功",
  "data": null
}

获取成就排行榜

接口URL: /achievements/leaderboard
请求方式: GET
请求参数:

参数名	类型	说明	是否必须	示例
type	String	排行榜类型：TOTAL/CARBON_REDUCTION/ACTIVITY	否	TOTAL
pageNum	Integer	页码	否	1
pageSize	Integer	每页记录数	否	10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "rank": 1,
        "userId": 1002,
        "nickname": "森林守护者",
        "avatar": "https://example.com/avatar1.jpg",
        "completedCount": 35,
        "badgeUrl": "https://example.com/badges/master.png",
        "isCurrentUser": false
      },
      {
        "rank": 2,
        "userId": 1005,
        "nickname": "碳中和先锋",
        "avatar": "https://example.com/avatar2.jpg",
        "completedCount": 32,
        "badgeUrl": "https://example.com/badges/pioneer.png",
        "isCurrentUser": false
      },
      {
        "rank": 3,
        "userId": 1001,
        "nickname": "绿色先锋",
        "avatar": "https://example.com/avatar.jpg",
        "completedCount": 30,
        "badgeUrl": "https://example.com/badges/expert.png",
        "isCurrentUser": true
      }
    ],
    "total": 100,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 10,
    "currentUserRank": 3
  }
}

奖品兑换API

获取奖品列表

接口URL: /api/prizes/list
请求方式: GET
请求参数:

参数名	类型	必须	描述
categoryId	Long	否	分类ID
prizeType	String	否	奖品类型：PHYSICAL/VIRTUAL/COUPON/PRIVILEGE/DONATION
prizeLevel	String	否	奖品等级：COMMON/PREMIUM/RARE/EXCLUSIVE
keyword	String	否	搜索关键词
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页大小，默认10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "prizeCode": "P20251001001",
        "prizeName": "环保购物袋",
        "prizeType": "PHYSICAL",
        "prizeLevel": "COMMON",
        "categoryId": 1,
        "pointsPrice": 100,
        "marketPrice": 15.00,
        "cashPrice": null,
        "thumbnail": "http://example.com/images/bag.jpg",
        "description": "环保材质购物袋，减少塑料使用",
        "availableStock": 100,
        "hasEnoughPoints": true
      }
    ],
    "total": 10,
    "pageNum": 1,
    "pageSize": 10
  }
}

获取奖品详情

接口URL: /api/prizes/detail/{prizeCode}
请求方式: GET
请求参数:

参数名	类型	必须	描述
prizeCode	String	是	奖品编码

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "prizeCode": "P20251001001",
    "prizeName": "环保购物袋",
    "prizeType": "PHYSICAL",
    "prizeLevel": "COMMON",
    "categoryId": 1,
    "categoryName": "环保用品",
    "pointsPrice": 100,
    "marketPrice": 15.00,
    "cashPrice": null,
    "thumbnail": "http://example.com/images/bag.jpg",
    "images": ["http://example.com/images/bag1.jpg", "http://example.com/images/bag2.jpg"],
    "description": "环保材质购物袋，减少塑料使用",
    "specification": "尺寸: 40x30cm，材质: 可降解环保材料",
    "exchangeLimit": 5,
    "exchangeStart": "2025-10-01 00:00:00",
    "exchangeEnd": "2025-12-31 23:59:59",
    "weight": 0.2,
    "deliveryFee": 0,
    "availableStock": 100,
    "totalStock": 150,
    "userCurrentPoints": 300,
    "hasEnoughPoints": true,
    "canExchange": true,
    "rules": [
      {
        "id": 1,
        "ruleCode": "LIMIT_001",
        "ruleName": "每人限兑5个",
        "ruleType": "LIMIT",
        "ruleCondition": "{\"limit\":5}",
        "ruleValue": "5",
        "description": "每个用户最多可兑换5个"
      }
    ]
  }
}

购物车操作接口

添加到购物车

接口URL: /api/prizes/cart/add
请求方式: POST
请求参数:

{
  "prizeId": 1,
  "quantity": 2
}

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

购物车列表

接口URL: /api/prizes/cart/list
请求方式: GET
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "id": 1,
      "prizeId": 1,
      "prizeCode": "P20251001001",
      "prizeName": "环保购物袋",
      "prizeType": "PHYSICAL",
      "prizeImage": "http://example.com/images/bag.jpg",
      "pointsPrice": 100,
      "cashPrice": null,
      "quantity": 2,
      "totalPoints": 200,
      "totalCash": 0,
      "prizeStatus": 1,
      "canExchange": true,
      "availableStock": 100,
      "stockEnough": true,
      "selectedStatus": 1
    }
  ]
}

移除购物车商品

接口URL: /api/prizes/cart/remove
请求方式: POST
请求参数:

[1, 2]

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

更新购物车数量

接口URL: /api/prizes/cart/update
请求方式: POST
请求参数:

参数名	类型	必须	描述
cartItemId	Long	是	购物车项ID
quantity	Integer	是	数量

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

订单接口

创建兑换订单

接口URL: /api/prizes/order/create
请求方式: POST
请求参数:

{
  "items": [
    {
      "prizeId": 1,
      "quantity": 2
    }
  ],
  "addressId": 10,
  "deliveryMethod": "EXPRESS",
  "cartItemIds": [1],
  "remark": "请包装好，谢谢"
}

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": "JD2025101012345678901234"
}

获取订单列表

接口URL: /api/prizes/order/list
请求方式: GET
请求参数:

参数名	类型	必须	描述
status	String	否	订单状态
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页大小，默认10

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "orderNo": "JD2025101012345678901234",
        "orderType": "PHYSICAL",
        "totalPoints": 200,
        "totalCash": 0,
        "totalAmount": 2,
        "status": "PENDING",
        "createTime": "2025-10-10 12:34:56",
        "firstPrizeImage": "http://example.com/images/bag.jpg",
        "items": [
          {
            "id": 1,
            "orderId": 1,
            "orderNo": "JD2025101012345678901234",
            "prizeId": 1,
            "prizeName": "环保购物袋",
            "prizeType": "PHYSICAL",
            "prizeImage": "http://example.com/images/bag.jpg",
            "pointsPrice": 100,
            "quantity": 2,
            "totalPoints": 200,
            "status": "PENDING"
          }
        ]
      }
    ],
    "total": 10,
    "pageNum": 1,
    "pageSize": 10
  }
}

获取订单详情

接口URL: /api/prizes/order/detail/{orderNo}
请求方式: GET
请求参数:

参数名	类型	必须	描述
orderNo	String	是	订单编号

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "orderNo": "JD2025101012345678901234",
    "orderType": "PHYSICAL",
    "totalPoints": 200,
    "totalCash": 0,
    "totalAmount": 2,
    "status": "PENDING",
    "paymentStatus": 1,
    "paymentTime": "2025-10-10 12:35:12",
    "deliveryMethod": "EXPRESS",
    "deliveryFee": 0,
    "consignee": "张三",
    "consigneePhone": "13800138000",
    "consigneeAddress": "北京市海淀区中关村南大街5号",
    "logisticsCompany": "顺丰快递",
    "logisticsNo": "SF1234567890",
    "createTime": "2025-10-10 12:34:56",
    "remark": "请包装好，谢谢",
    "items": [
      {
        "id": 1,
        "orderId": 1,
        "orderNo": "JD2025101012345678901234",
        "prizeId": 1,
        "prizeName": "环保购物袋",
        "prizeType": "PHYSICAL",
        "prizeImage": "http://example.com/images/bag.jpg",
        "pointsPrice": 100,
        "quantity": 2,
        "totalPoints": 200,
        "status": "PENDING"
      }
    ],
    "logistics": {
      "logisticsCompany": "顺丰快递",
      "logisticsNo": "SF1234567890",
      "status": "SHIPPED",
      "trackingList": [
        {
          "time": "2025-10-11 09:30:00",
          "status": "已揽收",
          "description": "快递员已揽收"
        },
        {
          "time": "2025-10-11 12:45:00",
          "status": "运输中",
          "description": "货物已到达分拣中心"
        }
      ]
    }
  }
}

取消订单

接口URL: /api/prizes/order/cancel
请求方式: POST
请求参数:

参数名	类型	必须	描述
orderNo	String	是	订单编号
reason	String	是	取消原因

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

确认收货

接口URL: /api/prizes/order/confirm
请求方式: POST
请求参数:

参数名	类型	必须	描述
orderNo	String	是	订单编号

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": null
}

通知系统API

获取用户通知列表

接口URL: /api/notifications/list
请求方式: GET
请求参数:

参数名	类型	必须	描述
type	String	否	通知类型：ALL/SYSTEM/ACTIVITY/ACHIEVEMENT/CARBON/SOCIAL
readStatus	String	否	阅读状态：ALL/READ/UNREAD
pageNum	Integer	否	页码
pageSize	Integer	否	每页记录数

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "notificationId": "NT20250526001",
        "userId": 1001,
        "title": "成就解锁通知",
        "content": "恭喜您解锁了"环保达人"成就！",
        "type": "ACHIEVEMENT",
        "status": "UNREAD",
        "actionType": "VIEW_ACHIEVEMENT",
        "actionParams": {
          "achievementCode": "ACH20250003"
        },
        "createTime": "2025-05-26 15:30:00"
      },
      {
        "id": 2,
        "notificationId": "NT20250525001",
        "userId": 1001,
        "title": "活动提醒",
        "content": "您报名的"城市公园清洁日"活动将于明天上午9点开始，请准时参加。",
        "type": "ACTIVITY",
        "status": "READ",
        "actionType": "VIEW_ACTIVITY",
        "actionParams": {
          "activityCode": "ACT20250501001"
        },
        "readTime": "2025-05-25 18:45:00",
        "createTime": "2025-05-25 12:00:00"
      },
      {
        "id": 3,
        "notificationId": "NT20250524001",
        "userId": 1001,
        "title": "系统公告",
        "content": "Green-U平台已升级至v2.0版本，新增碳减排数据分析功能。",
        "type": "SYSTEM",
        "status": "UNREAD",
        "actionType": "VIEW_ANNOUNCEMENT",
        "actionParams": {
          "announcementId": "AN20250524001"
        },
        "createTime": "2025-05-24 10:00:00"
      }
    ],
    "total": 15,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 2,
    "unreadCount": 8
  }
}

获取通知统计信息

接口URL: /api/notifications/stats
请求方式: GET
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "totalCount": 15,
    "unreadCount": 8,
    "typeStats": [
      {
        "type": "SYSTEM",
        "count": 3,
        "unreadCount": 2
      },
      {
        "type": "ACTIVITY",
        "count": 5,
        "unreadCount": 1
      },
      {
        "type": "ACHIEVEMENT",
        "count": 4,
        "unreadCount": 3
      },
      {
        "type": "CARBON",
        "count": 2,
        "unreadCount": 1
      },
      {
        "type": "SOCIAL",
        "count": 1,
        "unreadCount": 1
      }
    ]
  }
}

标记通知为已读

接口URL: /api/notifications/read
请求方式: POST
请求参数:

{
  "notificationIds": ["NT20250526001", "NT20250524001"],
  "all": false
}

注：当all=true时，notificationIds可为空，表示标记所有通知为已读

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "updatedCount": 2,
    "unreadCount": 6
  }
}

删除通知

接口URL: /api/notifications/delete
请求方式: POST
请求参数:

{
  "notificationIds": ["NT20250525001"]
}

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "deletedCount": 1
  }
}

系统配置API

获取应用配置

接口URL: /api/config/app
请求方式: GET
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "appVersion": "2.0.1",
    "minimumVersion": "1.5.0",
    "forceUpdate": false,
    "updateUrl": "https://www.green-u.jdwa.com/download",
    "updateDescription": "1. 优化用户体验\n2. 修复已知问题\n3. 新增碳减排数据分析",
    "servicePhone": "400-123-4567",
    "serviceEmail": "support@green-u.jdwa.com",
    "privacyPolicyUrl": "https://www.green-u.jdwa.com/privacy",
    "termsOfServiceUrl": "https://www.green-u.jdwa.com/terms",
    "aboutUsUrl": "https://www.green-u.jdwa.com/about",
    "helpCenterUrl": "https://www.green-u.jdwa.com/help"
  }
}

获取APP启动页

接口URL: /api/config/splash
请求方式: GET
请求参数: 无
响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "enable": true,
    "duration": 3,
    "splashList": [
      {
        "id": 1,
        "imageUrl": "https://example.com/splash/image1.jpg",
        "title": "世界环境日特别活动",
        "description": "6月5日，与我们一起守护地球家园",
        "actionType": "ACTIVITY",
        "actionParams": {
          "activityCode": "ACT20250605001"
        },
        "startTime": "2025-06-01 00:00:00",
        "endTime": "2025-06-07 23:59:59"
      }
    ]
  }
}

获取系统公告

接口URL: /api/config/announcements
请求方式: GET
请求参数:

参数名	类型	必须	描述
pageNum	Integer	否	页码
pageSize	Integer	否	每页记录数

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": 1,
        "announcementId": "AN20250524001",
        "title": "Green-U平台已升级至v2.0版本",
        "content": "<p>尊敬的用户：</p><p>Green-U平台现已升级至v2.0版本，新增以下功能：</p><ol><li>碳减排数据分析</li><li>成就系统优化</li><li>社区互动增强</li></ol><p>祝您使用愉快！</p>",
        "publishTime": "2025-05-24 10:00:00",
        "endTime": "2025-06-24 10:00:00",
        "importance": "HIGH",
        "isRead": false
      },
      {
        "id": 2,
        "announcementId": "AN20250520001",
        "title": "系统维护通知",
        "content": "<p>尊敬的用户：</p><p>为提供更好的服务体验，我们将于2025年5月21日凌晨2:00-4:00进行系统维护，届时平台将暂停服务。</p><p>感谢您的理解与支持！</p>",
        "publishTime": "2025-05-20 12:00:00",
        "endTime": "2025-05-21 04:00:00",
        "importance": "MEDIUM",
        "isRead": true
      }
    ],
    "total": 5,
    "pageNum": 1,
    "pageSize": 10,
    "totalPages": 1
  }
}

获取系统参数

接口URL: /api/config/params
请求方式: GET
请求参数:

参数名	类型	必须	描述
keys	String	否	参数键名，多个用逗号分隔

响应结果:

{
  "code": 200,
  "message": "操作成功",
  "data": {
    "CARBON_EXCHANGE_RATE": "10",
    "DAILY_CHECK_IN_POINTS": "5",
    "ACTIVITY_SHARE_POINTS": "10",
    "INVITE_FRIEND_POINTS": "50",
    "CARBON_UPLOAD_MAX_DAILY": "10",
    "FEEDBACK_COOLDOWN_MINUTES": "60"
  }
}

提交用户反馈

接口URL: /api/feedback/submit
请求方式: POST
请求参数:

{
  "type": "SUGGESTION",
  "content": "希望能增加更多种类的环保活动",
  "contactWay": "email",
  "contactValue": "user@example.com",
  "images": ["data:image/jpeg;base64,..."]
}

响应结果:

{
  "code": 200,
  "message": "提交成功",
  "data": {
    "feedbackId": "FB20250526001",
    "createTime": "2025-05-26 18:30:00"
  }
}

数据安全与隐私保护

Green-U API在设计和实现过程中，高度重视用户数据安全和隐私保护，采取了以下措施：

传输安全：所有API通信均使用HTTPS协议，确保数据传输安全
认证授权：
- 使用JWT令牌机制进行身份认证
- 基于RBAC模型的权限控制
- 令牌自动过期和刷新机制
数据保护：
- 敏感信息加密存储
- 用户授权的数据访问范围控制
- 数据最小化原则，只收集必要信息
安全防护：
- API请求频率限制
- 防重放攻击措施
- 实时安全监控与审计
合规性：
- 符合相关数据保护法规要求
- 提供明确的隐私政策和用户协议
- 支持用户数据查询和删除

开发者支持

Green-U为开发者提供以下支持资源：

接口测试环境：
- 测试环境URL: https://test-api.green-u.jdwa.com/v1
- 支持沙箱测试，无需真实数据
- 提供测试账号和测试数据
开发支持：
- 接口变更通知机制
- 详细的错误提示和问题诊断
- 技术支持联系方式: dev-support@green-u.jdwa.com
文档资源：
- 完整的API参考文档
- 常见问题解答
- 最佳实践指南
- 集成示例代码
接口更新策略：
- API版本控制，支持平滑迁移
- 接口废弃提前通知
- 向下兼容原则

版本历史

版本号	发布日期	主要更新内容
v1.0.0	2025-02-01	首次发布，包含用户管理、活动管理和基础功能
v1.1.0	2025-03-15	新增碳减排数据API和成就系统API
v1.2.0	2025-04-10	新增社区互动API和文件上传API
v1.3.0	2025-05-01	新增奖品兑换API和物流查询API
v2.0.0	2025-05-24	全面升级，新增通知系统和系统配置API，优化已有接口

结语

本文档全面介绍了JDWA Green-U平台的API接口规范，旨在为前端开发人员提供清晰的接口使用指南。API接口将持续优化和完善，以支持平台的功能扩展和性能提升。如有疑问或建议，请联系我们的技术支持团队。

作者：记得晚安(JDWA) Email: 1412800823@qq.com GitHub: https://github.com/AAASS554