Verifies connectivity to a registered ZKTeco device by establishing a connection and retrieving the device’s current time. This is useful for troubleshooting network connectivity and validating device configuration.
Path Parameters
The unique identifier of the device to pingExample: "principal" or "bodega"
Response
Indicates whether the connection test was successful
Status message (present on success)
Current time reported by the device (present on success)
IP address of the device that was tested
Error message describing the connection failure (present on error)
Example Request
curl -X GET https://your-server.com/devices/principal/ping
Example Response
Success (200)
{
"success": true,
"message": "Conexion exitosa con 'principal'.",
"device_time": "2026-03-06 15:30:45",
"ip": "192.168.1.205"
}
Error: Connection Failed (503)
{
"success": false,
"error": "[Errno 111] Connection refused",
"ip": "192.168.1.205"
}
Error: Timeout (503)
{
"success": false,
"error": "timeout: timed out",
"ip": "192.168.1.207"
}
Error: Device Not Found (404)
{
"success": false,
"error": "Dispositivo 'nonexistent' no encontrado.",
"disponibles": ["principal", "bodega"]
}
Error Codes
| Status Code | Description |
|---|
| 200 | Connection successful |
| 404 | Device with the specified ID does not exist |
| 503 | Service unavailable (device unreachable or connection failed) |
Common Connection Errors
| Error Message | Cause | Solution |
|---|
Connection refused | Device is offline or wrong port | Verify device power and network; check port configuration |
timed out | Network issue or incorrect IP | Check network connectivity; verify IP address |
No route to host | Network routing problem | Check network configuration and firewall rules |
Invalid password | Wrong communication password | Update device configuration with correct password |
What This Endpoint Tests
- Network connectivity to the device IP
- TCP connection on the configured port
- Protocol compatibility with the ZK library
- Authentication using the stored password
- Basic device responsiveness by retrieving the current time
Use Cases
- Initial setup: Verify device configuration after registration
- Troubleshooting: Diagnose connectivity issues
- Health monitoring: Periodic checks to ensure devices are online
- Pre-operation validation: Test connection before performing bulk operations
Notes
- The connection is automatically closed after the test
- This endpoint uses a thread lock to prevent concurrent operations on the same device
- The device’s clock is read but not modified
- Minimal performance impact on the device (single command operation)