# 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 $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