Listar Grupos

Retorna uma lista de grupos eclesiásticos do sistema

Este endpoint é do tipo: Protected

Descrição

Retorna uma lista dos 6 grupos eclesiásticos fixos do sistema com as seguintes funcionalidades:

Lista todos os 6 grupos eclesiásticos pré-definidos
Inclui contadores de usuários e questionários por grupo
Inclui métricas de conclusão: respostas recebidas/esperadas, percentual e status
Retorna as iniciais do grupo (G1..G6) e dos últimos 5 informadores
Retorna a referência ao processo relacionado (id, name, protocol)
Filtro por processo específico (process_id)
Filtros por busca em nome e descrição
Paginação configurável (padrão: 12 itens por página)
Ordenação por nome (Grupo 1, 2, 3, etc.)
Retorna descrição, cor e URL da imagem de cada grupo
Nota: Os grupos são fixos e não podem ser criados ou excluídos
Requer autenticação JWT válida
Colaborador sem vínculo ao processo (via process_id ou group_id resolvido): HTTP 403

Detalhes do Endpoint

VERBO

GET

URL BASE

https://api.provisao.dev.nabrasil.org.br/v1

ENDPOINT

/groups

Parâmetros de Query

Parâmetro	Tipo	Obrigatório	Descrição
process_id	string (UUID)	Não	Filtrar grupos por ID do processo
search	string	Não	Buscar por nome ou descrição do grupo
per_page	integer	Não	Número de itens por página (padrão: 12)
page	integer	Não	Número da página (padrão: 1)

Cabeçalhos

Parâmetro	Valor
Authorization	Bearer <token>
Accept	application/json

Respostas

Sucesso - 200

{
  "success": true,
  "data": [
    {
      "id": "a022d1ee-3003-4afe-8686-d7aeb5b051c9",
      "initials": "G1",
      "name": "Grupo 1",
      "description": "Bispo em saída/transferido",
      "color": "bg-primary",
      "users_count": 5,
      "answers_received": 12,
      "answers_expected": 15,
      "completion_label": "12/15",
      "completion_percent": 80,
      "status": "Em andamento",
      "recent_informers": [
        {"initials": "JB", "blacklisted": false, "avatar_color": "#26BF94"},
        {"initials": "DC", "blacklisted": false, "avatar_color": "#26BF94"},
        {"initials": "FA", "blacklisted": false, "avatar_color": "#26BF94"},
        {"initials": "RL", "blacklisted": false, "avatar_color": "#26BF94"},
        {"initials": "TM", "blacklisted": true,  "avatar_color": "#000000"}
      ],
      "has_more_users": true,
      "plus_badge_color": "#845ADF",
      "process": {"id": "uuid-processo", "name": "Diocese de São Paulo", "protocol": "PROV-2025-001"}
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 12,
    "total": 6,
    "last_page": 1,
    "from": 1,
    "to": 6,
    "has_more_pages": false
  }
}

Nota: Este endpoint retorna os grupos eclesiásticos do sistema com paginação. Os contadores users_count e questionnaires_count mostram quantos usuários e questionários estão associados a cada grupo. Os grupos são retornados ordenados por nome (Grupo 1, 2, 3, etc.).

Erro - 401 (Token inválido)

{
  "success": false,
  "message": "Token não fornecido"
}

Condição: Token JWT inválido, expirado ou não fornecido

Erro - 403 (Sem permissão no processo)

{
  "success": false,
  "message": "Acesso negado. Você não tem permissão para acompanhar este processo.",
  "errors": []
}

Condição: Usuário colaborador sem vínculo em process_colaborador para o processo informado (ou resolvido via grupo)

Códigos de Resposta

Código	Descrição
200	Lista de grupos retornada com sucesso
401	Token inválido ou expirado
403	Colaborador sem permissão de acompanhamento no processo

Nunciatura Provista