📱 API - Gerenciamento de Dispositivos Conectados

Sistema completo para gerenciar dispositivos conectados dos usuários

📌 Sobre o Sistema
Sistema para gerenciar dispositivos conectados dos usuários com registro automático no login, listagem, desconexão remota, personalização com apelidos e verificação de status de sessão.

Base URL: /api/v1/dispositivo

📌 Visão Geral

O sistema oferece as seguintes funcionalidades:

✅ Registro automático de dispositivos no login
✅ Listagem de dispositivos conectados
✅ Desconexão remota de dispositivos
✅ Personalização com apelidos (nicknames)
✅ Verificação de status de sessão

🔐 Autenticação

Todos os endpoints requerem JWT Bearer Token no header:

Header de Autenticação

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

📡 Endpoints

1️⃣ Login com Dispositivo

Faz login e registra automaticamente o dispositivo.

Método	Endpoint
POST	`/api/auth/login`

Headers:

Content-Type: application/json

Body (mínimo):

Request Body - Autenticação Básica

{
  "document": "12345678901"
}

Body (com dispositivo):

Request Body - Com Informações do Dispositivo

{
  "document": "12345678901",
  "deviceIdentifier": "iPhone-14-Pro-ABC123",
  "deviceType": "mobile",
  "operatingSystem": "iOS 17.5",
  "appVersion": "1.0.0",
  "location": "São Paulo, SP"
}

Campos:

Campo	Tipo	Obrigatório	Descrição
`document`	string	✅ Sim	CPF com 11 dígitos
`deviceIdentifier`	string	❌ Não	ID único do dispositivo
`deviceType`	string	❌ Não	Tipo: "mobile", "tablet", "web"
`operatingSystem`	string	❌ Não	Ex: "iOS 17.5", "Android 14"
`appVersion`	string	❌ Não	Versão do app: "1.2.3"
`location`	string	❌ Não	Ex: "São Paulo, SP"

Response (200):

Response JSON

{
  "success": true,
  "message": "Login realizado com sucesso",
  "usuario": {
    "codigo": 123,
    "nome": "João Silva",
    "documento": "12345678901"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

✅ O que acontece

Se deviceIdentifier for enviado, registra/atualiza o dispositivo automaticamente
Retorna token JWT para usar nos próximos endpoints

2️⃣ Registrar/Atualizar Dispositivo

Registra ou atualiza informações de um dispositivo.

Método	Endpoint
POST	`/api/v1/dispositivo/registrar`

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

Request Body

{
  "deviceIdentifier": "Samsung-Galaxy-S23-XYZ789",
  "nickname": "Celular do Trabalho",
  "deviceType": "mobile",
  "operatingSystem": "Android 14",
  "appVersion": "1.2.3",
  "location": "Rio de Janeiro, RJ"
}

Campos:

Campo	Tipo	Obrigatório	Descrição
`deviceIdentifier`	string	✅ Sim	ID único do dispositivo
`nickname`	string	❌ Não	Apelido (gerado se não informado)
`deviceType`	string	❌ Não	"mobile", "tablet", "web"
`operatingSystem`	string	❌ Não	Ex: "iOS 17", "Android 14"
`appVersion`	string	❌ Não	Ex: "1.2.3"
`location`	string	❌ Não	Ex: "São Paulo, SP"

Response (200):

Response JSON

{
  "message": "Dispositivo registrado com sucesso",
  "dispositivoId": 1
}

3️⃣ Listar Dispositivos

Lista todos os dispositivos do usuário autenticado.

Método	Endpoint
GET	`/api/v1/dispositivo`

Headers:

Authorization: Bearer {token}

Response (200):

Response JSON

[
  {
    "id": 1,
    "deviceIdentifier": "iPhone-14-Pro-ABC123",
    "nickname": "Meu iPhone",
    "deviceType": "mobile",
    "operatingSystem": "iOS 17.5",
    "appVersion": "1.2.3",
    "location": "São Paulo, SP",
    "isActive": true,
    "lastLogin": "2025-10-21T14:30:00Z",
    "createdAt": "2025-10-20T10:00:00Z"
  },
  {
    "id": 2,
    "deviceIdentifier": "Samsung-Galaxy-XYZ",
    "nickname": "Celular do Trabalho",
    "deviceType": "mobile",
    "operatingSystem": "Android 14",
    "appVersion": "1.2.3",
    "location": "Rio de Janeiro, RJ",
    "isActive": true,
    "lastLogin": "2025-10-21T12:15:00Z",
    "createdAt": "2025-10-19T08:00:00Z"
  }
]

4️⃣ Obter Dispositivo por ID

Obtém informações de um dispositivo específico.

Método	Endpoint
GET	`/api/v1/dispositivo/{id}`

Path Parameters:

Parâmetro	Tipo	Descrição
`id`	int	ID do dispositivo

Headers:

Authorization: Bearer {token}

Response (200):

Response JSON - Sucesso

{
  "id": 1,
  "deviceIdentifier": "iPhone-14-Pro-ABC123",
  "nickname": "Meu iPhone",
  "deviceType": "mobile",
  "operatingSystem": "iOS 17.5",
  "appVersion": "1.2.3",
  "location": "São Paulo, SP",
  "isActive": true,
  "lastLogin": "2025-10-21T14:30:00Z",
  "createdAt": "2025-10-20T10:00:00Z"
}

Response (404):

Response JSON - Não Encontrado

{
  "message": "Dispositivo não encontrado"
}

5️⃣ Atualizar Nickname

Atualiza o apelido de um dispositivo.

Método	Endpoint
PATCH	`/api/v1/dispositivo/{id}/nickname`

Path Parameters:

Parâmetro	Tipo	Descrição
`id`	int	ID do dispositivo

Headers:

Content-Type: application/json
Authorization: Bearer {token}

Body:

Request Body

{
  "nickname": "iPhone do Trabalho"
}

Campos:

Campo	Tipo	Obrigatório	Descrição
`nickname`	string	✅ Sim	Novo apelido (máx 100 caracteres)

Response (200):

Response JSON

{
  "message": "Nickname atualizado com sucesso"
}

6️⃣ Logout de Dispositivo

Desconecta um dispositivo específico.

Método	Endpoint
POST	`/api/v1/dispositivo/{id}/logout`

Path Parameters:

Parâmetro	Tipo	Descrição
`id`	int	ID do dispositivo

Headers:

Authorization: Bearer {token}

Response (200):

Response JSON

{
  "message": "Dispositivo desconectado com sucesso"
}

✅ O que acontece

Marca isActive = false
Dispositivo continua aparecendo na lista, mas inativo

7️⃣ Logout de Todos os Dispositivos

Desconecta todos os dispositivos do usuário.

Método	Endpoint
POST	`/api/v1/dispositivo/logout-all`

Headers:

Authorization: Bearer {token}

Response (200):

Response JSON

{
  "message": "Todos os dispositivos foram desconectados"
}

8️⃣ Logout de Todos Exceto Um

Desconecta todos os dispositivos, exceto o especificado.

Método	Endpoint
POST	`/api/v1/dispositivo/logout-all?exceptDeviceId={id}`

Query Parameters:

Parâmetro	Tipo	Obrigatório	Descrição
`exceptDeviceId`	int	❌ Não	ID do dispositivo que permanece conectado

Headers:

Authorization: Bearer {token}

Exemplo:

Exemplo de Request

POST /api/v1/dispositivo/logout-all?exceptDeviceId=5

Response (200):

Response JSON

{
  "message": "Todos os dispositivos foram desconectados"
}

✅ O que acontece

Desconecta todos exceto o exceptDeviceId
Se não informar exceptDeviceId, desconecta todos
Útil para manter apenas o dispositivo atual

9️⃣ Verificar Status de Sessão

Verifica se um dispositivo está ativo.

Método	Endpoint
GET	`/api/v1/dispositivo/{id}/status`

Path Parameters:

Parâmetro	Tipo	Descrição
`id`	int	ID do dispositivo

Headers:

Authorization: Bearer {token}

Response - Ativo (200):

Response JSON - Sessão Ativa

{
  "dispositivoId": 1,
  "isActive": true,
  "message": "Sessão ativa"
}

Response - Inativo (200):

Response JSON - Sessão Inativa

{
  "dispositivoId": 1,
  "isActive": false,
  "message": "Sessão inativa"
}

⚠️ Códigos HTTP

Código	Significado	Quando Ocorre
200	Sucesso	Operação realizada com sucesso
400	Bad Request	Dados inválidos no body
401	Unauthorized	Token ausente ou inválido
404	Not Found	Dispositivo não encontrado
500	Server Error	Erro interno

🎯 Fluxos Práticos

Fluxo 1: Login Automático

App envia POST /api/auth/login com deviceIdentifier
API registra/atualiza dispositivo automaticamente
API retorna token JWT
App usa token para próximas chamadas

Fluxo 2: Ver Dispositivos

App chama GET /api/v1/dispositivo
API retorna lista de dispositivos
App mostra na tela

Fluxo 3: Desconectar Outro Dispositivo

Usuário vê lista e escolhe dispositivo
App chama POST /api/v1/dispositivo/{id}/logout
Dispositivo fica inativo

Fluxo 4: Desconectar Todos (Segurança)

Usuário suspeita de invasão
App chama POST /api/v1/dispositivo/logout-all?exceptDeviceId=5
Todos desconectam exceto o atual

📝 Resumo de Campos Obrigatórios

Login

✅ document (obrigatório)
❌ deviceIdentifier (opcional)
❌ deviceType (opcional)
❌ operatingSystem (opcional)
❌ appVersion (opcional)
❌ location (opcional)

Registrar Dispositivo

✅ deviceIdentifier (obrigatório)
❌ nickname (opcional - gerado automaticamente)
❌ deviceType (opcional)
❌ operatingSystem (opcional)
❌ appVersion (opcional)
❌ location (opcional)

Atualizar Nickname

✅ nickname (obrigatório)

Outros Endpoints

Não requerem body, apenas token JWT