Query Operator Card Status

Query the current status of a sent Operator Card

API Information

• URL: POST /v2/items/state
• Authentication: Bearer Token
• Encryption: Requests are encrypted using AES-256-GCM; responses are returned as plaintext JSON

Request

Request Headers

POST /v2/items/state HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
x-agentid: integratorNBTest04
x-timestamp: 1769746894501
x-nonce: 56ffd5ecd8a3a4457863a0bd7c298fb2
x-signature: 904e97bee2589b93e9747eed0346c68b23d8ff8b568dabaf4b94a5e89093df67

Request Parameters

Parameters Before Encryption

{
   "username": "testaccount001",
   "spinId": "VPItemTestTrans1015_ghjklhtombg",
   "itemId": "Systemtest_ItemId_1"
}

Encrypted Request Body

{
  "cipherText": "G0ZMDELeJwx+7JcIfIFOLJjkSzANPu6krGM2uw==..."
}

Field	Type	Required	Description
username	string	Conditional	Player Account (Required when used with spinId)
spinId	string	Conditional	Operator Card Unique Identifier (Required when used with username)
itemId	string	Conditional	System Operator Card ID (Required when used alone)

Response

Success Response

{
   "code": 0,
   "message": "No error.",
   "data": {
       "win": 2.64,
       "isFinished": true,
       "gameCode": "VP_230001_1",
       "username": "integratorNBTest04_VPSysDevTest002",
       "expiredTime": "2025-10-25T17:03:20.000Z",
       "itemId": "e60926515661dac5bbb611e042dfed2b_VPItemTestTrans1036_ghjklhtombg"
   },
   "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}

Response Field Description

Field	Type	Description
data.win	number	Current win amount
data.isFinished	boolean	Whether usage is completed
data.gameCode	string	Game Code
data.username	string	Player Account
data.expiredTime	string	Expiration time
data.itemId	string	System Operator Card ID

Error Response

{
  "code": 4,
  "message": "The transaction doesn`t exist.",
  "logUUID": "6589bf8d-fe74-48bd-841a-71bf8f848f86"
}

Common Error Codes

Code	Description
4	Transaction does not exist or has been cancelled
8	Player does not exist
11	Parameters error
83	Authentication Failed
84	Decryption Failed
89	Item expired

Important Notes

1. Query Method: You can query using one of two combinations
   • Method 1: username + spinId
   • Method 2: itemId
2. Parameter Combination: A complete parameter combination must be provided, do not mix and match
3. Real-time Data: Returns the latest usage status of the current Operator Card

Frequently Asked Questions

Q1: Scenarios for isFinished under various Operator Card statuses?

• isFinished false (Sent, but not settled)
  • Sent, not played, not expired
  • Sent, played but exited midway without settlement, not expired
• isFinished true (Sent, already settled)
  • Sent, played and settled, not expired

Q2: Can the query result differentiate between "unused" and "in use"?

Currently, it cannot be differentiated; both statuses return isFinished: false. isFinished only indicates whether settlement is completed, it cannot determine whether the Operator Card is currently in use.

Related APIs

• Cancel Operator Card