AK Manager — Bridge API (Exact from server.js)

This documentation was generated from the latest server.js you provided. It lists exact routes, parameters, return values, error codes and includes a Postman collection you can download.

Server & DLL

The bridge loads configuration from config.json and the vendor DLL path. Typical config:

{
  "port": 3001,
  "dllPath": "./btlock57.dll"
}

The server warns if Node's architecture is not ia32 because many vendor DLLs are 32-bit. Start the server with node server.js.

Authentication

The bridge expects callers to protect endpoints via your environment (firewall, local network) and recommends using an API key header when integrating with AK Manager or other systems:

Header: X-API-Key: <your_key>

Exact endpoints (from server.js)

GET /status
Bridge health and DLL load check.
200 OK
{ "connected": true, "type": "BTLock V5.7 Bridge", "message": "Bridge is active." }

500 (DLL missing)
{ "connected": false, "message": "DLL not loaded on server." }
GET /serial
Returns a serial number derived from current time using DLL function SerialNo_FromNow().
Request: GET /serial
Response 200:
{ "success": true, "serial": 12345678 }

500 on error
{ "success": false, "message": "..." }
POST /alarm
Trigger reader alarm (beep). Useful for UX feedback when testing hardware.

Request body (JSON)

{ "port": 1, "readerType": 4, "count": 1 }

Responses

200 OK
{ "success": true, "message": "Alarm triggered." }

400 - DLL returned non-zero
{ "success": false, "message": "Failed to trigger alarm.", "code": X }

500 - Exception
{ "success": false, "message": "..." }
POST /write-card
Writes a guest card using Write_Guest_Card in the DLL.

Request body (JSON)

{
  "propertySettings": {
    "doorId": "0001",            // required
    "port": 1,                    // optional (default 1)
    "readerType": 4,              // optional (default 4)
    "sectorNo": 0,
    "hotelPwd": "123456",
    "cardNo": 123456789,
    "guestSn": 123456789,
    "guestIdx": 1,
    "suitDoor": "0000",
    "pubDoor": "00000000",
    "beginTime": "2025-11-27 12:00",
    "endTime": "2025-11-28 12:00"
  },
  "options": {}
}

Success

200
{ "success": true, "message": "Card written successfully.", "cardData": { "cardNo": 123456789, "guestSn": 123456789, "doorId": "0001" } }

Errors

400 - DLL returned non-zero (example)
{ "success": false, "message": "DLL Error Code: 6 (Write Error)", "code": 6 }

500 - Exception
{ "success": false, "message": "..." }
POST /read-card
Reads a guest card using Read_Guest_Card. The implementation allocates pointers and buffers and returns parsed values.

Request body (JSON)

{ "propertySettings": { "port":1, "readerType":4, "sectorNo":0, "hotelPwd":"123456" } }

Success response (result === 0)

200
{
  "success": true,
  "data": {
    "cardNo": 123456789,
    "guestSn": 123456789,
    "guestIdx": 1,
    "doorId": "0001",
    "suitDoor": "0000",
    "pubDoor": "00000000",
    "beginTime": "2025-11-27 12:00",
    "endTime": "2025-11-28 12:00"
  }
}

Error responses

400 - DLL returned non-zero
Possible codes mapped:
1 = Serial Port Error
2 = No Card Found
3 = Card Type Error
4 = Read Error
5 = Hotel Password Error

Example:
{ "success": false, "message": "DLL Error Code: 2 (No Card Found)", "code": 2 }
POST /write-function-card
Simulated function card write — used by UI flows (e.g., checkout card). Currently triggers an alarm to simulate activity.
Request body: { "cardType": "checkout", "propertySettings": {"port":1} }
Response: { "success": true, "message": "checkout card operation simulated." }

DLL functions & types

The server maps these DLL functions via ffi-napi:

Note: argument types in server.js use ref and Buffer for pointer/char outputs.

Examples

Trigger alarm — curl

curl -X POST http://localhost:3001/alarm \
  -H "Content-Type: application/json" \
  -d '{"port":1,"readerType":4,"count":1}'

Write card — curl

curl -X POST http://localhost:3001/write-card \
  -H "Content-Type: application/json" \
  -d '{"propertySettings":{"doorId":"0001","beginTime":"2025-11-27 12:00","endTime":"2025-11-28 12:00"}}'

Read card — curl

curl -X POST http://localhost:3001/read-card \
  -H "Content-Type: application/json" \
  -d '{"propertySettings":{"port":1}}'

Postman collection

Download a ready-to-import Postman v2.1 collection with these exact routes and example bodies.

Download Postman Collection (JSON)

Troubleshooting & notes