# マイナンバーカード券面事項入力補助API

<br>

## **概要**       

券面事項入力補助APIは、マイナンバーカードの表面と裏面のテキストデータを取得するためのAPIです。
取得するテキストに対応した照合番号を入力し、マイナンバーカードのICチップから券面事項入力補助APを読み取ります。
これにより、契約や申込み時にテキストデータを取得、またテキストデータを利用した利用者情報や個人番号の自動入力が実現可能となります。
    
## **取得できる項目**
<AccordionGroup>
    <Accordion title="券面のテキスト（表面と裏面）">
        - 氏名（例：姓名／フリガナ）
        - 住所
        - 生年月日
        - 性別
        - 個人番号
    </Accordion>
    <Accordion title="券面のテキスト（表面）">
        - 氏名（例：姓名／フリガナ）
        - 住所
        - 生年月日
        - 性別
    </Accordion>
    <Accordion title="券面のテキスト（裏面）">
        - 個人番号
    </Accordion>
</AccordionGroup>
    
## **アクセスコントロール**

<AccordionGroup>
    <Accordion title="表面（基本4情報）と裏面（個人番号）のテキストを利用する" >
        暗証番号（4桁の数字） 
        ※3回連続で券面事項入力補助の暗証番号を間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
    </Accordion>
    <Accordion title="表面（基本4情報）のテキストを利用する" >
        券面記載の照合番号B（14桁の数字：生年月日6桁＋有効期限の西暦4桁＋セキュリティコード4桁）
        ※10回連続で券面事項確認の照合番号Bを間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
    </Accordion>
    <Accordion title="裏面（個人番号）のテキストを利用する" >
        券面記載の照合番号A（個人番号12桁の数字）
    </Accordion>
</AccordionGroup>
    
## **処理の流れ**

<Tabs>
    <Tab title="対面">
        <Steps>
            <Step title="券面事項の要求（サービスプロバイダ事業者）">
               取得対象に対応する暗証番号もしくは照合番号を利用者が入力します。
            </Step>
            <Step title="券面のテキストデータを取得（サービスプロバイダ事業者）">
                SDKを利用して、マイナンバーカードに格納されている券面事項入力補助APを呼び出し、暗証番号もしくは照合番号を照合することでマイナンバーカードの券面情報のテキストデータを取得します。
            </Step>
        </Steps>
    </Tab>
    <Tab title="非対面">
        <Steps>
            <Step title="券面事項の要求（サービスプロバイダ事業者）">
               取得対象に対応する暗証番号もしくは照合番号を利用者が入力します。 
            </Step>
            <Step title="券面のテキストデータを取得（サービスプロバイダ事業者）">
                SDKを利用して、マイナンバーカードに格納されている券面事項入力補助APを呼び出し、暗証番号もしくは照合番号を照合することでマイナンバーカードの券面情報のテキストデータを取得します。
            </Step>
        </Steps>
    </Tab>
</Tabs>

## **シーケンス図**
    
<Tabs>
    <Tab title="対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS

    サービスプロバイダ事業者->>SDK: 券面事項の要求
    alt 表面と裏面のテキストを利用する
        SDK->>利用者: 券面事項の要求・暗証番号4桁の要求
        利用者->>SDK: 券面の読み取り<br>暗証番号4桁の入力
    else 表面のテキストのみ利用する
        SDK->>利用者: 券面事項の要求・照合番号Bの要求
        利用者->>SDK: 券面の読み取り<br>照合番号Bの入力
    else 裏面のテキストのみ利用する
        SDK->>利用者: 券面事項の要求・照合番号Aの要求
        利用者->>SDK: 券面の読み取り<br>照合番号Aの入力
    end
    SDK->>SDK: 券面のデータ取得
    SDK->>サービスプロバイダ事業者: 券面データの返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 券面データの送信
    プラットフォーム事業者->>プラットフォーム事業者: 券面データのテキスト変換
    プラットフォーム事業者->>サービスプロバイダ事業者: テキストデータの返却
```
    </Tab>
    <Tab title="非対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS

    サービスプロバイダ事業者->>SDK: 券面事項の要求
    alt 表面と裏面のテキストを利用する
        SDK->>利用者: 券面事項の要求・暗証番号4桁の要求
        利用者->>SDK: 券面の読み取り<br>暗証番号4桁の入力
    else 表面のテキストのみ利用する
        SDK->>利用者: 券面事項の要求・照合番号Bの要求
        利用者->>SDK: 券面の読み取り<br>照合番号Bの入力
    else 裏面のテキストのみ利用する
        SDK->>利用者: 券面事項の要求・照合番号Aの要求
        利用者->>SDK: 券面の読み取り<br>照合番号Aの入力
    end
    SDK->>SDK: 券面のデータ取得
    SDK->>サービスプロバイダ事業者: 券面データの返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 券面データの送信
    プラットフォーム事業者->>プラットフォーム事業者: 券面データのテキスト変換
    プラットフォーム事業者->>サービスプロバイダ事業者: テキストデータの返却
```
    </Tab>
</Tabs>
    
## **実装例**

<Tabs>
    <Tab title="iOS">
```swift
// 暗証番号4桁または照合番号Aまたは照合番号B
let pinCode = "暗証番号4桁または照合番号Aまたは照合番号B"

// エンドポイント
let endpoint = "APIのエンドポイント"

// SDKの呼び出し
let reader = NFCReader(delegate: _NFCDelegate())

// 券面のテキストデータ取得
reader.getTicketTextData(pinCode: pinCode) { ticketTextData in

    let parameters = """
    {
        "data": "\(ticketTextData)"
    }
    """
    let postData = parameters.data(using: .utf8)
    
    // リクエスト作成
    var request = URLRequest(url: URL(string: endpoint)!, timeoutInterval: Double.infinity)
    request.addValue("<token>", forHTTPHeaderField: "X-PTS-API-Key")
    request.addValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpMethod = "POST"
    request.httpBody = postData
    
    // リクエストの送信・エラー処理の記述
    
}

```
    </Tab>
    <Tab title="Android">
```kotlin
// 暗証番号4桁または照合番号Aまたは照合番号B
val pinCode = "暗証番号4桁または照合番号Aまたは照合番号B"

// エンドポイント
val endpoint = "APIのエンドポイント"

// SDKの呼び出し
val reader = NFCReader(delegate = NFCDelegate())

// 券面のテキストデータ取得
reader.getTicketTextData(pinCode = pinCode) { ticketTextData ->
    val client = OkHttpClient()
    
    // リクエスト作成
    val body = JSONObject()
    body.put("data", ticketTextData)
    
    val mediaType = "application/json".toMediaType()
    val requestBody = body.toString().toRequestBody(mediaType)
    
    val request = Request.Builder()
        .url(endpoint)
        .post(requestBody)
        .addHeader("Content-Type", "application/json")
        .addHeader("X-PTS-API-Key", "<token>")
        .build()
    
    // リクエストの送信・エラー処理の記述
}
        
```
    </Tab>
    <Tab title="React Native">
```typescript
// 暗証番号4桁または照合番号A/B
const pinCode = '暗証番号4桁または照合番号Aまたは照合番号B';
// エンドポイント
const endpoint = 'APIのエンドポイント';
const token = '<token>';

// 本来はSDKで券面テキストデータを取得する
const ticketTextData = '<ticket-text-data>'; // 取得結果の想定

// リクエスト作成・送信
await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PTS-API-Key': `${token}`,
  },
  body: JSON.stringify({
    data: ticketTextData,
  }),
});
        
// リクエストの送信・エラー処理の記述

```
    </Tab>
    <Tab title="Windows">
```cpp
// 暗証番号4桁または照合番号Aまたは照合番号B
std::string pinCode = "暗証番号4桁または照合番号Aまたは照合番号B";

// エンドポイント
std::string endpoint = "APIのエンドポイント";

std::string responseData;

// SDKの呼び出し
NFCReader reader(delegate);

// 券面のテキストデータ取得
reader.getTicketTextData(pinCode, [&](const std::string& ticketTextData) {
    // リクエスト作成
    Json::Value body;
    body["data"] = ticketTextData;
    
    std::string jsonString = Json::writeString(Json::StreamWriterBuilder(), body);
    
    CURL* curl = curl_easy_init();
    if (curl) {
        struct curl_slist* headers = curl_slist_append(nullptr, "Content-Type: application/json");
        headers = curl_slist_append(headers, "X-PTS-API-KEY: <token>");
        curl_easy_setopt(curl, CURLOPT_URL, endpoint.c_str());
        curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonString.c_str());
        curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
        curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback);
        curl_easy_setopt(curl, CURLOPT_WRITEDATA, &responseData);
        
        CURLcode res = curl_easy_perform(curl);
        // リクエストの送信・エラー処理の記述

    }
});
        
```
    </Tab>
</Tabs>

<br>