Pular para o conteúdo principal

Endpoints de Frequência

O módulo de Frequência gerencia locais de campus, serviços, horários de serviço, sessões de frequência, visitas e sessões de visita. Ele fornece a infraestrutura para registrar quem compareceu a qual culto ou reunião de grupo, oferece suporte aos fluxos de check-in e disponibiliza relatórios de tendências e resumos de frequência.

Caminho base: /attendance

Campus​

Caminho base: /attendance/campuses

Controlador CRUD padrão (estende GenericCrudController). Fornece as rotas getById, getAll, post e delete por meio da classe base CRUD.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Listar todos os campus da igreja
GET/:idJWT—Obter um campus pelo ID
POST/JWTServices.EditCriar ou atualizar campus
DELETE/:idJWTServices.EditExcluir um campus

Serviços​

Caminho base: /attendance/services

Estende GenericCrudController com as rotas CRUD getById, getAll, post e delete. Os endpoints getAll (GET /) e search são sobrescritos com implementações personalizadas.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Listar todos os serviços (inclui informações do campus)
GET/:idJWT—Obter um serviço pelo ID
GET/search?campusId=JWT—Pesquisar serviços pelo ID do campus
POST/JWTServices.EditCriar ou atualizar serviços
DELETE/:idJWTServices.EditExcluir um serviço

Exemplo: Pesquisar Serviços por Campus​

GET /attendance/services/search?campusId=abc-123
Authorization: Bearer <token>
[
{
"id": "svc-001",
"churchId": "church-123",
"campusId": "abc-123",
"name": "Sunday Morning"
}
]

Horários de Serviço​

Caminho base: /attendance/servicetimes

Estende GenericCrudController com as rotas CRUD getById, post e delete. Os endpoints getAll e search têm implementações personalizadas.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Listar todos os horários de serviço. Filtrar por ?serviceId=. Adicione ?include=groups para incluir os dados dos grupos. Cada linha inclui um booleano calculado checkinOpen (falso somente quando o horário de serviço tem uma programação de check-in cuja janela está fechada neste momento). A janela é medida no fuso horário do campus do serviço, depois no fuso horário da igreja, depois no primeiro campus que tiver um, e por fim em America/New_York
GET/:idJWT—Obter um horário de serviço pelo ID
GET/search?campusId=&serviceId=JWT—Pesquisar horários de serviço por campus e serviço
GET/public/:churchIdPública—Obter a árvore campus → serviço → horário de uma igreja. Alimenta o elemento serviceTimes do construtor de sites
POST/JWTServices.EditCriar ou atualizar horários de serviço. Campos opcionais de programação: dayOfWeek (0 = domingo … 6), startTime / endTime (HH:mm), checkinOpenMinutes (antes do início), checkinCloseMinutes (após o término). O check-in só é limitado por horário quando dayOfWeek e startTime estão definidos
DELETE/:idJWTServices.EditExcluir um horário de serviço

Horários de Serviço dos Grupos​

Caminho base: /attendance/groupservicetimes

Vincula grupos a horários de serviço específicos.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWT—Listar todas as associações grupo-horário de serviço. Filtre por ?groupId= para obter as associações com os nomes dos serviços
GET/:idJWT—Obter uma associação grupo-horário de serviço pelo ID
POST/JWTServices.EditCriar ou atualizar associações grupo-horário de serviço
DELETE/:idJWTServices.EditExcluir uma associação grupo-horário de serviço

Registros de Frequência​

Caminho base: /attendance/attendancerecords

Fornece visões agregadas somente leitura dos dados de frequência para relatórios e exibição.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTAttendance.ViewCarregar os registros de frequência de uma pessoa. Requer ?personId=
GET/myJWT—Com escopo do próprio usuário: os registros de frequência do próprio membro autenticado dos últimos 12 meses, do mais recente para o mais antigo. Retorna 401 se o usuário não estiver vinculado a uma pessoa. Alimenta a seção My Attendance da página B1 Me
GET/treeJWT—Carregar a árvore completa de frequência (campus, serviços, horários de serviço, grupos)
GET/trend?campusId=&serviceId=&serviceTimeId=&groupId=JWTAttendance.View SummaryCarregar os dados de tendência de frequência com filtros opcionais
GET/groups?serviceId=&week=JWTAttendance.ViewCarregar a frequência dos grupos de um serviço em uma determinada semana
GET/sessionStatus?serviceTimeId=&date=JWTAttendance.ViewPara cada grupo atribuído ao horário de serviço, retorna { groupId, sessionId, attendanceCount } para aquela data (date no formato YYYY-MM-DD; sessionId é null quando o grupo não tem sessão). Alimenta o diálogo Who Still Needs Attendance do B1Admin
GET/search?campusId=&serviceId=&serviceTimeId=&groupId=&startDate=&endDate=JWTAttendance.ViewPesquisar registros de frequência com filtros (campus, serviço, horário de serviço, grupo, intervalo de datas)

Exemplo: Tendência de Frequência​

GET /attendance/attendancerecords/trend?serviceId=svc-001
Authorization: Bearer <token>
[
{ "week": "2025-01-05", "count": 142 },
{ "week": "2025-01-12", "count": 156 },
{ "week": "2025-01-19", "count": 138 }
]

Sessões​

Caminho base: /attendance/sessions

Estende GenericCrudController com as rotas CRUD getById e delete. Os endpoints getAll e save têm implementações personalizadas que também permitem que líderes de grupo gerenciem as sessões de seus grupos.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTAttendance.View ou Group LeaderListar todas as sessões. Filtre por ?groupId= (inclui os nomes). Líderes de grupo podem visualizar as sessões dos seus próprios grupos
GET/:idJWTAttendance.ViewObter uma sessão pelo ID
POST/JWTAttendance.Edit ou Group LeaderCriar ou atualizar sessões. Líderes de grupo podem salvar sessões dos seus próprios grupos
DELETE/:idJWTAttendance.EditExcluir uma sessão

Visitas​

Caminho base: /attendance/visits

Gerencia os registros individuais de visita (uma pessoa comparecendo em uma data específica) e fornece o fluxo de check-in.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTAttendance.ViewListar todas as visitas. Filtre por ?personId=
GET/:idJWTAttendance.ViewObter uma visita pelo ID
GET/checkin?serviceId=&peopleIds=JWTAttendance.View ou Attendance.CheckinCarregar os dados de check-in de pessoas em um serviço. Retorna as visitas com as sessões de visita da última data registrada
POST/JWTAttendance.EditCriar ou atualizar visitas
POST/checkin?serviceId=&peopleIds=JWTAttendance.Edit ou Attendance.CheckinEnviar os dados de check-in. Cria/atualiza visitas e sessões de visita e remove os registros obsoletos
DELETE/:idJWTAttendance.EditExcluir uma visita

Exemplo: Fluxo de Check-in​

Passo 1 -- Carregar os dados de check-in existentes:

GET /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>
[
{
"id": "visit-001",
"personId": "person-1",
"visitDate": "2025-01-19T00:00:00.000Z",
"visitSessions": [
{
"id": "vs-001",
"sessionId": "sess-001",
"visitId": "visit-001",
"session": {
"id": "sess-001",
"groupId": "group-001",
"serviceTimeId": "st-001",
"sessionDate": "2025-01-19T00:00:00.000Z"
}
}
]
}
]

Passo 2 -- Enviar o check-in:

POST /attendance/visits/checkin?serviceId=svc-001&peopleIds=person-1,person-2
Authorization: Bearer <token>

[
{
"personId": "person-1",
"visitSessions": [
{
"session": { "serviceTimeId": "st-001", "groupId": "group-001" }
}
]
}
]

Se um horário de serviço escolhido tiver uma programação de check-in e a janela estiver fechada (medida na mesma ordem de fuso horário, priorizando o campus, usada por checkinOpen), nada é salvo e a resposta é 409 { "error": "notOpen", "groups": [{ "groupId", "groupName", "reason": "notOpen" }] }. Violações de capacidade e de proporção de voluntários também retornam 409 (error: "capacity" ou "ratio"). As sessões que uma pessoa já possui hoje (reenviadas a cada check-in) ignoram a verificação da janela, de modo que uma família pode adicionar um horário de serviço aberto depois que a janela de um horário anterior já tiver fechado.

Sessões de Visita​

Caminho base: /attendance/visitsessions

Gerencia a associação entre visitas e sessões (em qual sessão específica uma pessoa compareceu durante uma visita). Também fornece um endpoint de registro rápido e um endpoint de download/exportação.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/JWTAttendance.View ou Group LeaderListar sessões de visita. Filtre por ?sessionId=. Líderes de grupo podem visualizar as sessões de visita dos seus próprios grupos
GET/:idJWTAttendance.ViewObter uma sessão de visita pelo ID
GET/download/:sessionIdJWTAttendance.ViewBaixar a frequência de uma sessão (retorna os nomes das pessoas com o status de presente/ausente)
POST/JWTAttendance.EditCriar ou atualizar sessões de visita
POST/logJWTAttendance.Edit ou Group LeaderRegistrar rapidamente a frequência de uma pessoa em uma sessão. Cria a visita automaticamente, se necessário. Líderes de grupo podem registrar a frequência dos seus próprios grupos
DELETE/:idJWTAttendance.EditExcluir uma sessão de visita pelo ID
DELETE/?personId=&sessionId=JWTAttendance.Edit ou Group LeaderRemover uma pessoa de uma sessão. Exclui a sessão de visita e a visita pai caso não restem sessões. Líderes de grupo podem remover a frequência dos seus próprios grupos

Exemplo: Registro Rápido de Frequência​

POST /attendance/visitsessions/log
Authorization: Bearer <token>

{
"personId": "person-001",
"visitSessions": [
{ "sessionId": "sess-001" }
]
}
{}

Exemplo: Baixar a Frequência de uma Sessão​

GET /attendance/visitsessions/download/sess-001
Authorization: Bearer <token>
[
{
"id": "vs-001",
"personId": "person-001",
"visitId": "visit-001",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "John Smith",
"status": "present"
},
{
"id": "",
"personId": "person-002",
"visitId": "",
"sessionDate": "2025-01-19T00:00:00.000Z",
"personName": "Jane Doe",
"status": "absent"
}
]

Sequências​

Caminho base: /attendance/streaks

Acompanha as sequências de frequência de cada pessoa -- semanas consecutivas em que ela compareceu. Útil para métricas de engajamento e gamificação.

MétodoCaminhoAutenticaçãoPermissãoDescrição
GET/person/:personIdJWT—Carregar as sequências de frequência de uma pessoa

Páginas Relacionadas​