# API Quick Reference Card

Quick reference for all enhanced device APIs.

## Base URL
```
http://your-domain.com/api/
```

## Authentication (Optional)
```
X-API-KEY: your-secret-key
```

---

## 1. IsConnectEnhanced.php
**Heartbeat & Health Check**

```bash
# Request
POST /api/IsConnectEnhanced.php
{
  "SN": "DEVICE001",
  "FirmwareVersion": "1.2.3",
  "DeviceInfo": "Additional info"
}

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "ServerStatus": "online",
  "Status": 1,
  "DeviceStatus": "registered",
  "Message": "Heartbeat recorded"
}
```

---

## 2. ConfigSync.php
**Configuration Synchronization**

```bash
# Request
POST /api/ConfigSync.php
{
  "SN": "DEVICE001",
  "CurrentVersion": "1.0.0"
}

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "ConfigVersion": "1.0.0",
  "RequireSync": false,
  "Message": "Configuration up to date"
}
```

---

## 3. QueryCommands.php
**Get Pending Commands**

```bash
# Request
POST /api/QueryCommands.php
{
  "SN": "DEVICE001",
  "MaxCommands": 5
}

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "PendingCommands": 2,
  "Commands": [
    {
      "CmdID": 123,
      "CmdCode": 1,
      "CmdName": "Reboot",
      "CmdParams": {}
    }
  ]
}
```

---

## 4. CommandResponse.php
**Submit Command Result**

```bash
# Request
POST /api/CommandResponse.php
{
  "SN": "DEVICE001",
  "CmdID": 123,
  "Status": 1,
  "Response": "Command executed successfully"
}

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "Message": "Command response recorded"
}
```

---

## 5. UpdateStatistics.php
**Report Device Statistics**

```bash
# Request
POST /api/UpdateStatistics.php
{
  "SN": "DEVICE001",
  "Date": "2024-02-24",
  "TotalScans": 150,
  "SuccessfulScans": 145,
  "FailedScans": 5,
  "UptimeMinutes": 1440
}

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "Message": "Statistics recorded"
}
```

---

## 6. DeviceStatistics.php
**Get Device Statistics**

```bash
# Request (GET or POST)
GET /api/DeviceStatistics.php?SN=DEVICE001

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "DeviceInfo": {
    "DeviceID": "DEVICE001",
    "ConnectionStatus": "online"
  },
  "Statistics": {
    "Summary": {
      "TotalScans": 1500,
      "SuccessfulScans": 1450
    }
  }
}
```

---

## 7. DeviceStatus.php
**Get Real-time Status**

```bash
# Request (GET or POST)
GET /api/DeviceStatus.php?SN=DEVICE001

# Response
{
  "DateTime": "2024-02-24 10:30:00",
  "Status": 1,
  "Device": {
    "DeviceID": "DEVICE001",
    "ConnectionStatus": "online",
    "LastHeartbeat": "2024-02-24 10:29:00",
    "IsOnline": true
  }
}
```

---

## Admin Utilities

### Get Help
```bash
GET /api/admin_utilities.php?action=help
```

### List All Devices
```bash
GET /api/admin_utilities.php?action=list_devices
```

### Device Summary
```bash
GET /api/admin_utilities.php?action=device_summary
```

### Create Command
```bash
POST /api/admin_utilities.php?action=create_command
{
  "SN": "DEVICE001",
  "CmdCode": 1,
  "CmdName": "Reboot",
  "Params": {},
  "Priority": 0
}
```

### Mark Offline Devices
```bash
GET /api/admin_utilities.php?action=mark_offline
```

### Clear Old Logs
```bash
GET /api/admin_utilities.php?action=clear_old_logs&days=30
```

---

## Common Response Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 429 | Too Many Requests |
| 500 | Server Error |

---

## Status Codes

| Status | Meaning |
|--------|---------|
| 1 | Success |
| 0 | Error/Failed |

---

## Connection Status

| Status | Description |
|--------|-------------|
| online | Device is connected |
| offline | Device is disconnected |
| unknown | Status not determined |

---

## Command Codes (Examples)

| Code | Command |
|------|---------|
| 0 | No operation |
| 1 | Reboot device |
| 2 | Update configuration |
| 3 | Clear cache |
| 4 | Sync time |
| 5 | Factory reset |

---

## Testing Commands

### cURL Examples

```bash
# Test heartbeat
curl -X POST http://localhost/api/IsConnectEnhanced.php \
  -H "Content-Type: application/json" \
  -d '{"SN":"TEST001"}'

# Test with authentication
curl -X POST http://localhost/api/IsConnectEnhanced.php \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-secret-key" \
  -d '{"SN":"TEST001"}'

# Get device status
curl -X GET "http://localhost/api/DeviceStatus.php?SN=TEST001"

# Get all devices
curl -X GET "http://localhost/api/DeviceStatus.php"
```

### PHP Examples

```php
// Send heartbeat
$data = [
    'SN' => 'DEVICE001',
    'FirmwareVersion' => '1.0.0'
];

$ch = curl_init('http://localhost/api/IsConnectEnhanced.php');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

### JavaScript Examples

```javascript
// Send heartbeat
fetch('http://localhost/api/IsConnectEnhanced.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    SN: 'DEVICE001',
    FirmwareVersion: '1.0.0'
  })
})
.then(response => response.json())
.then(data => console.log(data));

// Get device status
fetch('http://localhost/api/DeviceStatus.php?SN=DEVICE001')
  .then(response => response.json())
  .then(data => console.log(data));
```

---

## Database Tables

| Table | Purpose |
|-------|---------|
| device_heartbeats | Track device connectivity |
| device_commands | Command queue |
| device_configurations | Config versions |
| device_statistics | Daily statistics |
| api_request_logs | API call logs |
| server_configuration | Server settings |

---

## Useful SQL Queries

```sql
-- Check online devices
SELECT device_id, last_heartbeat 
FROM device_heartbeats 
WHERE connection_status = 'online';

-- Get today's statistics
SELECT * FROM device_statistics 
WHERE stat_date = CURDATE();

-- Check pending commands
SELECT * FROM device_commands 
WHERE status = 'pending' 
ORDER BY priority DESC;

-- Recent API calls
SELECT endpoint, COUNT(*) as calls 
FROM api_request_logs 
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 1 HOUR)
GROUP BY endpoint;
```

---

## Troubleshooting

### Device Not Responding
1. Check `device_heartbeats` table
2. Verify `last_heartbeat` timestamp
3. Check `connection_status`

### Commands Not Executing
1. Check `device_commands` table
2. Verify `status` field
3. Check device is calling `QueryCommands.php`

### Statistics Not Updating
1. Verify device is calling `UpdateStatistics.php`
2. Check `device_statistics` table
3. Verify date format

---

## Dashboard Access

```
http://your-domain.com/api/dashboard.html
```

---

## Support

- Check logs: `api_request_logs` table
- Review errors: Web server error logs
- Test connectivity: Use `test_all_apis.php`

---

## Version

API Version: 1.0.0
Last Updated: 2024-02-24