1.Overview
The Alipay Mini Program plugin provides Bluetooth unlocking and custom passwords. Pass the required parameters to unlock via Bluetooth or add, change, and delete passwords.
The Alipay Mini Program supports plugin API mode only. Use requirePlugin to load the plugin and call its APIs. The API returns the unlock result; the integrating app implements the user interface.
2. Integration Instructions
Add the QR Key plugin to your Mini Program on the Alipay Open Platform. After authorization, declare it in app.json. For integration details, see Alipay Mini Program Plugin Guide.
QR Key Alipay Mini Program plugin ID (provider): 2021007112686309
Unlock and password operations use the same business parameters. See below for the actual return fields. Enable Bluetooth and grant the Mini Program Bluetooth permission before calling.
III. Parameter Description
Required parameters Explanation
accountSid The Account SID for the Lock Cabinet Developer Account
token The Auth Token for the Lock Cabinet Developer Account
mobile Mobile
communityNo QR Master community
cardNo Please refer to Generate cards
areaCode Mobile phone area code
4. Sample Code
4.1 Declare the plugin in app.json
Plugin引用名使用 yaoshibang,provider 为AlipayPlugin ID,version 使用 1.0.0.
{
  "plugins": {
    "yaoshibang": {
      "version": "1.0.0",
      "provider": "2021007112686309"
    }
  }
}
4.2 Bind the unlock event in the page AXML
Use onTap to bind a page method. Customize the button and result display as needed.
<!-- pages/index/index.axml -->
<button onTap="openapi">Unlock via Bluetooth</button>
4.3 Call the unlock API in the page JS
Load the plugin with requirePlugin and call getResult(apiParam) to unlock via Bluetooth. Use the Promise to handle the result or an error. No navigation to a plugin page is required.
// pages/index/index.js
const yaoshibang = requirePlugin("yaoshibang");

Page({
  async openapi() {
    const apiParam = {
      accountSid: '98651082ab89c3f1b50f35caf794179f',
      token: 'd7ca4ca93c1e809b96ce30acf0a9a9',
      mobile: '10000000000',
      communityNo: '1316879946',
      cardNo: 'd4JYo5DmvRYApL2l',
      areaCode: '86'
    };
    my.showLoading({ content: 'Unlocking' });
    try {
      const result = await yaoshibang.getResult(apiParam);
      // 根据Back code、msg or错误对象处理结果
      console.log(result);
    } catch (error) {
      console.error(error);
    } finally {
      my.hideLoading();
    }
  }
});
Replace the sample account, room card, and other parameters with your actual business data.
4.4 Unlock API Return Values
getFlag resolves with status and info on success. On failure it still resolves with code, msg, message, and error; catch is not called. info preserves the server displayFlag as a number or string and does not identify a room door or locker.
getResult resolves with code and msg on success and rejects with code, msg, message, and error on failure. Both displayFlag 0 and 1 use API unlocking without navigating to a plugin page.
Parameter Name Type Explanation
status number getFlag success status; always the number 200
info number | string | undefined Original server displayFlag: 0 for the legacy API mode, 1 for the legacy page mode
code number The number 200 on getResult success; otherwise a plugin error code from the table below
msg string Unlock result text. A closed door still returns code 200 with msg set to “门已关闭”
message string Returned only on failure and equal to msg. Unlock errors are plain objects, not PassworldOperationError instances
error any | undefined Returned only on failure; preserves the native error, server response, or lock data and may be undefined

BLEPasswordOperation interface

yaoshibang.passwordAdd: (prams:PasswordAddParmas)=>Promise<PasswordAddResult> throw PassworldOperationError

PasswordAddParmas

Parameter Name Type example Explanation
version string 1.0.00 api version
accountSid string 5621e3c3618de890e48375801ca77e18 Unique identification of developer account
communityNo string 1316880684 Community No.
buildNo string 001 Building No.
floorNo string 000 Floor No.
roomNo string 410 Room No.
cipher string 123456 Password
startTime string 202412261200 Start Time
endTime string 202412271200 End Time
token string 8732e7bed17b3c0c097bc8af5677df token
holder string UCLBRT Holder
callback (p:ProcessCallback)=>void Operation progress callback

ProcessCallback

Parameter Name Type example Explanation
status number 1 Current operating state
msg string Request QR Master Short description
status msg
1 Request QR Master
10 Subcontracting data
20 Turn on Bluetooth adapter
30 Search Bluetooth devices
40 Connecting lock
50 Get Bluetooth services
60 Get the Bluetooth service feature value
70 Writes data to the lock
80 Obtain operation result data
90 Synchronize data to QR Master

PasswordAddResult

Parameter Name Type example Explanation
mac string 1234567A1234 MAC address
roomId any 1001 Original server roomId; may be undefined
cipher any 123456 Original server cipher without type conversion. Deletion APIs may return undefined, and batch deletion does not guarantee an array
power number 99 Raw battery value from byte 8 of the lock reply; the plugin does not validate its range

PassworldOperationError

code message error Description
0 string any | undefined Missing parameters, an invalid password array, Bluetooth initialization, or an unknown error. message may be empty; error preserves the original exception.
100 string any | undefined System Bluetooth permission denied (state 3). Enable Bluetooth permission for Alipay in system settings.
101 string any | undefined Alipay or the host Mini Program was denied Bluetooth permission; error is the native error.
102 string any | undefined System Bluetooth is off or unavailable.
103 string undefined Target lock search timed out. Password APIs return message timeout and error undefined.
104 string any | undefined Starting Bluetooth discovery or retrieving discovered devices failed.
105 string any | undefined Lock connection failed or timed out.
106 string any | undefined Service or characteristic retrieval failed, FFF0 or FFEA is missing, or writing or notifications are unsupported.
107 string any | undefined Writing Bluetooth data to the lock failed or timed out.
108 string any | undefined Registering a Bluetooth listener or subscribing to characteristic notifications failed.
109 string {result: String} | object | undefined Unknown, incomplete, or malformed lock reply, or result timeout. Unknown password replies use comma-separated hex bytes in result; unknown unlock replies use the raw hex string.
110 string {code: Number} Beep Error Reference The lock rejected the operation. error.code is the numeric hardware error code; see the beep error reference.
111 string any | undefined Server request failed or timed out; error preserves the native network error.
112 string any | undefined Invalid HTTP status or server data, missing lock data or required fields, or malformed commands. error is the response body or lock data.
403 string {
   status: Number | String,
   info: String
}		 Business error. error preserves status, info, and other fields. Password APIs have an empty message; unlock APIs prefer the server info.
113 string any | undefined The lock operation succeeded but server synchronization failed: password reporting for password APIs, or unlock-log reporting for unlock APIs. Reconcile the state; do not automatically repeat the lock operation.

Complete Example

const yaoshibang = requirePlugin("yaoshibang");

async function passwordAdd() {
  try {
    my.showLoading();
    const result = await yaoshibang.passwordAdd({
      version: "1.0.00",
      accountSid: "5621e3c3618de890e48375801ca77e18",
      communityNo: "1316880684",
      buildNo: "001",
      floorNo: "000",
      roomNo: "410",
      cipher: "123456",
      startTime: "202412261200",
      endTime: "202412271200",
      token: "8732e7bed17b3c0c097bc8af5677df",
      holder: "UCLBRT",
      callback: ({ status, msg }) => {
        console.log("进度", status, msg);
        my.showLoading({
          content: status + ":" + msg,
        });
      },
    });
    console.log("Operation succeeded", result);
    console.log("Electricity", result.power);
  } catch (error) {
    if (error instanceof yaoshibang.PassworldOperationError) {
      console.error(error.code, error.message, error.error);
    } else {
      console.error(error);
    }
    console.log("Operation failed");
  } finally {
    my.hideLoading();
  }
}

//Promise风格
function passwordAddByPromise(){
  my.showLoading();
  yaoshibang.passwordAdd({
      version: "1.0.00",
      accountSid: "5621e3c3618de890e48375801ca77e18",
      communityNo: "1316880684",
      buildNo: "001",
      floorNo: "000",
      roomNo: "410",
      cipher: "123456",
      startTime: "202412261200",
      endTime: "202412271200",
      token: "8732e7bed17b3c0c097bc8af5677df",
      holder: "UCLBRT",
      callback: ({ status, msg }) => {
        console.log("进度", status, msg);
        my.showLoading({
          content: status + ":" + msg,
        });
      },
    })
    .then((result) => {
      console.log("Operation succeeded", result);
      console.log("Electricity", result.power);
      my.hideLoading();
    })
    .catch((error) => {
      if (error instanceof yaoshibang.PassworldOperationError) {
        console.error(error.code, error.message, error.error);
      } else {
        console.error(error);
      }
      console.log("Operation failed");
      my.hideLoading();
    });
}

passwordAdd();

yaoshibang.passwordDel: (prams:PasswordDelParmas)=>Promise<PasswordDelResult> throw PassworldOperationError

PasswordDelParmas

Parameter Name Type example Explanation
version string 1.0.00 api version
accountSid string 5621e3c3618de880e48375801ca77e18 Unique identification of developer account
communityNo string 1316880684 Community No.
buildNo string 001 Building No.
floorNo string 000 Floor No.
roomNo string 410 Room No.
cipher string 123456 Password
token string 8732e7bed17b3c1c097bc8af5677df token
callback (p:ProcessCallback)=>void Operation progress callback

PasswordDelResult

Parameter Name Type example Explanation
mac string 1234567A1234 MAC address
cipher any 123456 Original server cipher without type conversion. Deletion APIs may return undefined, and batch deletion does not guarantee an array
power number 99 Raw battery value from byte 8 of the lock reply; the plugin does not validate its range

yaoshibang.passwordsDel: (prams:PasswordDelParmas)=>Promise<PasswordDelResult> throw PassworldOperationError

PasswordsDelParmas

Parameter Name Type example Explanation
version string 1.0.00 api version
accountSid string 5621e3c3618de880e48375801ca77e18 Unique identification of developer account
communityNo string 1316880684 Community No.
buildNo string 001 Building No.
floorNo string 000 Floor No.
roomNo string 410 Room No.
ciphers array ['123456', '234567'] Password (up to 10 deleted)
token string 8732e7bed17b3c1c097bc8af5677df token
callback (p:ProcessCallback)=>void Operation progress callback

PasswordsDelResult

Parameter Name Type example Explanation
mac string 1234567A1234 MAC address
cipher any ['123456','234567'] Original server cipher without type conversion. Deletion APIs may return undefined, and batch deletion does not guarantee an array
power number 99 Raw battery value from byte 8 of the lock reply; the plugin does not validate its range

yaoshibang.passwordChange: (prams:PasswordChangeParmas)=>Promise<PasswordChangeResult> throw PassworldOperationError

PasswordChangeParmas

Parameter Name Type example Explanation
version string 1.0.00 api version
accountSid string 5621e3c3618de880e48375801ca77e18 Unique identification of developer account
communityNo string 1316880684 Community No.
buildNo string 001 Building No.
floorNo string 000 Floor No.
roomNo string 410 Room No.
oldCipher string 123456 Old password
newCipher string 123456 New password
startTime string 202412261200 Start Time
endTime string 202412271200 End Time
token string 8732e7bed17b3c0c097bc8af5677df token
holder string UCLBRT Holder
callback (p:ProcessCallback)=>void Operation progress callback

PasswordChangeResult

Parameter Name Type example Explanation
mac string 1234567A1234 MAC address
roomId any 1001 Original server roomId; may be undefined
newCipher any 654321 Original server newCipher without type conversion
oldCipher any 123456 Original server oldCipher without type conversion
power number 99 Raw battery value from byte 8 of the lock reply; the plugin does not validate its range

Beep Error Reference

code Prompt Cause and explanation
1 Operation successful; startup Sounds when a lock operation succeeds, encryption is performed, or the card issuer starts
2 Clear card processed successfully Authorization information cleared; factory settings restored
3 Key mismatch User password is incorrect or invalid
4 Invalid card type Card type, communication, or key error
5 No guest checked in Five beeps indicate no guest is checked into this room; the checkout card is invalid
6 Room number mismatch The room number on the card differs from the lock. Change rooms or reconfigure the lock
7 Time mismatch (reported over Bluetooth) The card has expired or the lock clock is incorrect. Obtain a new card or reset the lock time
8 Batch number mismatch (guest card) This card was reported lost. Reissue a card with the same batch number (guest card)
9 Invalid clear card The key has not been turned
10 Invalid authorization code on the authorization card Turn the mechanical key before authorizing the lock
11 Invalid building card number The building card used to configure the hotel belongs to a different hotel
12 Invalid floor card number The floor card used to set the room number belongs to a different floor. Reset the room numbers for this floor
13 Room deadbolted The lock is deadbolted and cannot be opened
14 Low battery Low battery (presenting a card after the lock restarts also produces 14 beeps)
15 Hotel identifier mismatch The authorization or reissued card was not issued on this hotel's front desk computer. Reissue it on that computer
16 Log collection failed Sound emitted by the lock when log collection with an IC card fails
17 Reading failed Sound emitted when the card issuer fails to read a card
18 Invalid usage count (reported over Bluetooth) The guest card has used all its allowed unlocks
20 Brand number mismatch Card belongs to a different system
21 Room access suspended The guest card, building, or floor is suspended, preventing the room lock from opening. Present the card again to restore normal operation
30 Distributor number mismatch Card belongs to a different system