API 接口详细文档

Name: 麦喵单词卡
Rating: 4.8 (1000 reviews)
Author: 麦喵单词卡

微信公众号：磊子 X 麦喵单词卡

API 接口详细文档

麦喵开放 API 提供完整的 HTTP 接口服务，支持卡片和卡组的创建、查询、管理。

基础信息

Base URL: https://fc-mp-7c19cdfb-aa09-46b8-af6b-f7b52e3b3d7b.next.bspapp.com/open-api

App ID: __UNI__235AE90（所有接口都需在 Header 中携带）

认证机制

用户认证

需要登录态的接口（如创建卡组、获取卡片列表）：

Header	类型	说明
`uni-id-token`	string	用户登录凭证，通过 `/login` 接口获取
`app-id`	string	应用标识，固定值 `__UNI__235AE90`

卡组认证

操作卡片的接口（如创建卡片）：

参数	类型	说明
`cardGroupToken`	string	卡组访问凭证（JWT Token），通过 `/getCardGroupOpenApiToken` 获取

接口列表

1. 用户登录

获取用户访问凭证。

接口地址: POST /login

请求头:

app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`mobile`	string	是	手机号
`password`	string	是	密码

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "uid": "用户ID",
    "token": "认证token",
    "tokenExpired": 1672531200000
  }
}

错误响应:

{
  "errCode": 500,
  "errMsg": "手机号不能为空",
  "data": null
}

2. 获取当前用户信息

获取当前登录用户的详细信息。

接口地址: POST /getCurrentUser

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数: 无

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "_id": "user123",
    "nickname": "张三",
    "avatar": "https://example.com/avatar.jpg",
    "registerDate": 1640995200000,
    "expirationDate": 1672531200000,
    "role": ["student"],
    "status": 0,
    "points": 1000,
    "experience": 2500,
    "isVip": true,
    "isForeverVip": false,
    "cardGroup": {
      "_id": "cardgroup123",
      "title": "英语基础词汇",
      "description": "适合初学者的英语词汇",
      "total": 100,
      "isPublic": 1,
      "tags": ["英语", "基础"],
      "createUser": {
        "_id": "creator456",
        "nickname": "李老师",
        "avatar": "https://example.com/teacher.jpg",
        "isVip": true
      }
    }
  }
}

3. 创建卡组

创建新的卡组，需要用户登录态。

接口地址: POST /createCardGroup

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`title`	string	是	卡组标题
`description`	string	否	卡组描述
`tags`	array	否	标签数组，如 `["英语", "基础"]`
`is_public`	integer	否	是否公开：1-公开，0-私有，默认1
`language`	object	否	语言设置 `{ "front": "en", "back": "zh" }`
`is_vip`	integer	否	是否VIP卡组：1-是，0-否，默认0

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "id": "659d5c0821821b50afc316db"
  }
}

4. 获取卡组 Token

获取指定卡组的访问凭证，需要用户登录态且为卡组创建者。

接口地址: POST /getCardGroupOpenApiToken

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`cardGroupId`	string	是	卡组ID

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

5. 重置卡组 Token

重置指定卡组的访问凭证，需要用户登录态且为卡组创建者。

接口地址: POST /resetCardGroupOpenApiToken

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`cardGroupId`	string	是	卡组ID

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "cardGroupId": "659d5c0821821b50afc316db",
    "isSuccess": true,
    "openApiSecret": "new_secret_key"
  }
}

6. 创建卡片

向指定卡组添加新卡片。

接口地址: POST /createCard

请求头:

app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`cardGroupToken`	string	是	卡组访问凭证
`front`	string	是	卡片正面内容
`back`	string	是	卡片背面内容
`imgs`	array	否	图片URL数组，最多9张
`frontNote`	string	否	正面备注
`backNote`	string	否	背面备注

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "id": "659d5c0821821b50afc316db",
    "cardTotal": 10,
    "cardGroupId": "659d5c0821821b50afc316db"
  }
}

7. 获取卡组所有卡片

获取指定卡组内的所有卡片。

接口地址: POST /getAllCard

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`cardGroupId`	string	是	卡组ID

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "count": 100,
    "cards": [
      {
        "id": "card123",
        "cardGroupId": "cardgroup123",
        "front": "Hello",
        "back": "你好",
        "imgs": [],
        "frontNote": "英语问候语",
        "backNote": "中文翻译",
        "createDate": 1640995200000,
        "status": 0
      }
    ]
  }
}

8. 获取不熟悉卡片列表

获取用户标记为不熟悉的卡片列表。

接口地址: POST /getAllUnfamiliarCard

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`cardGroupId`	string	是	卡组ID
`onlyIsShow`	boolean	否	是否只显示可见卡片，默认true
`onlyShowToday`	boolean	否	是否只显示今天的不熟悉卡片，默认false

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "count": 25,
    "cards": [
      {
        "_id": "unfamiliar123",
        "cardGroupId": "cardgroup123",
        "front": "difficult",
        "back": "困难的",
        "imgs": [],
        "frontNote": "形容词",
        "backNote": "表示困难",
        "createDate": 1640995200000,
        "status": 0
      }
    ]
  }
}

9. 获取学习小组成员列表

获取指定学习小组的成员列表，需要用户登录态。

接口地址: POST /getUserList

请求头:

uni-id-token: <用户认证token>
app-id: __UNI__235AE90
Content-Type: application/json

请求参数:

参数	类型	必填	说明
`learningGroupId`	string	是	学习小组ID
`page`	integer	否	页码，默认1
`pageSize`	integer	否	每页数量，默认500
`userStatus`	string	否	用户状态：join(已加入)/audit(待审核)/reject(拒绝)，默认join

状态说明:

status: 0=已加入, 1=已退出, 2=待审核, 3=审核拒绝
source: create=创建者, join=加入者
isVip: 根据expirationDate自动计算

响应示例:

{
  "errCode": 0,
  "errMsg": "success",
  "data": {
    "total": 150,
    "list": [
      {
        "userId": "user123",
        "learningGroupId": "group456",
        "source": "join",
        "status": 0,
        "createDate": 1672531200000,
        "updateDate": 1672531200000,
        "user": {
          "_id": "user123",
          "nickname": "张三",
          "avatar": "https://example.com/avatar.jpg",
          "expirationDate": 1672531200000,
          "points": 100,
          "experience": 500,
          "isVip": true
        }
      }
    ]
  }
}

错误码说明

错误码	说明
0	成功
400	参数错误
401	认证失败
403	权限不足
500	服务器内部错误

常见错误信息

错误信息	原因
`卡片正反面不能为空`	创建卡片时front或back参数为空
`卡组 Token 不能为空`	创建卡片时未提供cardGroupToken
`Token 校验失败`	cardGroupToken无效或已过期
`卡组不存在`	指定的卡组ID不存在
`无权限操作`	当前用户不是卡组的创建者
`卡组未开启 openApi`	卡组未生成openApiSecret

使用流程图

用户登录
    ↓
获取 uni-id-token
    ↓
创建卡组 → 获取 cardGroupId
    ↓
获取卡组 Token → 获取 cardGroupToken
    ↓
批量创建卡片
    ↓
分享卡组给学生

注意事项

App ID 必须：所有接口请求都需要在 Header 中携带 app-id: __UNI__235AE90
Token 有效期：用户登录 token 有过期时间，需要处理续期
卡组 Token：是 JWT 格式，包含卡组 ID 和签名信息
图片上传：创建卡片时图片 URL 需要是可访问的网络地址
权限控制：只有卡组创建者才能获取和重置卡组 Token
频率限制：注意 API 调用频率，避免触发限制

获取帮助

遇到问题？联系我们：

💬 微信公众号：磊子 X 麦喵单词卡
💬 微信：34805850（备注：API）

API 接口详细文档

ON THIS PAGE