デバイスゲートウェイAPI

Request to provide the next list of commands to be executed on a device

post

This method is used by TSH to request the pending commands to be executed on a device. It is used for reading/updating the content of a device (e.g. topup). The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses.

ヘッダーパラメータ

x-actor-idstring · 最大: 32必須

HTTP header identifying the actor initiating the request.

本文

issuerIdstring · 最小: 1 · 最大: 16必須

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · 最小: 1 · 最大: 48必須

The Card Identifier. Unique for each card.

purchaseIdstring · 最小: 1 · 最大: 64オプション

The Purchase Identifier. Unique for each purchase. It is provided when the call is related to topup initiated from wallet.

deviceIdstring · 最小: 1 · 最大: 48必須

The Device Identifier. Unique for each device.

operationstring · enumオプション

The operation for which the commands are requested

可能な値:

responseTimeMsnumber · doubleオプション

Total time of all executed commands listed in responses array in milliseconds.

statusCodenumberオプション

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringオプション

Textual status message

レスポンス

200

getCardCommands response payload

application/json

500

Internal Server Error

post

/getCardCommands

POST /tes/devicegtwapi/1/0/getCardCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 318

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "purchaseId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ]
}

Request to provide the next list of commands to be executed on a device for parking a card

post

This method is used by TSH to request the pending commands to be executed on a device. It is used for parking a card (meaning reading the current balance of a card for storing it on server side). The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses. Once the card has been parked on TES side, the TES has to return the card balance to TSH on last response.

ヘッダーパラメータ

x-actor-idstring · 最大: 32必須

HTTP header identifying the actor initiating the request.

本文

issuerIdstring · 最小: 1 · 最大: 16必須

The Card Issuer Identifier. Unique for each card issuer.

cardIdstring · 最小: 1 · 最大: 48必須

The Card Identifier. Unique for each card.

deviceIdstring · 最小: 1 · 最大: 48必須

The Device Identifier. Unique for each device.

operationstring · enumオプション

The operation for which the commands are requested

可能な値:

responseTimeMsnumber · doubleオプション

Total time of all executed commands listed in responses array in milliseconds.

statusCodenumberオプション

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringオプション

Textual status message

レスポンス

200

getParkCardCommands response payload

application/json

500

Internal Server Error

post

/getParkCardCommands

POST /tes/devicegtwapi/1/0/getParkCardCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 298

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z"
  },
  "issuerId": "text",
  "cardId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "cardData": {
    "balanceAmount": 1
  }
}

Request to provide the next list of reader mode commands to be executed on a device

post

This method is used by TSH to request the pending reader mode commands to be executed on a device. It is used for reading/updating the content of an external device. The TES has to return the list of commands that needs to be executed on the device after checking the previous commands responses. Once the card has been ingested on TES side, the TES has to create a new card account and return the card balance and card account identifier to TSH on last response.

ヘッダーパラメータ

x-actor-idstring · 最大: 32必須

HTTP header identifying the actor initiating the request.

本文

issuerIdstring · 最小: 1 · 最大: 16必須

The Card Issuer Identifier. Unique for each card issuer.

deviceIdstring · 最小: 1 · 最大: 48必須

The Device Identifier. Unique for each device.

operationstring · enumオプション

The operation for which the commands are requested

可能な値:

responseTimeMsnumber · doubleオプション

Total time of all executed commands listed in responses array in milliseconds.

cardContentsobject · cardContentsオプション

This object gives a description of the external SE. For FeliCa, the following can be provided:

"cardContents": {
	"cardServiceId" : "Test Service",
	"systemCode" : "FE00",
	"idm" : "1122334455667788",
	"pmm" : "0000000000000000",
	"areaCodeList" : [
		{
			"areaCode" : "0100",
			"keyVersion" : "6745"
		},
		{
			"areaCode" : "1000",
			"keyVersion" : "4567"
		}
	]
}

statusCodenumberオプション

Status code to the request

Status code	Description
0	OK
111	Missing mandatory parameter
112	Bad parameter format
113	Unknown issuer
117	Unknown device
118	Unknown session
119	Unknown virtual card
159	Card is blacklisted
160	Card is deleted
162	Card has unsufficient balance
163	Card product not eligible
167	Card is already provisioned
172	Invalid card, unsupported system code
173	Invalid card, unsupported service
177	Invalid card, invalid area data
178	Invalid card, card status is in-station
191	Card is expired
192	Reader mode attempt exceeded allowed threshold
221	Device or wallet server not accessible
231	Device unexpected error
232	Device out of memory error
321	Operation already on-going for this device
322	Time to live of the operation expired
323	Operation incomplete
911	Operation failed
921	Unexpected server error

statusMessagestringオプション

Textual status message

レスポンス

200

getReaderModeCommands response payload

application/json

cardAccountIdstring · 最小: 1 · 最大: 48オプション

The Card Account Identifier. Unique for each card account.

500

Internal Server Error

post

/getReaderModeCommands

POST /tes/devicegtwapi/1/0/getReaderModeCommands HTTP/1.1
x-actor-id: text
Content-Type: application/json
Accept: */*
Content-Length: 300

{
  "requestHeader": {
    "requestId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z"
  },
  "issuerId": "text",
  "deviceId": "text",
  "operation": "READ_BALANCE",
  "responses": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "responseTimeMs": 1,
  "cardContents": {},
  "statusCode": 1,
  "statusMessage": "text"
}

{
  "responseHeader": {
    "responseId": "text",
    "sessionId": "text",
    "generationDateTime": "2026-06-17T17:28:37.184Z",
    "statusCode": 1,
    "statusMessage": "text"
  },
  "commands": [
    {
      "id": "text",
      "name": "text",
      "value": "text"
    }
  ],
  "cardAccountId": "text",
  "cardData": {
    "balanceAmount": 1
  }
}

前へトランジットAPI 次へヘルスチェックAPI

最終更新 4 か月前

役に立ちましたか？