# マイナンバーカード券面API


<br>
## **概要**

券面APIは、マイナンバーカードの表面と裏面の券面データを取得するAPIです。
取得する券面データに対応した照合番号を入力し、マイナンバーカードのICチップから券面APを読み取ります。
これにより、本人確認時の券面記載情報の改ざん検知、また本人確認の証跡として画像情報の利用が可能となります。


:::caution[]
券面の両面（表面と裏面）のデータを取得する場合は、表面と裏面をそれぞれ取得する時と同様の利用料金がかかります。
:::

## **取得できる項目**
<AccordionGroup>
    <Accordion title="券面（表面と裏面）">
        画像で取得する項目
        - 氏名
        - 住所
        - 顔写真
        - セキュリティコード
        - 個人番号
        
        テキストで取得する項目
        - 生年月日
        - 性別
        - 有効期限
    </Accordion>
    <Accordion title="券面（表面）">
        画像で取得する項目
        - 氏名
        - 住所
        - 顔写真
        - セキュリティコード
        
        テキストで取得する項目
        - 生年月日
        - 性別
        - 有効期限
    </Accordion>
    <Accordion title="券面（裏面）">
        画像で取得する項目
        - 個人番号
    </Accordion>
</AccordionGroup>

## **アクセスコントロール**

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

## **処理の流れ**

<Tabs>
    <Tab title="対面">
        <Steps>
            <Step title="暗証番号または照合番号の入力要求（サービスプロバイダ事業者）">
                SDKを利用して取得する券面データに対応する暗証番号または照合番号の入力を利用者に要求します。
            </Step>
            <Step title="暗証番号または照合番号の入力（利用者）">
                利用者が暗証番号または照合番号を入力します。
                
:::info[]
SDKの券面OCR機能により、スマートフォンのカメラで照合番号の自動読み取りが可能です。
:::
            </Step>
            <Step title="券面データを取得（サービスプロバイダ事業者）">
                SDKを使用して、マイナンバーカードに格納されている券面APを呼び出し、入力した暗証番号または照合番号と照合することで内部認証を行います。内部認証が成功するとマイナンバーカードの券面データとして取得されます。
            </Step>
            <Step title="券面データの変換・返却（プラットフォーム事業者）">
                APIを使用して券面データを利用できる形式に変換し、サービスプロバイダ事業者へ返却します。
            </Step>
        </Steps>
    </Tab>
    <Tab title="非対面">
        <Steps>
            <Step title="暗証番号または照合番号の入力要求（サービスプロバイダ事業者）">
                SDKを利用して取得する券面データに対応する暗証番号または照合番号の入力を利用者に要求します。
            </Step>
            <Step title="暗証番号または照合番号の入力（利用者）">
                利用者が暗証番号または照合番号を入力します。
                
:::info[]
SDKの券面OCR機能により、スマートフォンのカメラで照合番号の自動読み取りが可能です。
:::
            </Step>
            <Step title="券面データを取得（サービスプロバイダ事業者）">
                SDKを使用して、マイナンバーカードに格納されている券面APを呼び出し、入力した暗証番号または照合番号と照合することで内部認証を行います。内部認証が成功するとマイナンバーカードの券面データとして取得されます。
            </Step>
            <Step title="券面データの変換・返却（プラットフォーム事業者）">
                APIを使用して券面データを利用できる形式に変換し、サービスプロバイダ事業者へ返却します。
            </Step>
        </Steps>
    </Tab>
</Tabs>




## **シーケンス図**

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

    Note over SDK,サービスプロバイダ事業者:1.暗証番号または照合番号の入力要求
    サービスプロバイダ事業者->>SDK: 券面データの要求
    Note over 利用者,SDK:2.暗証番号または照合番号の入力
    alt OCRを使用する場合
        SDK->>SDK: OCR用カメラ起動
        SDK->>利用者: OCR用カメラ画面の表示
        par
            利用者->>利用者: カメラで券面を映し続ける
        and
            SDK->>SDK: 券面より照合番号を読み取る
        end
    else 手入力を行う場合
        SDK->>利用者: 暗証番号または照合番号の入力画面表示
        alt 表面と裏面を読み取る場合
            利用者->>SDK: 暗証番号の入力
        else 表面を読み取る場合
            利用者->>SDK: 照合番号Bの入力
        else 裏面を読み取る場合
            利用者->>SDK: 照合番号Aの入力
        end
    end
    Note over 利用者,SDK:3.券面データを取得
    SDK->>利用者: マイナンバーカードの読み取り要求
    利用者->>SDK: マイナンバーカードをかざす
    Note over SDK,プラットフォーム事業者:4.券面データの変換・返却
    SDK->>SDK: 券面データ取得
    SDK->>サービスプロバイダ事業者: 券面データの返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 券面データの送信
    プラットフォーム事業者->>プラットフォーム事業者: 券面データの変換
    プラットフォーム事業者->>サービスプロバイダ事業者: 画像データの返却
```
    </Tab>
    <Tab title="非対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    autonumber
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS

    Note over SDK,サービスプロバイダ事業者:1.暗証番号または照合番号の入力要求
    サービスプロバイダ事業者->>SDK: 券面データの要求
    Note over 利用者,SDK:2.暗証番号または照合番号の入力
    alt OCRを使用する場合
        SDK->>SDK: OCR用カメラ起動
        SDK->>利用者: OCR用カメラ画面の表示
        par
            利用者->>利用者: カメラで券面を映し続ける
        and
            SDK->>SDK: 券面より照合番号を読み取る
        end
    else 手入力を行う場合
        SDK->>利用者: 暗証番号または照合番号の入力画面表示
        alt 表面と裏面を読み取る場合
            利用者->>SDK: 暗証番号の入力
        else 表面を読み取る場合
            利用者->>SDK: 照合番号Bの入力
        else 裏面を読み取る場合
            利用者->>SDK: 照合番号Aの入力
        end
    end
    Note over 利用者,SDK:3.券面データを取得
    SDK->>利用者: マイナンバーカードの読み取り要求
    利用者->>SDK: マイナンバーカードをかざす
    Note over SDK,プラットフォーム事業者:4.券面データの変換・返却
    SDK->>SDK: 券面データ取得
    SDK->>サービスプロバイダ事業者: 券面データの返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 券面データの送信
    プラットフォーム事業者->>プラットフォーム事業者: 券面データの変換
    プラットフォーム事業者->>サービスプロバイダ事業者: 画像データの返却
```
    </Tab>
</Tabs>


## **実装例**

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

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

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

// 内部認証・券面データ取得
reader.getTicketData(matchingNumber: pinCode) { ticketData in
    
    let parameters = """
    {
        "data": "\(ticketData.base64EncodedString())"
    }
    """
    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
// 照合番号Aまたは照合番号B
val pinCode = "暗証番号4桁または照合番号Aまたは照合番号B"

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

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

// 内部認証・券面データ取得
reader.getTicketData(matchingNumber = pinCode) { ticketData ->
    val client = OkHttpClient()
    
    // リクエスト作成
    val body = JSONObject()
    body.put("data", Base64.encodeToString(ticketData, Base64.NO_WRAP))
    
    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
// エンドポイント
const endpoint = 'APIのエンドポイント';
// 券面PIN
const pinCode = '暗証番号4桁または照合番号Aまたは照合番号B';

// 内部認証・券面データ取得
const cardFaceBase64 = TrustServices.getCardFace(pinCode);

// リクエスト作成
await fetch(endpoint, {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-PTS-API-Key': `${token}`,
    },
    body: JSON.stringify({
        data: cardFaceBase64, // Base64の券面データ
    })
});

// リクエストの送信・エラー処理の記述
```
    </Tab>
    <Tab title="Windows">
```cpp
// 照合番号Aまたは照合番号B
std::string pinCode = "照合番号";

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

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

// 内部認証・券面データ取得
reader.getTicketData(pinCode, [&](const std::vector<unsigned char>& ticketData) {
    // リクエスト作成
    Json::Value body;
    body["data"] = base64_encode(ticketData);
    
    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>