Query Operator Card Status

Query the current Status of sent Operator Cards.

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 winning 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 methods: Two combinations can be chosen for query
   • Method one: username + spinId
   • Method two: itemId
2. Parameter combination: A complete parameter combination must be provided, cannot be mixed
3. Real-time Data: Returns the latest usage status of the current Operator Card

Common QA

Q1: isFinished scenarios under various Item Status?

• 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

Related APIs

• Cancel Operator Card