# 特別永住者証明書API

<br>
## **概要**

特別永住者証明書APIは、特別永住者証明書または特定特別永住者証明書のICチップを読み取るためのAPIです。
特別永住者証明書または特定特別永住者証明書に記載されている12桁の特別永住者証明書番号を入力することで、特別永住者証明書または特定特別永住者証明書の情報を全て取得します（取得項目は選択可能です）。また、特別永住者証明書に格納されているチェックコードを検証することで真贋判定を行い、有効期限満了日と当日の日時を比較することで、有効性確認も同時に行います。真贋および有効性確認後、特別永住者証明書または特定特別永住者証明書の情報を取得できます。

:::caution[]
注意
特別永住者証明書には、第1世代または第2世代の2種類が存在し、一部の取得項目が異なります。各特別永住者証明書の取得項目につきましては、「第1世代特別永住者証明書の取得項目」および「第2世代特別永住者証明書の取得項目」をご覧ください。
:::

<AccordionGroup>
    <Accordion title="第1世代特別永住者証明書の取得項目">
        ※第1世代特別永住者証明書の表面の情報は、券面（表）イメージとして1つの画像で取得されます。
        **券面（表）イメージ**
        - 氏名
        - 生年月日
        - 性別
        - 住居地
        - 有効期限満了日
        - 国籍
        - 在留カード等の番号 
        
        **券面（表）イメージ以外**
        - カード種別
        - 顔画像（カラー画像）
        - 追記書き込み年月
        - 市町村コード
        - 住居地（裏面）
        - チェックコード
        - 公開鍵証明書        
    </Accordion>
    <Accordion title="第2世代特別永住者証明書の取得項目">
        - 氏名イメージ
        - 生年月日
        - 性別
        - 住居地イメージ
        - 顔画像（カラー画像）
        - 有効期限満了日
        - 住居地（裏面）
        - カード種別
        - 在留カード等の番号 
        - 国籍
        - 追記書き込み年月
        - 市町村コード
        - 出入国在留管理庁長官が記載した旨 
        - チェックコード
        - 公開鍵証明書        
    </Accordion>
    <Accordion title="特定特別永住者証明書の取得項目">
        - 氏名イメージ
        - 生年月日
        - 性別
        - 住居地イメージ
        - 顔画像（カラー画像）
        - 有効期限満了日
        - 住居地（裏面）
        - カード種別
        - 在留カード等の番号 
        - 国籍
        - 追記書き込み年月
        - 市町村コード
        - 出入国在留管理庁長官が記載した旨 
        - チェックコード
        - 公開鍵証明書        
    </Accordion>
</AccordionGroup>

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

<AccordionGroup>
    <Accordion title="特別永住者証明書情報の取得">
        - 券面記載の在留カード等の番号（計12桁：アルファベット大文字2桁＋数字8桁＋アルファベット大文字2桁）
    </Accordion>
    <Accordion title="特定特別永住者証明書情報の取得">
        - 券面記載の在留カード等の番号（計12桁：アルファベット大文字2桁＋数字8桁＋アルファベット大文字2桁）
    </Accordion>
 </AccordionGroup>
    
## **処理の流れ**

<Tabs>
    <Tab title="対面">
        <Steps>
            <Step title="特別永住者証明書・特定特別永住者証明書のデータ取得（サービスプロバイダ事業者）">
                SDKを利用して特別永住者証明書または特定特別永住者証明書のICチップを読み取り、利用者が入力した特別永住者証明書番号または特定特別永住者証明書番号を利用することで、特別永住者証明書または特定特別永住者証明書のデータを取得します。取得したデータは、署名検証・有効性確認・利用できる形式への変換を行うために、専用のAPIで送信します。
            </Step>
            <Step title="特別永住者証明書・特定特別永住者証明書の署名検証・有効性確認（プラットフォーム事業者）">
                APIで送信されたデータより、電子署名を取得し、署名検証による真贋判定を行います。署名検証後は、特別永住者証明書または特定特別永住者証明書の有効期限満了日と当日の日付を比較することで、有効性確認を行います。第一世代の特別永住者証明書に限り、券面イメージ内の有効期限満了日を抽出し、そちらを照合するため、抽出失敗時はエラーを返却します。

:::caution[]
紛失、出国済み、在留資格の取消しなど、失効理由を確認される場合は、出入国在留管理庁の提供する「[在留カード等番号失効情報照会](https://www.moj.go.jp/isa/applications/procedures/rcc-support.html)」を別途ご利用ください。
:::
            </Step>
            <Step title="特別永住者証明書情報・特定特別永住者証明書の情報取得（プラットフォーム事業者）">
                署名検証および有効性確認後、特別永住者証明書または特定特別永住者証明書の情報を利用できる形式へ変換し、サービスプロバイダ事業者へ返却します。取得項目を選択している場合は、対象の項目のみ返却されます。
            </Step>
        </Steps>
    </Tab>
    <Tab title="非対面">
        <Steps>
            <Step title="特別永住者証明書・特定特別永住者証明書のデータ取得（サービスプロバイダ事業者）">
                SDKを利用して特別永住者証明書または特定特別永住者証明書のICチップを読み取り、利用者が入力した特別永住者証明書番号または特定特別永住者証明書番号を利用することで、特別永住者証明書または特定特別永住者証明書のデータを取得します。取得したデータは、署名検証・有効性確認・利用できる形式への変換を行うために、専用のAPIで送信します。
            </Step>
            <Step title="特別永住者証明書・特定特別永住者証明書の署名検証・有効性確認（プラットフォーム事業者）">
                APIで送信されたデータより、電子署名を取得し、署名検証による真贋判定を行います。署名検証後は、特別永住者証明書または特定特別永住者証明書の有効期限満了日と当日の日付を比較することで、有効性確認を行います。第一世代の特別永住者証明書に限り、券面イメージ内の有効期限満了日を抽出し、そちらを照合するため、抽出失敗時はエラーを返却します。
:::caution[]
紛失、出国済み、在留資格の取消しなど、失効理由を確認される場合は、出入国在留管理庁の提供する「[在留カード等番号失効情報照会](https://www.moj.go.jp/isa/applications/procedures/rcc-support.html)」を別途ご利用ください。
:::
            </Step>
            <Step title="特別永住者証明書情報・特定特別永住者証明書の情報取得（プラットフォーム事業者）">
                署名検証および有効性確認後、特別永住者証明書または特定特別永住者証明書の情報を利用できる形式へ変換し、サービスプロバイダ事業者へ返却します。取得項目を選択している場合は、対象の項目のみ返却されます。
            </Step>
        </Steps>
    </Tab>
</Tabs>



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

<Tabs>
    <Tab title="対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS
    
    alt 特別永住者証明書の場合
        サービスプロバイダ事業者->>SDK: 特別永住者証明書の読み取り要求
        SDK->>利用者: 特別永住者証明書の読み取り要求
        利用者->>SDK: 特別永住者証明書の読み取り<br>特別永住者証明書番号の入力
        SDK->>SDK: 特別永住者証明書のデータ取得
        SDK->>SDK: ハッシュ値の生成
        SDK->>サービスプロバイダ事業者: 特別永住者証明書のデータの返却
        サービスプロバイダ事業者->>プラットフォーム事業者: 特別永住者証明書のデータの送信
        プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書の署名検証
        プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書の有効性確認
        alt 署名検証・有効性確認が正常の場合
            プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書データの変換
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果<br>特別永住者証明書情報の返却
        else 署名検証・有効性確認が異常の場合
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果の返却
        end
    else 特定特別永住者証明書の場合
        サービスプロバイダ事業者->>SDK: 特定特別永住者証明書の読み取り要求
        SDK->>利用者: 特定特別永住者証明書の読み取り要求
        利用者->>SDK: 特定特別永住者証明書の読み取り<br>特別永住者証明書番号の入力
        SDK->>SDK: 特定特別永住者証明書のデータ取得
        SDK->>SDK: ハッシュ値の生成
        SDK->>サービスプロバイダ事業者: 特定特別永住者証明書のデータの返却
        サービスプロバイダ事業者->>プラットフォーム事業者: 特定特別永住者証明書のデータの送信
        プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書の署名検証
        プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書の有効性確認
        alt 署名検証・有効性確認が正常の場合
            プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書データの変換
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果<br>特定特別永住者証明書情報の返却
        else 署名検証・有効性確認が異常の場合
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果の返却
        end
    end
```
    </Tab>
    <Tab title="非対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS
    
    alt 特別永住者証明書の場合
        サービスプロバイダ事業者->>SDK: 特別永住者証明書の読み取り要求
        SDK->>利用者: 特別永住者証明書の読み取り要求
        利用者->>SDK: 特別永住者証明書の読み取り<br>特別永住者証明書番号の入力
        SDK->>SDK: 特別永住者証明書のデータ取得
        SDK->>SDK: ハッシュ値の生成
        SDK->>サービスプロバイダ事業者: 特別永住者証明書のデータの返却
        サービスプロバイダ事業者->>プラットフォーム事業者: 特別永住者証明書のデータの送信
        プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書の署名検証
        プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書の有効性確認
        alt 署名検証・有効性確認が正常の場合
            プラットフォーム事業者->>プラットフォーム事業者: 特別永住者証明書データの変換
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果<br>特別永住者証明書情報の返却
        else 署名検証・有効性確認が異常の場合
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果の返却
        end
    else 特定特別永住者証明書の場合
        サービスプロバイダ事業者->>SDK: 特定特別永住者証明書の読み取り要求
        SDK->>利用者: 特定特別永住者証明書の読み取り要求
        利用者->>SDK: 特定特別永住者証明書の読み取り<br>特定特別永住者証明書番号の入力
        SDK->>SDK: 特定特別永住者証明書のデータ取得
        SDK->>SDK: ハッシュ値の生成
        SDK->>サービスプロバイダ事業者: 特定特別永住者証明書のデータの返却
        サービスプロバイダ事業者->>プラットフォーム事業者: 特定特別永住者証明書のデータの送信
        プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書の署名検証
        プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書の有効性確認
        alt 署名検証・有効性確認が正常の場合
            プラットフォーム事業者->>プラットフォーム事業者: 特定特別永住者証明書データの変換
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果<br>特定特別永住者証明書情報の返却
        else 署名検証・有効性確認が異常の場合
            プラットフォーム事業者->>サービスプロバイダ事業者: 署名検証結果・有効性確認結果の返却
        end
    end
```
    </Tab>
</Tabs>

## **実装例**

<Tabs>
    <Tab title="iOS">
```swift
// 特別永住者証明書番号
let pin = "特別永住者証明書番号"

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

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

// 特別永住者証明書情報の取得
reader.getSpecialPermanentResidentCertInfo(pin: pin) { certData in

    let parameters = """
    {
        "data": "\(certData)",
        "allFlag":false
    }
    """
    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
// 特別永住者証明書番号
val pin = "特別永住者証明書番号"

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

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

// 特別永住者証明書情報の取得
reader.getSpecialPermanentResidentCertInfo(tag, pin) { certData ->
    val client = OkHttpClient()
    
    // リクエスト作成
    val body = JSONObject()
    body.put("data", certData)
    body.put("allFlag",false)
    
    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 pin = "特別永住者証明書番号"

// エンドポイント
const endpoint = 'APIのエンドポイント';
const token = '<token>';

// 本来はSDKで特別永住者証明書情報を取得する
const certData = '<certData>'; // 取得結果の想定

// リクエスト作成・送信
await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PTS-API-Key': `${token}`,
  },
  body: JSON.stringify({
    data: certData,
    allFlag: false
  }),
});
        
// リクエストの送信・エラー処理の記述
```
    </Tab>
    <Tab title="Windows">
```cpp
// 特別永住者証明書番号
std::string pin = "特別永住者証明書番号";

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

std::string responseData;

// 特別永住者証明書情報の取得（C API: get_special_permanent_resident_cert_info(session, pin, data, data_max, data_len)）
const int data_max = 4096;  // 必要に応じてサイズを調整
std::vector<uint8_t> buffer(data_max);
int data_len = 0;

int result = get_special_permanent_resident_cert_info(session, pin.c_str(), buffer.data(), data_max, &data_len);

if (result == 0 && data_len > 0) {
    // APIはBase64のICカードデータを要求するため、バイナリをBase64エンコード
    std::string certDataBase64 = base64_encode(buffer.data(), data_len);
    
    // リクエスト作成
    Json::Value body;
    body["data"] = certDataBase64;
    body["allFlag"] = false;
    
    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);
        // リクエストの送信・エラー処理の記述
        
        curl_slist_free_all(headers);
        curl_easy_cleanup(curl);
    }
}
```
    </Tab>
</Tabs>

<br>