# Guia de Integração - API de Captura de MACs

## Visão Geral

A API de captura de MACs permite que dispositivos (TVs, set-top boxes, etc.) se registrem automaticamente no painel administrativo. Os MACs capturados aparecem em `Gerenciamento > MACs Capturados` para ativação manual.

---

## Endpoint Principal

**URL**: `http://seu-painel.com/mac_auto.php`

**Métodos Suportados**: 
- `POST` - Registrar novo MAC
- `GET` - Listar MACs capturados
- `OPTIONS` - Preflight CORS

---

## 1. Registrar um MAC (POST)

### Requisição

```bash
curl -X POST http://seu-painel.com/mac_auto.php \
  -H "Content-Type: application/json" \
  -d '{
    "mac": "AA:BB:CC:DD:EE:FF",
    "deviceName": "TV Samsung 55\"",
    "devID": "device_12345",
    "ip": "192.168.1.100"
  }'
```

### Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `mac` | string | ✅ Sim | Endereço MAC do dispositivo (formato: XX:XX:XX:XX:XX:XX) |
| `deviceName` | string | ❌ Não | Nome/descrição do dispositivo |
| `devID` | string | ❌ Não | ID único do dispositivo |
| `ip` | string | ❌ Não | Endereço IP do dispositivo (capturado automaticamente se não enviado) |

### Resposta de Sucesso (200)

```json
{
  "success": true,
  "status": "ok",
  "message": "MAC registered successfully",
  "mac": "AA:BB:CC:DD:EE:FF",
  "timestamp": "2026-06-08 14:30:45"
}
```

### Resposta de Erro (400)

```json
{
  "error": "MAC address is required"
}
```

### Resposta de Erro (500)

```json
{
  "error": "Failed to save MAC"
}
```

---

## 2. Listar MACs Capturados (GET)

### Requisição

```bash
curl http://seu-painel.com/mac_auto.php
```

### Resposta de Sucesso

```json
{
  "success": true,
  "total": 3,
  "data": [
    {
      "mac": "AA:BB:CC:DD:EE:FF",
      "deviceName": "TV Samsung",
      "devID": "device_12345",
      "ip": "192.168.1.100",
      "timestamp": "2026-06-08 14:30:45"
    },
    {
      "mac": "11:22:33:44:55:66",
      "deviceName": "Set-top Box",
      "devID": "device_67890",
      "ip": "192.168.1.101",
      "timestamp": "2026-06-08 14:25:30"
    }
  ]
}
```

---

## 3. Exemplos de Integração

### JavaScript/Fetch API

```javascript
async function registerMAC(mac, deviceName) {
  try {
    const response = await fetch('http://seu-painel.com/mac_auto.php', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        mac: mac,
        deviceName: deviceName,
        devID: 'my_device_id',
        ip: '192.168.1.100'
      })
    });

    const data = await response.json();
    
    if (data.success) {
      console.log('MAC registrado com sucesso:', data.mac);
    } else {
      console.error('Erro:', data.error);
    }
  } catch (error) {
    console.error('Erro na requisição:', error);
  }
}

// Uso
registerMAC('AA:BB:CC:DD:EE:FF', 'Minha TV');
```

### Python

```python
import requests
import json

def register_mac(mac, device_name):
    url = 'http://seu-painel.com/mac_auto.php'
    
    payload = {
        'mac': mac,
        'deviceName': device_name,
        'devID': 'my_device_id',
        'ip': '192.168.1.100'
    }
    
    headers = {
        'Content-Type': 'application/json'
    }
    
    try:
        response = requests.post(url, json=payload, headers=headers)
        data = response.json()
        
        if data.get('success'):
            print(f"MAC registrado: {data['mac']}")
        else:
            print(f"Erro: {data.get('error')}")
    except Exception as e:
        print(f"Erro na requisição: {e}")

# Uso
register_mac('AA:BB:CC:DD:EE:FF', 'Minha TV')
```

### PHP

```php
<?php
$mac = 'AA:BB:CC:DD:EE:FF';
$deviceName = 'Minha TV';

$data = [
    'mac' => $mac,
    'deviceName' => $deviceName,
    'devID' => 'my_device_id',
    'ip' => $_SERVER['REMOTE_ADDR']
];

$options = [
    'http' => [
        'method' => 'POST',
        'header' => 'Content-Type: application/json',
        'content' => json_encode($data)
    ]
];

$context = stream_context_create($options);
$response = file_get_contents('http://seu-painel.com/mac_auto.php', false, $context);
$result = json_decode($response, true);

if ($result['success']) {
    echo "MAC registrado: " . $result['mac'];
} else {
    echo "Erro: " . $result['error'];
}
?>
```

### cURL (Bash)

```bash
#!/bin/bash

MAC="AA:BB:CC:DD:EE:FF"
DEVICE_NAME="Minha TV"
ENDPOINT="http://seu-painel.com/mac_auto.php"

curl -X POST "$ENDPOINT" \
  -H "Content-Type: application/json" \
  -d "{
    \"mac\": \"$MAC\",
    \"deviceName\": \"$DEVICE_NAME\",
    \"devID\": \"my_device_id\",
    \"ip\": \"192.168.1.100\"
  }"
```

---

## 4. Fluxo de Ativação

```
┌─────────────────────────────────────────────────────────┐
│ 1. Dispositivo se conecta e envia MAC via API           │
│    POST /mac_auto.php                                   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 2. MAC aparece em "Gerenciamento > MACs Capturados"     │
│    Status: Pendente                                     │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 3. Administrador clica em "Ativar"                      │
│    Vai para users_create.php?mac=AA:BB:CC:DD:EE:FF      │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 4. Preenche dados do cliente e salva                    │
│    INSERT INTO ibo (mac_address, ...)                   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│ 5. MAC agora aparece em "Dashboard > Lista de Clientes" │
│    Status: Ativado                                      │
└─────────────────────────────────────────────────────────┘
```

---

## 5. Códigos de Status HTTP

| Código | Significado | Ação |
|--------|-------------|------|
| 200 | Sucesso | MAC registrado ou listado com sucesso |
| 400 | Requisição Inválida | MAC não fornecido ou dados inválidos |
| 405 | Método Não Permitido | Método HTTP não suportado (use POST ou GET) |
| 500 | Erro do Servidor | Falha ao salvar arquivo JSON |

---

## 6. Limites e Restrições

- **Máximo de MACs**: 500 registros (os mais antigos são removidos)
- **Tamanho máximo de campo**: 255 caracteres
- **Formato de MAC**: Aceita XX:XX:XX:XX:XX:XX ou XXXXXXXXXXXX (sem separadores)
- **Timeout**: Recomenda-se timeout de 10 segundos

---

## 7. Troubleshooting

### Erro: "MAC address is required"
- Verifique se o parâmetro `mac` foi enviado
- Valide o formato do MAC

### Erro: "Failed to save MAC"
- Verifique permissões da pasta `a/rtx/`
- Certifique-se que o servidor tem permissão de escrita
- Verifique espaço em disco disponível

### MACs não aparecem no painel
- Acesse `devices.php` para verificar
- Verifique se o arquivo `a/rtx/request.json` existe
- Limpe o cache do navegador

### CORS Error no navegador
- A API suporta CORS automaticamente
- Verifique se está usando `Content-Type: application/json`

---

## 8. Segurança

### Recomendações

1. **Autenticação**: Considere adicionar token de autenticação
2. **Rate Limiting**: Implemente limite de requisições por IP
3. **Validação**: Sempre valide formato de MAC
4. **HTTPS**: Use HTTPS em produção
5. **Firewall**: Restrinja acesso à API por IP se possível

### Exemplo com Token (Recomendado)

```javascript
// Cliente
fetch('http://seu-painel.com/mac_auto.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer seu_token_aqui'
  },
  body: JSON.stringify({...})
});

// Servidor (mac_auto.php)
if (!isset($_SERVER['HTTP_AUTHORIZATION']) || 
    $_SERVER['HTTP_AUTHORIZATION'] !== 'Bearer seu_token_aqui') {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}
```

---

## 9. Suporte

Para problemas ou dúvidas:
1. Verifique os logs em `error_log` e `api/error_log`
2. Acesse `devices.php` e verifique a seção "Integração da API"
3. Teste a API manualmente com cURL

---

**Última Atualização**: 08 de Junho de 2026  
**Versão da API**: 2.0
