Skip to main content

API Reference - Endpoints

Documentação completa de todos os endpoints da API de Gamificação.

🔐 Autenticação​

Todos os endpoints requerem autenticação via JWT token no header:

Authorization: Bearer <jwt_token>

🎯 Pontuação e Ações​

Adicionar Pontos​

Registra uma ação do técnico e calcula pontos automaticamente.

POST /api/v1/gamification/points
Content-Type: application/json
Authorization: Bearer <token>

{
    "usuario_id": "123e4567-e89b-12d3-a456-426614174000",
    "acao": "checkin_pontual",
    "chamado_id": "987fcdeb-51a2-43d4-b789-123456789012",
    "metadata": {
        "latitude": -8.0476,
        "longitude": -34.8770,
        "timestamp_checkin": "2025-08-06T14:30:00Z"
    }
}

Response (200 OK):

{
  "success": true,
  "data": {
    "pontos_adicionados": 19,
    "pontos_total": 1247,
    "nivel_atual": "Experiente",
    "subiu_nivel": false,
    "badges_conquistados": [],
    "posicao_ranking_local": 3,
    "posicao_ranking_nacional": 127,
    "multiplicadores": {
      "tier": 1.2,
      "densidade": 1.1,
      "nivel": 1.05
    }
  },
  "timestamp": "2025-08-06T14:30:01Z"
}

Histórico de Pontuações​

Consulta o histórico de pontuações do usuário.

GET /api/v1/gamification/points/history?usuario_id={id}&limit=50&offset=0&periodo=30d

Response:

{
  "success": true,
  "data": {
    "historico": [
      {
        "id": 12345,
        "acao": "checkin_pontual",
        "pontos_base": 10,
        "pontos_final": 19,
        "multiplicadores": {
          "tier": 1.2,
          "densidade": 1.1,
          "nivel": 1.05
        },
        "chamado_id": "987fcdeb-51a2-43d4-b789-123456789012",
        "cidade": "Recife",
        "data_acao": "2025-08-06T14:30:00Z"
      }
    ],
    "resumo": {
      "total_pontos_periodo": 850,
      "total_acoes": 42,
      "media_pontos_dia": 28.3,
      "acao_mais_frequente": "chamado_concluido"
    },
    "paginacao": {
      "limit": 50,
      "offset": 0,
      "total": 156,
      "has_next": true
    }
  }
}

🏆 Rankings​

Ranking Local​

Consulta ranking de uma cidade específica.

GET /api/v1/gamification/rankings/local?cidade=Recife&periodo=mensal&limit=10&offset=0

Response:

{
  "success": true,
  "data": {
    "ranking": [
      {
        "posicao": 1,
        "usuario_id": "user-123",
        "nome": "João TechPro",
        "pontos": 2134,
        "nivel": "Expert",
        "badges_count": 12,
        "variacao_posicao": 1,
        "avatar_url": "https://cdn.example.com/avatars/user-123.jpg"
      },
      {
        "posicao": 2,
        "usuario_id": "user-456",
        "nome": "Maria FixMaster",
        "pontos": 1987,
        "nivel": "Expert",
        "badges_count": 9,
        "variacao_posicao": -1,
        "avatar_url": null
      }
    ],
    "meta": {
      "cidade": "Recife",
      "periodo": "mensal",
      "total_tecnicos": 15,
      "periodo_inicio": "2025-08-01T00:00:00Z",
      "periodo_fim": "2025-08-31T23:59:59Z",
      "ultima_atualizacao": "2025-08-06T15:00:00Z"
    },
    "posicao_usuario": {
      "posicao": 3,
      "pontos": 1247,
      "distancia_proximo": 740
    }
  }
}

Ranking Nacional​

GET /api/v1/gamification/rankings/nacional?categoria=experiente&limit=100&offset=0

Rankings Especializados​

GET /api/v1/gamification/rankings/categoria/{categoria}

# Categorias disponíveis:
# - pontualidade (menor % atrasos)
# - qualidade (maior média estrelas)
# - velocidade (menor tempo médio)
# - atividade (mais chamados)
# - confiabilidade (menor cancelamento)

🎖️ Badges e Conquistas​

Badges do Usuário​

Lista todos os badges conquistados pelo usuário.

GET /api/v1/gamification/badges/user/{usuario_id}

Response:

{
    "success": true,
    "data": {
        "badges": [
            {
                "nome": "Sempre no Horário",
                "categoria": "pontualidade",
                "descricao":