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 together with spinId)
spinId	string	Conditional	Operator Card Unique Identifier (Required when used together 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 the item has finished being used
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	The transaction does not exist or has already been cancelled
8	Player does not exist
11	Parameter error
83	Authentication Failed
84	Decryption Failed
89	Item has expired

Important Notes

1. Query Method: You can query using either of the following combinations
   • Method 1: username + spinId
   • Method 2: itemId
2. Parameter Combination: The complete parameter combination must be provided; mixing is not allowed
3. Real-time Data：Returns the latest usage status of the current Operator Card

FAQ

Q1: What are the isFinished scenarios for each Item Status?

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

Related APIs

• Cancel Operator Card