跳到主要内容

Membership 端点

Membership 模块负责管理人员、教会、小组、家庭、角色、权限、表单和设置。它是规模最大的模块,为所有其他模块提供核心的身份与授权层。

基础路径: /membership

人员​

基础路径:/membership/people

方法路径身份验证权限说明
GET/JWTPeople.View 或 Member列出教会的所有人员
GET/:idJWTPeople.View 或本人记录根据 ID 获取人员(包含表单提交内容)
GET/ids?ids=JWTPeople.View、Member 或 People.ViewNames根据逗号分隔的 ID 获取多个人员。仅具有 People.ViewNames 而不具有 People.View 的调用者会获得基础模型,已退订的人员会被排除(调用者本人除外)
GET/basic?ids=JWT—获取多个人员的基础信息(仅姓名)
GET/names?ids=JWT任意教会权限[{ id, name: { display, first, last }, photo }],按姓氏、再按名字排序,针对调用者已拥有的逗号分隔 ID,使得没有 People.View 的角色(奉献、出勤)也能为人员添加标签。不提供搜索,也不做目录过滤
POST/namesJWT任意教会权限与 GET /names 相同。请求体:{ peopleIds }(或 { ids })
GET/recentJWTPeople.View、Member 或 People.ViewNames最近添加的人员。仅具有 People.ViewNames 而不具有 People.View 的调用者(即使是具有目录访问权限的成员)获得基础模型(id、name.display、photo、membershipStatus),已退订的人员会被排除
GET/guest-register/options?churchId=Public—二维码访客登记的检查清单:返回 { email, phone, address, birthDate, gender, maritalStatus, grade, comments },每项取值为 "off"、"optional" 或 "required"(从公开的 guestRegistrationFields 设置中解析;缺失或格式错误的值会回退为电子邮件/电话为可选、其余关闭)。除非请求携带匹配的网站/教会令牌,否则需要开启 enableQRGuestRegistration;有速率限制(429)
GET/search?term=&email=JWTPeople.View、Member 或 People.ViewNames按姓名或电子邮件搜索人员(最多 100 人,按姓氏、再按名字排序)。仅具有 People.ViewNames 而不具有 People.View 的调用者(即使是具有目录访问权限的成员)会获得返回基础模型的姓名搜索;使用 email 搜索则返回 []
GET/search/phone?number=JWTPeople.View 或 Member按电话号码搜索
GET/search/group?groupId=JWTPeople.View 或 Member获取特定小组中的人员
GET/household/:householdIdJWT—获取某家庭中的所有人员
GET/attendanceJWTPeople.Edit按筛选条件加载出席者(campusId、serviceId、serviceTimeId、groupId、categoryName、startDate、endDate)
GET/timeline?personIds=&groupIds=JWT—加载人员和小组的时间线数据
GET/directory/:idJWT—获取用于通讯录视图的人员信息(遵循可见性偏好)
GET/claim/:churchIdJWT—为当前用户在某教会认领一条人员记录
POST/JWTPeople.Edit 或 EditSelf创建或更新人员(批量)
POST/searchJWTPeople.View、Member 或 People.ViewNames搜索人员(POST 变体)。请求体:{ term } 或 { email };仅姓名可见规则与 GET /search 相同
POST/advancedSearchJWTPeople.View 或 Member多条件搜索(年龄、出生月份、会籍状态等)。请求体为条件数组;空请求体表示无条件,其他非数组的请求体返回 400
POST/loadOrCreatePublic—按电子邮件查找或创建人员。请求体:{ churchId, email, firstName, lastName }
POST/guest-registerPublic—二维码访客登记。请求体:{ churchId, members: [{ firstName, lastName, email?, phone?, birthDate?, gender?, grade? }], address?, maritalStatus?, comments? }(1–10 名成员;email/phone/maritalStatus 仅适用于第一位成员)。教会关闭的字段会被丢弃;缺少必填项或值无效则返回 400。该接口会先复用已有人员:当恰好有一名未被移除的人员与某成员的名字相同(不区分大小写),且电子邮件或电话号码数字(住宅、工作或手机)相同时,即视为匹配;没有电子邮件或电话的成员则在已匹配的家庭内按名字匹配。匹配的人员永远不会被编辑。未匹配的成员会加入已匹配的家庭,或者新建一个家庭(以第一位成员的姓氏命名),会籍状态为 membershipStatus: "Visitor",并使用共享的 address。若提交了 comments,则将其保存为第一位成员的备注;如果设置了 guestRegistrationGroupId,则将所有人加入该私密小组;当 guestRegistrationRecordAttendance 为 "true" 时,还会为该小组中当前签到窗口已开放、且已安排的礼拜时间记录出勤。返回 { householdId, people: [{ id, name }] },回显提交的姓名而非存储的姓名。与选项接口相同的选择加入/令牌及速率限制规则
POST/household/:householdIdJWTPeople.Edit更新家庭成员分配
POST/public/emailPublic—向某人发送电子邮件。请求体:{ churchId, personId, subject, body, appName }
POST/apiEmailsInternal—按 ID 加载人员的电子邮件(服务器间调用,需要 jwtSecret)
DELETE/:idJWTPeople.Edit删除人员

示例:搜索人员​

GET /membership/people/search?term=John
Authorization: Bearer <token>
[
{
"id": "abc-123",
"name": { "first": "John", "last": "Smith" },
"contactInfo": { "email": "john@example.com" },
"membershipStatus": "Member"
}
]

示例:创建人员​

POST /membership/people
Authorization: Bearer <token>

[{ "firstName": "Jane", "lastName": "Doe", "contactInfo": { "email": "jane@example.com" } }]

用户​

基础路径:/membership/users

有关登录、注册和密码管理端点,请参阅身份验证与权限。

方法路径身份验证权限说明
POST/loginPublic—登录(电子邮件/密码、JWT 刷新或 authGuid)
POST/registerPublic—注册新用户
POST/forgotPublic—发送密码重置邮件
POST/setPasswordGuidPublic—使用邮件链接中的 auth GUID 设置密码
POST/verifyCredentialsPublic—验证电子邮件/密码,并返回关联的教会
POST/loadOrCreateJWT—按电子邮件/userId 查找或创建用户
POST/setDisplayNameJWT—更新用户的名字和姓氏
POST/updateEmailJWT—更改用户的电子邮件地址
POST/updatePasswordJWT—更改用户密码(至少 6 个字符)
POST/updateOptedOutJWT—设置人员的退订状态
POST/sendInviteEmailJWTPeople.Edit向本教会的某人发送邀请邮件(email、personName、contextName)。对于没有账号的人,按钮显示 Sign Up(注册);对于已有用户,显示 Log In(登录)。从未登录过的用户则会收到一个 Set Your Password(设置密码)链接,该链接 7 天后过期。这是固定模板,因此不计入教会的每日邮件上限
GET/search?term=JWTServer.Admin按姓名/电子邮件搜索所有用户
DELETE/JWT—删除当前用户账号

教会​

基础路径:/membership/churches

方法路径身份验证权限说明
GET/JWT—加载当前用户的所有教会
GET/:idJWT—根据 ID 获取教会
GET/:id/getDomainAdminJWT—获取某教会的域名管理员用户
GET/:id/impersonateJWTServer.Admin模拟某教会(仅限服务器管理员)
GET/all?term=JWTServer.Admin搜索所有教会(管理员)
GET/search/?name=Public—按名称搜索教会
GET/lookup/?subDomain=&id=Public—按子域名或 ID 查找教会
POST/JWTSettings.Edit更新教会详情
POST/addJWT—注册新教会。必填字段:name、address1、city、state、zip、country
POST/searchPublic—按名称搜索教会(POST 变体)
POST/selectJWT—选择/切换到某教会。请求体:{ churchId } 或 { subDomain }
POST/:id/archiveJWTServer.Admin归档或取消归档某教会
POST/byIdsPublic—按 ID 加载多个教会
DELETE/deleteAbandonedJWTServer.Admin删除已被弃用 7 天以上的教会

小组​

基础路径:/membership/groups

继承标准 CRUD(GET /、GET /:id 来自基类)。

方法路径身份验证权限说明
GET/JWT—列出所有小组
GET/:idJWT—根据 ID 获取小组
GET/search?campusId=&serviceId=&serviceTimeId=JWT—按礼拜筛选条件搜索小组
GET/myJWT—获取当前用户所在的小组
GET/my/:tagJWT—获取当前用户按标签筛选的小组
GET/tag/:tagJWT—获取带有特定标签的所有小组
GET/public/:churchId/:idPublic—按教会和 ID 获取公开小组
GET/public/:churchId/tag/:tagPublic—按标签获取公开小组
GET/public/:churchId/label?label=Public—按标签(label)获取公开小组
GET/public/:churchId/slug/:slugPublic—按 slug 获取公开小组
POST/JWTGroups.Edit创建或更新小组(自动生成 slug)
DELETE/:idJWTGroups.Edit删除小组(对于事工小组,同时删除子团队)

小组成员​

基础路径:/membership/groupmembers

继承标准 CRUD(GET /:id、DELETE /:id 来自基类)。

方法路径身份验证权限说明
GET/:idJWTGroupMembers.View根据 ID 获取小组成员
GET/JWTGroupMembers.View*列出小组成员。可按 ?groupId=、?groupIds= 或 ?personId= 筛选。*若用户在该小组中,或正在查询本人的 personId,同样允许访问;当用户具有 Attendance.View 或 Attendance.Edit 权限时,对任何非保密小组的 ?groupId= 查询同样允许(对其而言会包含 13 岁以下的成员)
GET/myJWT—获取当前用户的小组成员资格
GET/basic/:groupIdJWT—获取某小组的基础成员名单
GET/public/leaders/:churchId/:groupIdPublic—获取小组负责人(公开)
GET/public/:churchId/:groupIdPublic—获取小组的公开名册(最少字段:personId、displayName、leader、照片)。仅当小组通过 publicRoster 选择加入时可用;为网站构建器的 staffGrid 元素提供数据
POST/JWTGroupMembers.Edit添加或更新小组成员
DELETE/:idJWTGroupMembers.View移除小组成员

家庭​

基础路径:/membership/households

标准 CRUD 控制器。

方法路径身份验证权限说明
GET/JWT—列出所有家庭
GET/:idJWT—根据 ID 获取家庭
POST/JWTPeople.Edit创建或更新家庭
DELETE/:idJWTPeople.Edit删除家庭

角色​

基础路径:/membership/roles

方法路径身份验证权限说明
GET/:idJWTRoles.View根据 ID 获取角色
GET/church/:churchIdJWTRoles.View获取某教会的所有角色。每个角色都包含 memberCount,即其中不同用户的数量
POST/JWTRoles.Edit创建或更新角色
DELETE/:idJWTRoles.Edit删除角色(同时删除其权限和成员)

角色成员​

基础路径:/membership/rolemembers

方法路径身份验证权限说明
GET/roles/:idJWTRoles.View获取某角色的成员。添加 ?include=users 可包含用户详情
POST/JWTRoles.Edit将成员添加到角色(如果电子邮件不存在则创建用户)
DELETE/:idJWTRoles.View移除角色成员
DELETE/self/:churchId/:userIdJWT—将自己从某教会中移除

角色权限​

基础路径:/membership/rolepermissions

方法路径身份验证权限说明
GET/roles/:idJWTRoles.View获取某角色的权限(ID 使用 null 表示 "Everyone" 角色)
POST/JWTRoles.Edit创建或更新角色权限
DELETE/:idJWTRoles.Edit删除角色权限

权限​

基础路径:/membership/permissions

方法路径身份验证权限说明
GET/JWT—获取可用权限的完整列表

每个条目都包含 apiName、section(内容类型)、action,以及 B1Admin 角色编辑器所显示的 displaySection / displayAction 标签。近期新增的权限包括:MembershipApi / People / View Names(View People Names Only(仅查看人员姓名),位于 People and Groups(人员与小组)下),以及 GivingApi / Donations / Enter(Enter Donations(录入奉献),位于 Donations(奉献)下;参见奉献批次)。

表单​

基础路径:/membership/forms

方法路径身份验证权限说明
GET/JWTForms.Admin 或 Forms.Edit列出所有表单(管理员可见全部;编辑者可见分配给自己的表单及非成员表单)
GET/:idJWT表单访问权限根据 ID 获取表单
GET/archivedJWTForms.Admin 或 Forms.Edit列出已归档的表单
GET/group/:groupIdJWT小组成员、小组负责人或 Forms.Admin关联到该小组的独立表单(forms.groupId),不包括已归档的表单,按名称排序。返回 id、name、description 和 open(是否在开放时间段内)。成员仅能看到开放的表单;负责人和表单管理员还能看到已关闭的表单。为小组页面的关联表单提供数据
GET/standalone/:id?churchId=JWT—获取独立表单(受限表单需要身份验证)
POST/JWTForms.Admin 或 Forms.Edit创建或更新表单。独立表单可接受可选的 photoUrl(显示在表单上方的页眉照片)和 groupId(关联小组)
DELETE/:idJWT表单访问权限删除表单

表单提交​

基础路径:/membership/formsubmissions

方法路径身份验证权限说明
GET/JWTForms.Admin 或 Forms.Edit列出提交内容。可按 ?personId= 或 ?formId= 筛选
GET/my?include=questions,answersJWT—仅限本人:已登录成员提交的或关联到其人员记录的至多 50 份独立表单提交(不包括人员表单)(contentType 为 person,contentId 为其人员 ID——例如管理员更改人员后),按最新在前排序,每份都包含 form.name。include 会附加每个表单的问题以及提交的答案。如果用户未关联到人员,则返回 401。为 B1 "我的页面"中的 My Forms(我的表单)部分提供数据
GET/group/:groupIdJWT该小组的负责人小组负责人可查看的答复:每个关联表单以及每个带有报名表单的小组活动各对应一条记录,每条包含 form、event(id、title、start;仅活动条目)、questions 以及 submissions(包含 answers 和 personName,匿名时为 null)
GET/:idJWTForms.Admin、Forms.Edit 或查看权限根据 ID 获取提交内容。添加 ?include=form,questions,answers。表单所关联小组的负责人,以及活动报名所属小组的负责人,也可以阅读该内容
GET/formId/:formIdJWT表单访问权限(查看)获取某表单的所有提交内容(包括表单、问题和答案)。表单所关联小组的负责人拥有查看权限
POST/JWT—提交表单答案(处理受限/非受限表单,并发送电子邮件通知)。当表单设置了 autoCreatePerson 时,会按电子邮件查找或创建一名访客人员,并关联该提交内容;若表单还设置了 groupId,则将该人员加入小组;当设置了 followUpSubject/followUpBody 时,会向提交人发送模板化的跟进邮件。除非调用者有权管理该表单,否则 submittedBy 始终设置为已登录成员的人员(匿名提交则留空)
DELETE/:idJWTForms.Admin 或 Forms.Edit删除提交内容及其答案

问题​

基础路径:/membership/questions

方法路径身份验证权限说明
GET/JWT表单访问权限列出某表单的问题。需要 ?formId=
GET/:idJWT表单访问权限根据 ID 获取问题
GET/unrestricted?formId=JWT—获取非受限表单的问题
GET/sort/:id/upJWT—将问题在排序中上移
GET/sort/:id/downJWT—将问题在排序中下移
POST/JWT表单访问权限创建或更新问题(自动分配排序)
DELETE/:id?formId=JWT表单访问权限删除问题

答案​

基础路径:/membership/answers

方法路径身份验证权限说明
GET/JWTForms.Admin 或 Forms.Edit列出答案。可按 ?formSubmissionId= 筛选
POST/JWTForms.Admin 或 Forms.Edit创建或更新答案

成员权限​

基础路径:/membership/memberpermissions

用于控制每位成员对特定表单的访问权限。

方法路径身份验证权限说明
GET/:idJWT表单访问权限根据 ID 获取成员权限
GET/member/:idJWT表单访问权限获取某成员的所有表单权限
GET/form/:idJWT表单访问权限获取某表单的所有成员权限
GET/form/:id/myJWT表单访问权限获取当前用户对某表单的权限
POST/JWT表单访问权限创建或更新成员权限
DELETE/:id?formId=JWT表单访问权限删除成员权限
DELETE/member/:id?formId=JWT表单访问权限删除某成员对某表单的所有权限

设置​

基础路径:/membership/settings

方法路径身份验证权限说明
GET/JWTSettings.Edit获取教会的所有设置
GET/public/:churchIdPublic—获取某教会的公开设置
POST/JWTSettings.Edit保存设置(支持 base64 图片上传)

域名​

基础路径:/membership/domains

继承标准 CRUD(GET /:id、GET /、DELETE /:id 来自基类)。

方法路径身份验证权限说明
GET/JWT—列出所有域名
GET/:idJWT—根据 ID 获取域名
GET/lookup/:domainNameJWT—按名称查找域名
GET/public/lookup/:domainNamePublic—按名称公开查找域名
GET/health/checkPublic—对未检查的域名运行健康检查
POST/JWTSettings.Edit创建或更新域名(会触发 Caddy 更新)
DELETE/:idJWTSettings.Edit删除域名

用户与教会关联​

基础路径:/membership/userchurch

管理用户与教会之间的关联。

方法路径身份验证权限说明
GET/userid/:userIdJWT—按用户 ID 获取用户-教会记录
GET/personid/:personIdJWT—获取某人员所关联用户的电子邮件
GET/user/:userIdJWTServer.Admin加载某用户的所有教会
POST/JWT—创建用户与教会的关联
PATCH/:userIdJWT—更新最近访问时间并记录访问日志
DELETE/record/:userId/:churchId/:personIdJWT—删除用户-教会记录

可见性偏好​

基础路径:/membership/visibilityPreferences

方法路径身份验证权限说明
GET/myJWT—获取当前用户的可见性偏好
POST/JWT—保存可见性偏好(地址、电话、电子邮件的可见性)

查询​

基础路径:/membership/query

方法路径身份验证权限说明
POST/membersJWT—使用 AI 进行自然语言成员搜索。请求体:{ text, subDomain, siteUrl }

客户端错误​

基础路径:/membership/clientErrors

方法路径身份验证权限说明
POST/JWT—记录客户端错误

相关页面​