API Documentation

TRXA Device Sync API Reference & Code Examples

API Endpoints

GET /api/pending.php?SN={serial_number}

Retrieve pending commands for a specific device. Note: Commands are automatically marked as "sent" upon fetching. No separate acknowledgment request is required.

Parameter	Type	Required	Description
`SN`	String	Yes	Device Serial Number (e.g., AIOR123456)

Success Response (JSON):

{
  "commands": [
    // 1. Add or Edit User Command
    {
      "id": "15",
      "type": "user_add",
      "user_id": "EMP001",
      "name": "John Doe",
      "card": "123456",
      "serial_number": "AIOR123456"
    },
    // 2. Fingerprint Enroll Command
    {
      "id": "16",
      "type": "finger_enroll",
      "user_id": "EMP001",
      "finger_id": 0, // Range: 0-9
      "serial_number": "AIOR123456"
    },
    // 3. Face Enroll Command
    {
      "id": "17",
      "type": "face_enroll",
      "user_id": "EMP001",
      "serial_number": "AIOR123456"
    },
    // 4. Delete User Command
    {
      "id": "18",
      "type": "user_delete",
      "user_id": "EMP002",
      "serial_number": "AIOR123456"
    }
  ]
}

POST /api/receive_log.php

Receive real-time attendance punch logs. Expects a JSON payload in the request body.

Parameter	Type	Required	Description
`logs`	Array	Yes	Array of attendance log objects
↳ `serial_number`	String	Yes	Device Serial Number
↳ `employee_id`	String	Yes	ID of the employee
↳ `timestamp`	String	Yes	Punch time (Format: YYYY-MM-DD HH:MM:SS)

Example Request Body (JSON):

{
  "logs": [
    {
      "serial_number": "AIOR123456",
      "employee_id": "EMP001",
      "timestamp": "2024-01-15 09:30:00"
    }
  ]
}

Success Response:

allok

Attendance Log Format

Logs are sent as a POST request to your configured API URL with the following JSON body:

{
  "logs": [
    {
      "employee_id": "EMP001",
      "timestamp": "2024-01-15 09:30:00",
      "serial_number": "ABC123456"
    },
    {
      "employee_id": "EMP002",
      "timestamp": "2024-01-15 09:32:00",
      "serial_number": "ABC123456"
    }
  ]
}

Logs are sent in batches of up to 20 at a time. After successfully saving, respond with allok.

Example Code / Device Simulator

Use these ready-made scripts to test the API endpoints or build your own ZKTeco device simulator.

<?php
// ZKTeco Device API Simulator - PHP
$baseUrl = "https://trxa.top/api";
$serialNumber = "AIOR123456"; // Change to your device SN

echo "=== TRXA API Test (PHP) ===\n\n";

// 1. Fetching Pending Commands (GET)
echo "[1] Fetching pending commands...\n";
$pendingUrl = $baseUrl . "/pending.php?SN=" . urlencode($serialNumber);

$response = file_get_contents($pendingUrl);
if ($response !== false) {
    $commandsData = json_decode($response, true);
    print_r($commandsData);
} else {
    echo "Failed to fetch commands.\n";
}

echo "\n----------------------------------------\n\n";

// 2. Sending Attendance Log (POST)
echo "[2] Sending dummy attendance log...\n";
$logUrl = $baseUrl . "/receive_log.php";

$logData = [
    "logs" => [
        [
            "serial_number" => $serialNumber,
            "employee_id" => "EMP001",
            "timestamp" => date("Y-m-d H:i:s")
        ]
    ]
];

$options = [
    'http' => [
        'header'  => "Content-Type: application/json\r\n",
        'method'  => 'POST',
        'content' => json_encode($logData),
    ]
];
$context = stream_context_create($options);
$logResponse = file_get_contents($logUrl, false, $context);

echo "Server Response: " . $logResponse . "\n";
?>

// ZKTeco Device API Simulator - Node.js (v18+)
const baseUrl = "https://trxa.top/api";
const serialNumber = "AIOR123456"; // Change to your device SN

async function runApiTest() {
    console.log("=== TRXA API Test (Node.js) ===\n");

    try {
        // 1. Fetching Pending Commands (GET)
        console.log("[1] Fetching pending commands...");
        const pendingRes = await fetch(`${baseUrl}/pending.php?SN=${serialNumber}`);
        
        if (pendingRes.ok) {
            const commandsData = await pendingRes.json();
            console.dir(commandsData, { depth: null, colors: true });
        }

        console.log("\n----------------------------------------\n");

        // 2. Sending Attendance Log (POST)
        console.log("[2] Sending dummy attendance log...");
        
        const now = new Date();
        const timestamp = now.toISOString().replace('T', ' ').substring(0, 19);

        const logData = {
            logs: [
                {
                    serial_number: serialNumber,
                    employee_id: "EMP001",
                    timestamp: timestamp
                }
            ]
        };

        const logRes = await fetch(`${baseUrl}/receive_log.php`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(logData)
        });

        const logResult = await logRes.text();
        console.log("Server Response:", logResult);

    } catch (error) {
        console.error("Error:", error.message);
    }
}

runApiTest();

Integration Notes

Auto-Acknowledgment: The /api/pending.php endpoint automatically marks all fetched commands as status = 'sent'. There is no need to make a secondary POST request to acknowledge them.

UID Management: The TRXA backend completely handles uid mapping internally. Sync clients only need to process the user_id (String).

Attendance Log Response: Your /api/receive_log.php endpoint must respond with allok after successfully receiving logs. Any other response will cause the system to treat the batch as failed and retry sending.