Эндпоинты Membership
Модуль Membership управляет людьми, церквями, группами, домохозяйствами, ролями, правами доступа, формами и настройками. Это самый крупный модуль; он обеспечивает основной слой идентификации и авторизации для всех остальных модулей.
Базовый путь: /membership
Люди
Базовый путь: /membership/people
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | People.View или Member | Список всех людей церкви |
| GET | /:id | JWT | People.View или собственная запись | Получить человека по ID (включает отправки форм) |
| GET | /ids?ids= | JWT | People.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 | /names | JWT | Любое право церкви | То же, что GET /names. Тело: { peopleIds } (или { ids }) |
| GET | /recent | JWT | People.View, Member или People.ViewNames | Недавно добавленные люди. Вызывающие с People.ViewNames без People.View (даже участники с доступом к каталогу) получают базовую модель (id, name.display, photo, membershipStatus), при этом люди, отказавшиеся от показа, не возвращаются |
| GET | /guest-register/options?churchId= | Public | — | Чек-лист регистрации гостей по QR-коду: возвращает { email, phone, address, birthDate, gender, maritalStatus, grade, comments }, где каждое значение — "off", "optional" или "required" (разбирается из публичной настройки guestRegistrationFields; при отсутствии или неверном значении используются значения по умолчанию: email/телефон — необязательные, остальное — выключено). Требует enableQRGuestRegistration, если только запрос не содержит подходящий токен сайта или церкви; ограничено по частоте (429) |
| GET | /search?term=&email= | JWT | People.View, Member или People.ViewNames | Поиск людей по имени или email (до 100, сортировка по фамилии, затем по имени). Вызывающие с People.ViewNames без People.View (даже участники с доступом к каталогу) получают при поиске по имени базовую модель; поиск по email возвращает [] |
| GET | /search/phone?number= | JWT | People.View или Member | Поиск по номеру телефона |
| GET | /search/group?groupId= | JWT | People.View или Member | Получить людей в конкретной группе |
| GET | /household/:householdId | JWT | — | Получить всех людей домохозяйства |
| GET | /attendance | JWT | People.Edit | Загрузить посетителей с фильтрами (campusId, serviceId, serviceTimeId, groupId, categoryName, startDate, endDate) |
| GET | /timeline?personIds=&groupIds= | JWT | — | Загрузить данные временной шкалы для людей и групп |
| GET | /directory/:id | JWT | — | Получить человека для просмотра в каталоге (учитываются настройки видимости) |
| GET | /claim/:churchId | JWT | — | Привязать запись человека к текущему пользователю в церкви |
| POST | / | JWT | People.Edit или EditSelf | Создать или обновить людей (пакетно) |
| POST | /search | JWT | People.View, Member или People.ViewNames | Поиск людей (вариант POST). Тело: { term } или { email }; те же правила для режима только имён, что и у GET /search |
| POST | /advancedSearch | JWT | People.View или Member | Поиск по нескольким условиям (возраст, birthMonth, membershipStatus и др.). Тело — массив условий; пустое тело означает отсутствие условий, а любое другое тело, не являющееся массивом, возвращает 400 |
| POST | /loadOrCreate | Public | — | Найти или создать человека по email. Тело: { churchId, email, firstName, lastName } |
| POST | /guest-register | Public | — | Регистрация гостя по QR-коду. Тело: { churchId, members: [{ firstName, lastName, email?, phone?, birthDate?, gender?, grade? }], address?, maritalStatus?, comments? } (от 1 до 10 участников; email/phone/maritalStatus относятся только к первому участнику). Поля, отключённые церковью, отбрасываются; отсутствующие обязательные или неверные значения возвращают 400. Сначала используются существующие люди: участник совпадает, если ровно один не удалённый человек имеет то же имя (без учёта регистра) и тот же email или цифры телефона (домашний, рабочий или мобильный); участник без email или телефона совпадает по имени внутри совпавшего домохозяйства. Совпавших людей никогда не редактируют. Несовпавшие участники присоединяются к совпавшему домохозяйству или создают новое (названное по фамилии первого участника) со статусом membershipStatus: "Visitor" и общим address. Сохраняет comments как заметку у первого участника, добавляет всех в приватную группу guestRegistrationGroupId, если она задана, и — когда guestRegistrationRecordAttendance равно "true" — записывает посещаемость на те запланированные времена служений этой группы, окно регистрации которых открыто сейчас. Возвращает { householdId, people: [{ id, name }] }, повторяя переданные имена, а не сохранённые. Те же правила согласия/токена и ограничения по частоте, что и для запроса options |
| POST | /household/:householdId | JWT | People.Edit | Обновить назначения участников домохозяйства |
| POST | /public/email | Public | — | Отправить письмо человеку. Тело: { churchId, personId, subject, body, appName } |
| POST | /apiEmails | Internal | — | Загрузить email людей по ID (межсерверный вызов, требуется jwtSecret) |
| DELETE | /:id | JWT | People.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
См. Аутентификация и права доступа — эндпоинты входа, регистрации и управления паролями.
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| POST | /login | Public | — | Вход (email/пароль, обновление JWT или authGuid) |
| POST | /register | Public | — | Зарегистрировать нового пользователя |
| POST | /forgot | Public | — | Отправить письмо для сброса пароля |
| POST | /setPasswordGuid | Public | — | Задать пароль по auth GUID из ссылки в письме |
| POST | /verifyCredentials | Public | — | Проверить email/пароль и вернуть связанные церкви |
| POST | /loadOrCreate | JWT | — | Найти или создать пользователя по email/userId |
| POST | /setDisplayName | JWT | — | Обновить имя и фамилию пользователя |
| POST | /updateEmail | JWT | — | Сменить email пользователя |
| POST | /updatePassword | JWT | — | Сменить пароль пользователя (минимум 6 символов) |
| POST | /updateOptedOut | JWT | — | Задать статус отказа от показа для человека |
| POST | /sendInviteEmail | JWT | People.Edit | Отправить приглашение человеку в этой церкви (email, personName, contextName). Кнопка называется Sign Up для человека без учётной записи и Log In для существующего пользователя. Пользователь, который ни разу не входил, получает ссылку Set Your Password, действительную 7 дней. Это фиксированный шаблон, поэтому он не учитывается в дневном лимите писем церкви |
| GET | /search?term= | JWT | Server.Admin | Поиск всех пользователей по имени/email |
| DELETE | / | JWT | — | Удалить учётную запись текущего пользователя |
Церкви
Базовый путь: /membership/churches
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Загрузить все церкви текущего пользователя |
| GET | /:id | JWT | — | Получить церковь по ID |
| GET | /:id/getDomainAdmin | JWT | — | Получить доменного администратора церкви |
| GET | /:id/impersonate | JWT | Server.Admin | Войти от имени церкви (только администратор сервера) |
| GET | /all?term= | JWT | Server.Admin | Поиск всех церквей (администратор) |
| GET | /search/?name= | Public | — | Поиск церквей по названию |
| GET | /lookup/?subDomain=&id= | Public | — | Найти церковь по поддомену или ID |
| POST | / | JWT | Settings.Edit | Обновить данные церкви |
| POST | /add | JWT | — | Зарегистрировать новую церковь. Обязательные поля: name, address1, city, state, zip, country |
| POST | /search | Public | — | Поиск церквей по названию (вариант POST) |
| POST | /select | JWT | — | Выбрать/переключиться на церковь. Тело: { churchId } или { subDomain } |
| POST | /:id/archive | JWT | Server.Admin | Архивировать или разархивировать церковь |
| POST | /byIds | Public | — | Загрузить несколько церквей по ID |
| DELETE | /deleteAbandoned | JWT | Server.Admin | Удалить церкви, брошенные 7 и более дней |
Группы
Базовый путь: /membership/groups
Наследует стандартный CRUD (GET /, GET /:id из базового класса).
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Список всех групп |
| GET | /:id | JWT | — | Получить группу по ID |
| GET | /search?campusId=&serviceId=&serviceTimeId= | JWT | — | Поиск групп по фильтрам служений |
| GET | /my | JWT | — | Получить группы текущего пользователя |
| GET | /my/:tag | JWT | — | Получить группы текущего пользователя, отфильтрованные по тегу |
| GET | /tag/:tag | JWT | — | Получить все группы с определённым тегом |
| GET | /public/:churchId/:id | Public | — | Получить публичную группу по церкви и ID |
| GET | /public/:churchId/tag/:tag | Public | — | Получить публичные группы по тегу |
| GET | /public/:churchId/label?label= | Public | — | Получить публичные группы по метке |
| GET | /public/:churchId/slug/:slug | Public | — | Получить публичную группу по slug |
| POST | / | JWT | Groups.Edit | Создать или обновить группы (slug генерируется автоматически) |
| DELETE | /:id | JWT | Groups.Edit | Удалить группу (для групп служений также удаляются дочерние команды) |
Участники групп
Базовый путь: /membership/groupmembers
Наследует стандартный CRUD (GET /:id, DELETE /:id из базового класса).
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /:id | JWT | GroupMembers.View | Получить участника группы по ID |
| GET | / | JWT | GroupMembers.View* | Список участников групп. Фильтры: ?groupId=, ?groupIds= или ?personId=. *Также разрешено, если пользователь состоит в группе или запрашивает собственный personId, а также для ?groupId= любой не конфиденциальной группы, если у пользователя есть Attendance.View или Attendance.Edit (для них включаются участники младше 13 лет) |
| GET | /my | JWT | — | Получить членство в группах текущего пользователя |
| GET | /basic/:groupId | JWT | — | Получить базовый список участников группы |
| GET | /public/leaders/:churchId/:groupId | Public | — | Получить руководителей группы (публично) |
| GET | /public/:churchId/:groupId | Public | — | Получить публичный состав группы (минимальные поля: personId, displayName, leader, фото). Только если группа включила publicRoster; обслуживает элемент staffGrid конструктора сайтов |
| POST | / | JWT | GroupMembers.Edit | Добавить или обновить участников групп |
| DELETE | /:id | JWT | GroupMembers.View | Удалить участника группы |
Домохозяйства
Базовый путь: /membership/households
Стандартный контроллер CRUD.
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Список всех домохозяйств |
| GET | /:id | JWT | — | Получить домохозяйство по ID |
| POST | / | JWT | People.Edit | Создать или обновить домохозяйства |
| DELETE | /:id | JWT | People.Edit | Удалить домохозяйство |
Роли
Базовый путь: /membership/roles
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /:id | JWT | Roles.View | Получить роль по ID |
| GET | /church/:churchId | JWT | Roles.View | Получить все роли церкви. Каждая роль включает memberCount — количество разных пользователей в ней |
| POST | / | JWT | Roles.Edit | Создать или обновить роли |
| DELETE | /:id | JWT | Roles.Edit | Удалить роль (также удаляются её права и участники) |
Участники ролей
Базовый путь: /membership/rolemembers
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /roles/:id | JWT | Roles.View | Получить участников роли. Добавьте ?include=users, чтобы включить данные пользователей |
| POST | / | JWT | Roles.Edit | Добавить участников в роль (создаёт пользователя, если email не существует) |
| DELETE | /:id | JWT | Roles.View | Удалить участника роли |
| DELETE | /self/:churchId/:userId | JWT | — | Удалить себя из церкви |
Права ролей
Базовый путь: /membership/rolepermissions
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /roles/:id | JWT | Roles.View | Получить права роли (используйте null как ID для роли «Everyone») |
| POST | / | JWT | Roles.Edit | Создать или обновить права ролей |
| DELETE | /:id | JWT | Roles.Edit | Удалить право роли |
Права
Базовый путь: /membership/permissions
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Получить полный список доступных прав |
Каждая запись содержит apiName, section (тип содержимого), action и подписи displaySection / displayAction, которые показывает редактор ролей B1Admin. Недавние добавления: MembershipApi / People / View Names (View People Names Only, в разделе People and Groups) и GivingApi / Donations / Enter (Enter Donations, в разделе Donations; см. Пакеты пожертвований).
Формы
Базовый путь: /membership/forms
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | Forms.Admin или Forms.Edit | Список всех форм (администратор видит все; редакторы — назначенные и не-участнические формы) |
| GET | /:id | JWT | Доступ к форме | Получить форму по ID |
| GET | /archived | JWT | Forms.Admin или Forms.Edit | Список архивных форм |
| GET | /group/:groupId | JWT | Участник группы, руководитель группы или Forms.Admin | Отдельные формы, связанные с группой (forms.groupId), без архивных, отсортированные по названию. Возвращает id, name, description и open (в пределах периода доступности). Участники получают только открытые формы; руководители и администраторы форм также получают закрытые. Обслуживает раздел связанных форм на странице группы |
| GET | /standalone/:id?churchId= | JWT | — | Получить отдельную форму (ограниченные формы требуют аутентификации) |
| POST | / | JWT | Forms.Admin или Forms.Edit | Создать или обновить формы. Отдельные формы принимают необязательные photoUrl (фото в шапке над формой) и groupId (связанная группа) |
| DELETE | /:id | JWT | Доступ к форме | Удалить форму |
Отправки форм
Базовый путь: /membership/formsubmissions
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | Forms.Admin или Forms.Edit | Список отправок. Фильтры: ?personId= или ?formId= |
| GET | /my?include=questions,answers | JWT | — | Только свои: до 50 отправок отдельных форм (не форм людей), которые отправил вошедший участник или которые привязаны к его записи (contentType = person, contentId = ID его записи — например, после смены человека администратором), сначала новые, каждая с form.name. include добавляет к каждой форме вопросы, а к отправке — ответы. Возвращает 401, если пользователь не привязан к записи человека. Обслуживает раздел My Forms на странице B1 Me |
| GET | /group/:groupId | JWT | Руководитель группы | Ответы для руководителей группы: по одной записи на каждую связанную форму и на каждое событие группы с формой регистрации; каждая содержит form, event (id, title, start; только для записей о событиях), questions и submissions (с answers и personName, null для анонимных) |
| GET | /:id | JWT | Forms.Admin, Forms.Edit или право на просмотр | Получить отправку по ID. Добавьте ?include=form,questions,answers. Руководители связанной с формой группы, а также руководители группы, к которой относится регистрация на событие, также могут её читать |
| GET | /formId/:formId | JWT | Доступ к форме (просмотр) | Получить все отправки формы (включает форму, вопросы, ответы). Руководители связанной с формой группы имеют доступ на просмотр |
| POST | / | JWT | — | Отправить ответы на форму (обрабатывает ограниченные и неограниченные формы, отправляет уведомления по email). Если у формы включён autoCreatePerson, находит или создаёт Guest-человека по email и привязывает к нему отправку; если у формы также есть groupId, добавляет этого человека в группу; если заданы followUpSubject/followUpBody, отправляет отправителю письмо по шаблону. Если вызывающий не может управлять формой, submittedBy всегда устанавливается в запись человека вошедшего участника (или остаётся пустым для анонимных отправок) |
| DELETE | /:id | JWT | Forms.Admin или Forms.Edit | Удалить отправку и её ответы |
Вопросы
Базовый путь: /membership/questions
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | Доступ к форме | Список вопросов формы. Требуется ?formId= |
| GET | /:id | JWT | Доступ к форме | Получить вопрос по ID |
| GET | /unrestricted?formId= | JWT | — | Получить вопросы неограниченной формы |
| GET | /sort/:id/up | JWT | — | Переместить вопрос вверх в порядке сортировки |
| GET | /sort/:id/down | JWT | — | Переместить вопрос вниз в порядке сортировки |
| POST | / | JWT | Доступ к форме | Создать или обновить вопросы (порядок сортировки назначается автоматически) |
| DELETE | /:id?formId= | JWT | Доступ к форме | Удалить вопрос |
Ответы
Базовый путь: /membership/answers
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | Forms.Admin или Forms.Edit | Список ответов. Фильтр: ?formSubmissionId= |
| POST | / | JWT | Forms.Admin или Forms.Edit | Создать или обновить ответы |
Права участников на формы
Базовый путь: /membership/memberpermissions
Управляет доступом отдельных участников к конкретным формам.
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /:id | JWT | Доступ к форме | Получить право участника на форму по ID |
| GET | /member/:id | JWT | Доступ к форме | Получить все права участника на формы |
| GET | /form/:id | JWT | Доступ к форме | Получить все права участников на форму |
| GET | /form/:id/my | JWT | Доступ к форме | Получить право текущего пользователя на форму |
| POST | / | JWT | Доступ к форме | Создать или обновить права участника на форму |
| DELETE | /:id?formId= | JWT | Доступ к форме | Удалить право участника на форму |
| DELETE | /member/:id?formId= | JWT | Доступ к форме | Удалить все права участника на форме |
Настройки
Базовый путь: /membership/settings
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | Settings.Edit | Получить все настройки церкви |
| GET | /public/:churchId | Public | — | Получить публичные настройки церкви |
| POST | / | JWT | Settings.Edit | Сохранить настройки (поддерживает загрузку изображений в base64) |
Домены
Базовый путь: /membership/domains
Наследует стандартный CRUD (GET /:id, GET /, DELETE /:id из базового класса).
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | / | JWT | — | Список всех доменов |
| GET | /:id | JWT | — | Получить домен по ID |
| GET | /lookup/:domainName | JWT | — | Найти домен по имени |
| GET | /public/lookup/:domainName | Public | — | Публичный поиск домена по имени |
| GET | /health/check | Public | — | Запустить проверку работоспособности непроверенных доменов |
| POST | / | JWT | Settings.Edit | Создать или обновить домены (обновляет Caddy) |
| DELETE | /:id | JWT | Settings.Edit | Удалить домен |
Связь пользователя с церковью
Базовый путь: /membership/userchurch
Управляет связью между пользователями и церквями.
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /userid/:userId | JWT | — | Получить запись «пользователь — церковь» по ID пользователя |
| GET | /personid/:personId | JWT | — | Получить email связанного пользователя для человека |
| GET | /user/:userId | JWT | Server.Admin | Загрузить все церкви пользователя |
| POST | / | JWT | — | Создать связь пользователя с церковью |
| PATCH | /:userId | JWT | — | Обновить время последнего доступа и записать доступ в журнал |
| DELETE | /record/:userId/:churchId/:personId | JWT | — | Удалить запись «пользователь — церковь» |
Настройки видимости
Базовый путь: /membership/visibilityPreferences
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| GET | /my | JWT | — | Получить настройки видимости текущего пользователя |
| POST | / | JWT | — | Сохранить настройки видимости (видимость адреса, телефона, email) |
Запрос
Базовый путь: /membership/query
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| POST | /members | JWT | — | Поиск участников на естественном языке с помощью ИИ. Тело: { text, subDomain, siteUrl } |
Ошибки клиента
Базовый путь: /membership/clientErrors
| Метод | Путь | Auth | Права | Описание |
|---|---|---|---|---|
| POST | / | JWT | — | Записать ошибку на стороне клиента |
Связанные страницы
- Аутентификация и права доступа — процесс входа, JWT, OAuth, модель прав
- Эндпоинты Attendance — учёт служений и посещений
- Структура модулей — организация кода