// Enterprise RESTful APIs

ZKTeco API Integration

For systems architects bridging biometric data with enterprise platforms like SAP, Odoo, ERPNext, or custom workforce management tools, communicating directly with edge hardware is considered an architectural anti-pattern. The modern standard is to leverage the RESTful APIs exposed by the ZKBio Time or ZKBio CVSecurity middleware platforms.

These APIs abstract the complexity of terminal desynchronization, template formatting, offline queuing, and raw HTTP parsing — wrapping operations in standard JSON responses and stateless authentication mechanics.

Authentication Mechanics

The ZKBio Time API utilizes a modern token-based authentication mechanism with two primary avenues: General Auth Tokens and JSON Web Tokens (JWT). To initiate a secure session, the consuming application must dispatch an HTTP POST request to the authentication endpoint.

POST /api-token-auth/

{
  "username": "admin",
  "password": "securepassword123"
}

Token Header Formats

General Tokens: Authorization: Token <token_string>
JWT: Authorization: JWT <token_string>

ZKBio Time API

The ZKBio Time software operates as a centralized hub connecting to standalone push-communication devices via Ethernet, Wi-Fi, or cellular networks. The API is segmented into functional resource blocks governing personnel administration, organizational hierarchy, and transactional records.

Category	Method	Endpoint	Key Parameters
Employees	GET / POST / PUT	/personnel/api/employees/	emp_code, department, page, page_size, first_name
Employee Resignation	POST	/personnel/api/employees/adjust_regsin/	employees (list), resign_type, disableatt (bool)
Biometric Templates	POST	/personnel/api/employees/del_bio_template/	finger_print (bool), face (bool), palm (bool)
Device Management	GET / POST	/iclock/api/terminals/	sn, alias, state, ip_address
Hardware Commands	POST	/iclock/api/terminals/reboot/	terminals (list)
Transactions	GET	/iclock/api/transactions/	start_time, end_time, emp_code, terminal_sn
Data Export	GET	/iclock/api/transactions/export/	export_type (csv, txt, xls)

Employees

Retrieve, create, or update core personnel records and assign them to departments.

Employee Resignation

Process HR offboarding, effectively disabling attendance tracking and revoking access.

Biometric Templates

Remotely command the middleware to purge localized biometric data from edge terminals.

Device Management

Provision new hardware, configure timezones, and monitor the health and activity state of edge terminals.

Hardware Commands

Execute remote shell commands (e.g., reboot, clear capture data, upload transactions) on specific devices.

Transactions

Fetch raw attendance logs. Responses include punch state, verification type, and GPS location data.

Data Export

Trigger the middleware to generate and return a formatted file containing raw transaction data.

ZKBio CVSecurity API

While ZKBio Time focuses on workforce logistics, ZKBio CVSecurity operates as a broader all-in-one security management system encompassing physical access control, elevator dispatching, visitor parking, and intelligent video management. The CVSecurity API requires explicit API license activation.

Standardized JSON Response Wrapper

{
  "code": 0,
  "message": "string",
  "data": {}
}

A code value > 0 indicates success; negative values denote failures or permission denials.

Dynamic Access Level Provisioning

Query and push access rights down to physical door controllers via endpoints like GET api/accLevel/list and POST accLevel/syncLevel. Critical for visitor management systems where temporary QR codes or PINs must be validated at turnstiles for specific timeframes.

Hardware State Manipulation

Bypass normal credential workflows with direct physical intervention mechanisms, granting external logic engines programmatic control over electronic door relays.

Real-Time Security Monitoring

Feed physical access logs into SIEM platforms via the transaction/monitor endpoint and api/transaction/device/{deviceSn} endpoints for correlation with cybersecurity events.

Elevator Dispatching

Integrate with third-party elevator controls to manage floor-specific access rights, preventing unauthorized personnel from calling cars to restricted levels.

Best Practices & Troubleshooting

Duplicate Data Prevention

Implement "last processed ID" logic or leverage precise timestamp filtering (start_time, end_time) to prevent duplicate data ingestion when synchronizing with HR platforms.

Offline Terminal States

The ADMS protocol caches punches locally when disconnected. APIs will occasionally receive massive historic data dumps once connectivity is restored — plan your ingestion pipeline accordingly.

Token Security

Enforce strict header compliance requiring Content-Type: application/json. Rotate tokens periodically and never expose credentials in client-side code.

Data Encryption

Enterprise middleware employs 256-bit AES encryption to secure biometric templates and personally identifiable information (PII) at rest and in transit.

Third-Party Abstractions & Cloud Bridges

The complexity of orchestrating raw ADMS push protocols has spurred the development of third-party abstraction layers. Open-source implementations provide lightweight, self-hosted alternatives using frameworks like Python Flask or Node.js.

Cloud bridge services intercept raw ADMS traffic from ZKTeco devices, parse the tab-separated values, and forward parsed data to client servers via clean, documented JSON webhooks — allowing organizations to sidestep the infrastructure costs of hosting ZKBio Time entirely while still achieving real-time synchronization with cloud ERPs.