团队 API

管理团队、成员、角色和邀请，实现协作表单构建。

团队 API 允许您创建和管理协作表单构建的团队。团队允许多个用户共享表单，通过基于角色的访问控制管理谁可以查看、编辑和删除表单及响应。

所有请求和响应体均使用 snake_case 字段命名。

团队角色

ownerrole

完全访问权限。可以管理成员、账单和删除团队。

adminrole

可以创建、编辑、删除表单，管理成员和查看响应。

editorrole

可以创建和编辑表单，查看响应。无法管理成员。

viewerrole

可以查看表单和响应。无法创建或编辑。

Endpoints

GET/api/v1/teamsPOST/api/v1/teamsGET/api/v1/teams/:teamIdPUT/api/v1/teams/:teamIdDELETE/api/v1/teams/:teamIdGET/api/v1/teams/:teamId/membersPOST/api/v1/teams/:teamId/membersPUT/api/v1/teams/:teamId/members/:memberIdDELETE/api/v1/teams/:teamId/members/:memberIdGET/api/v1/teams/:teamId/invitationsPOST/api/v1/teams/:teamId/invitationsDELETE/api/v1/teams/:teamId/invitations/:invId

列出团队

GET/api/v1/teams

返回已认证用户所属的所有团队。

响应

json

{
  "teams": [
    {
      "id": "665b2c3d4e5f6a7b8c9d0e1f",
      "name": "Marketing",
      "slug": "marketing",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-01-10T09:00:00.000Z",
      "updated_at": "2026-02-15T11:30:00.000Z",
      "member_count": 5,
      "your_role": "admin"
    },
    {
      "id": "665c3d4e5f6a7b8c9d0e1f20",
      "name": "Product",
      "slug": "product",
      "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "created_at": "2026-02-01T14:00:00.000Z",
      "updated_at": "2026-02-20T16:45:00.000Z",
      "member_count": 3,
      "your_role": "owner"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建团队

POST/api/v1/teams

创建新团队。已认证用户将成为团队所有者。

请求体

namestring

团队名称

请求示例

json

{
  "name": "Marketing"
}

响应

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing" }'

获取团队

GET/api/v1/teams/:teamId

通过 ID 检索单个团队。

路径参数

teamIdstring

团队 ID

响应

json

{
  "id": "665b2c3d4e5f6a7b8c9d0e1f",
  "name": "Marketing",
  "slug": "marketing",
  "owner_id": "665a0a1b2c3d4e5f6a7b8c9d",
  "created_at": "2026-01-10T09:00:00.000Z",
  "updated_at": "2026-02-15T11:30:00.000Z",
  "member_count": 5
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

更新团队

PUT/api/v1/teams/:teamId

更新团队属性。需要 owner 或 admin 角色。

路径参数

teamIdstring

团队 ID

请求体

namestring

新团队名称

请求示例

json

{
  "name": "Marketing & Growth"
}

响应

返回更新后的团队对象。

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marketing & Growth" }'

删除团队

DELETE/api/v1/teams/:teamId

永久删除团队。仅团队所有者可以删除团队。

删除团队将移除所有团队成员资格和邀请。属于该团队的表单不会被自动删除，但前团队成员将无法再访问。

路径参数

teamIdstring

团队 ID

响应

json

{
  "success": true
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f" \
  -H "Authorization: Bearer YOUR_API_KEY"

列出成员

GET/api/v1/teams/:teamId/members

返回团队的所有成员。

路径参数

teamIdstring

团队 ID

响应

json

{
  "members": [
    {
      "id": "66d1e2f3a4b5c6d7e8f9a0b1",
      "user_id": "665a0a1b2c3d4e5f6a7b8c9d",
      "email": "alice@example.com",
      "first_name": "Alice",
      "last_name": "Johnson",
      "role": "owner",
      "joined_at": "2026-01-10T09:00:00.000Z"
    },
    {
      "id": "66d2e3f4a5b6c7d8e9f0a1b2",
      "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "email": "bob@example.com",
      "first_name": "Bob",
      "last_name": "Smith",
      "role": "editor",
      "joined_at": "2026-01-15T14:30:00.000Z"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY"

添加成员

POST/api/v1/teams/:teamId/members

通过用户 ID 直接将用户添加到团队。需要 owner 或 admin 角色。如需通过邮箱邀请用户，请使用创建邀请。

路径参数

teamIdstring

团队 ID

请求体

user_idstring

要添加的用户 ID

rolestring

分配的角色："admin"、"editor"、"viewer"（默认："viewer"）

请求示例

json

{
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "role": "editor"
}

响应

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "editor",
  "joined_at": "2026-02-28T12:00:00.000Z"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
    "role": "editor"
  }'

更新成员角色

PUT/api/v1/teams/:teamId/members/:memberId

更新团队成员的角色。需要 owner 或 admin 角色。无法更改所有者的角色。

路径参数

teamIdstring

团队 ID

memberIdstring

团队成员 ID

请求体

rolestring

新角色："admin"、"editor"、"viewer"

请求示例

json

{
  "role": "admin"
}

响应

json

{
  "id": "66d2e3f4a5b6c7d8e9f0a1b2",
  "user_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f",
  "role": "admin",
  "joined_at": "2026-01-15T14:30:00.000Z"
}

代码示例

bash

curl -X PUT "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

移除成员

DELETE/api/v1/teams/:teamId/members/:memberId

从团队中移除成员。需要 owner 或 admin 角色。团队所有者不能被移除。

路径参数

teamIdstring

团队 ID

memberIdstring

团队成员 ID

响应

json

{
  "success": true
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/members/66d2e3f4a5b6c7d8e9f0a1b2" \
  -H "Authorization: Bearer YOUR_API_KEY"

列出邀请

GET/api/v1/teams/:teamId/invitations

返回团队所有待处理的邀请。需要 owner 或 admin 角色。

路径参数

teamIdstring

团队 ID

响应

json

{
  "invitations": [
    {
      "id": "66e1f2a3b4c5d6e7f8a9b0c1",
      "email": "carol@example.com",
      "role": "editor",
      "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
      "status": "pending",
      "expires_at": "2026-03-07T12:00:00.000Z",
      "created_at": "2026-02-28T12:00:00.000Z"
    }
  ]
}

代码示例

bash

curl -X GET "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY"

创建邀请

POST/api/v1/teams/:teamId/invitations

发送加入团队的邮件邀请。邀请包含唯一令牌，7 天后过期。需要 owner 或 admin 角色。

路径参数

teamIdstring

团队 ID

请求体

emailstring

要邀请的邮箱地址

rolestring

接受邀请后分配的角色："admin"、"editor"、"viewer"（默认："editor"）

请求示例

json

{
  "email": "carol@example.com",
  "role": "editor"
}

响应

json

{
  "id": "66e1f2a3b4c5d6e7f8a9b0c1",
  "email": "carol@example.com",
  "role": "editor",
  "invited_by": "665a0a1b2c3d4e5f6a7b8c9d",
  "status": "pending",
  "expires_at": "2026-03-07T12:00:00.000Z",
  "created_at": "2026-02-28T12:00:00.000Z"
}

代码示例

bash

curl -X POST "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "carol@example.com",
    "role": "editor"
  }'

取消邀请

DELETE/api/v1/teams/:teamId/invitations/:invId

取消待处理的邀请。需要 owner 或 admin 角色。邀请令牌将不再有效。

路径参数

teamIdstring

团队 ID

invIdstring

邀请 ID

响应

json

{
  "success": true
}

代码示例

bash

curl -X DELETE "https://api.nueform.io/api/v1/teams/665b2c3d4e5f6a7b8c9d0e1f/invitations/66e1f2a3b4c5d6e7f8a9b0c1" \
  -H "Authorization: Bearer YOUR_API_KEY"

错误响应

团队 API 端点返回的标准错误响应。

错误码

400Bad Request

缺少必填字段，角色无效

401Unauthorized

缺少或无效的 API 密钥

403Forbidden

角色权限不足

404Not Found

团队、成员或邀请未找到

409Conflict

用户已是成员，重复邀请

500Server Error

服务器内部错误

错误示例

json

{
  "error": "Not authorized to manage team members"
}

最后更新：2026年4月6日