Assist_Design/freebit-api-docs/PA05-20_mvno-semiblack-state-change.md

PA05-20 - MVNO Semi-Black Account Status Change (MVNO半黒アカウント状態変更)

Overview

Updates the status of a semi-black SIM identified by its product number, in freebit's managed systems.

• Used to manage the lifecycle of semi-black SIMs (cancel, mark as lost, returned, etc.)
• For white SIM inventory processing, use PA05-15 (MVNO White SIM Status Change) instead
• Setting status to "60" (cancelled) is a prerequisite for using the overwrite flag in PA05-18

---

Request

Method

POST (JSON format)

URL

https://[host]/emptool/api/mvno/semiblack/changeState/

Authentication

Obtained via separate authentication API, included in request parameters.

POST Parameters

No	Parameter	Name	Required	Description
1	json	JSON Parameters	◎	Main request body

JSON Parameters

No	Parameter	Name	Level	Type	Min	Max	Required	Description
1	authKey	Authentication Key	1	Alphanumeric	-	-	◎	Obtained from OEM authentication
2	productNumber	Product Number	1	Alphanumeric	15	15	◎	Product number printed on the back of the SIM. First 2 chars uppercase alpha, remaining 13 digits (e.g., AXxxxxxxxxxxxxx, DNxxxxxxxxxxxxx)
3	account	Account	1	Half-width numeric	11	14	◎	Target SIM phone number. Can be omitted when mnp.method is "20" (OTA). Required otherwise
4	mnp	MNP Info	1	Object	-	-	-	MNP information
5	mnp.method	MNP Method	2	Half-width numeric	2	2	◎	"10": Semi-black SIM, "20": OTA
6	mnp.reserveNumber	MNP Reservation Number	2	Half-width numeric	10	10	△	MNP reservation number (no hyphens). Can be omitted when mnp.method is "20" (OTA). Required otherwise
7	state	State	1	Half-width numeric	1	2	◎	Target SIM usage state (see State Values below)

Legend: ◎ Required | △ Conditional

State Values

Code	Name	Description
5	OEM Received	SIM received into OEM inventory
10	Semi-black (= Temp Reg)	Temporary registration state
20	Burn Failure / Reissue	SIM burn failed, needs reissue
30	Lost / Reissue	SIM lost, needs reissue
40	Used	SIM has been used/consumed
50	Damaged	SIM is physically damaged
60	Cancelled	Cancelled (e.g., MNP reservation invalid). Required before PA05-18 overwrite
70	OEM Collected	SIM collected/recovered by OEM
71	OEM Uncollectable	SIM cannot be collected by OEM
80	Returned to FB	SIM returned to freebit

---

Request Example

{
  "authKey": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "productNumber": "ZZ0009999999999",
  "account": "08011112222",
  "mnp": {
    "method": "10",
    "reserveNumber": "1101201234"
  },
  "state": "10"
}

---

Response

Format

JSON

Parameters

No	Parameter	Name	Level	Type	Description
1	resultCode	Result Code	1	Numeric	Processing result code
2	status	Status	1	Object	Status details
3	status.message	Message	2	Alphanumeric + symbols	Processing result message
4	status.statusCode	Detail Result Code	2	Numeric	Detailed status code

---

Response Codes

Status	Status Code	Detail Code	Message	Description
○	200	100	OK	Success
×	400	201	Bad Request	Parameter error - account (account/tempAccount) issue
×	400	266	Bad Request	Parameter error - product number issue
×	400	306	Bad Request	Parameter error - MNP method issue
×	400	307	Bad Request	Parameter error - MNP reservation number issue
×	400	280	Bad Request	Parameter error - state value issue
×	403	205	Auth Error	Authentication key problem
×	404	281	Not Found	Specified product number does not exist
×	500	282	NG	State transition not allowed (invalid state change)
×	500	900	NG	Unexpected error occurred

---

Response Example

{
  "resultCode": 100,
  "status": {
    "message": "OK",
    "statusCode": 200
  }
}

---

Related APIs

API	Name	Relationship
PA05-15	MVNO White SIM Status Change	Similar API for white SIMs (inventory processing)
PA05-18	MVNO Semi-Black Account Temporary Registration	Queues SIMs; overwrite flag requires this API to cancel first
PA05-19	MVNO Semi-Black Account Registration	Activates SIMs after temp registration