How to test a ZKTeco terminal without buying hardware: virtual sandbox step by step

The real cost of "testing with a real device"

If you build payroll SaaS, a condo management system or an HR platform, at some point a customer will ask: "can you read our ZKTeco terminals?". The traditional path looks like this:

• Buying a test terminal: between $250 and $900 USD depending on the model.
• Import logistics in Latin America: weeks of waiting and variable duties.
• Setting up a local server or a VPN just for the first tests.
• Dedicating team time before knowing whether the feature is worth it.

In other words: hundreds of dollars and weeks of friction before the first line of integration. For a product team, that usually means the feature never leaves the backlog.

What you can validate without touching hardware

The API Connect sandbox creates up to 2 virtual terminals with the same capabilities as a physical terminal connected to the cloud:

• Terminal registration with serial number, model and expiration date.
• Real-time access events: granted punches, denied punches and sync heartbeats.
• Attendance reports queryable by date range, with pagination.
• Users and credentials: enroll people with PIN, card and access groups.
• Device expiration: test how your logic behaves when a terminal expires.

Step by step: from zero to your first event

1. Create your account (14 days free, no card)

Registration takes less than a minute. Once in the dashboard you get access to the sandbox, the API and the reports for the whole trial.

2. Create your first virtual terminal

From the dashboard sandbox, create a virtual terminal. You'll get its simulated serial number, which is the key to everything else.

3. Simulate punches from the browser

The simulation screen lets you interact with the virtual terminal: record check-in and check-out punches, and generate access events. Each event lands in your history as if it came from a physical device.

4. Authenticate your software against the API

Your backend authenticates with your account credentials and receives a token to call the REST API:

curl -X POST https://YOUR-API-DOMAIN/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your_user", "password": "your_password"}'

# Response
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

5. Query the generated punches

With the token, request the virtual terminal's report for any date range:

curl -X GET "https://YOUR-API-DOMAIN/report/YOUR-SERIAL?from=2026-09-01&to=2026-09-14&page=1&per_page=500" \
  -H "Authorization: Bearer {token}"

The response comes as JSON ready to map to your models: punch, person, verification method and exact timestamp. If your software already imports CSVs from time clocks, this step is the difference between a weekly manual process and live data.

6. (Optional) Consume the events as a stream

If your architecture prefers reacting to events instead of polling, you can subscribe to the terminal's events and process them as they happen:

import { createClient } from 'redis';

const sub = createClient({
  socket: { host: process.env.REDIS_HOST, port: Number(process.env.REDIS_PORT) },
  password: process.env.REDIS_PASSWORD
});

await sub.connect();

await sub.subscribe('punch_YOUR-SERIAL', (message) => {
  const event = JSON.parse(message);
  console.log('new punch:', event.pin, event.timestamp);
  // fire your business logic here
});

When to go to production

The day the feature gets approved, the transition is the easy part: the customer's physical terminals are registered and pointed to the cloud, and your software keeps calling the same URLs. There's no "rewrite phase" because sandbox and production share the same API.

The value for your product, in one sentence

You can answer "yes, we read your ZKTeco terminals" in a demo with real data the same day the sales opportunity appears — without buying anything, without waiting for imports and without building infrastructure.

Frequently asked questions