# 同意取得API

<br>

## **概要**
    
同意取得APIは、利用者の基本4情報（氏名・住所・生年月日・性別）の提供を受けるために必要となる同意を取得するためのAPIです。利用者からの同意は、本人の意思に基づくものであることを確実に示すため、署名用電子証明書を用います。署名用電子証明書を用いた同意は、サービスプロバイダ事業者とプラットフォーム事業者を経由しJ-LISに送信されます。各事業者及びJ-LISは、それぞれ同意情報に関するデータベース等を構築し、保存・管理を行います。

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

<AccordionGroup>
    <Accordion title="マイナンバーカード">
        署名用電子証明書の暗証番号（6〜16桁の半角英数字）
        ※5回連続で署名用電子証明書の暗証番号を間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
    </Accordion>
    <Accordion title="スマートフォンのマイナンバーカード">
        署名用電子証明書の暗証番号（6〜16桁の半角英数字）
        ※5回連続で署名用電子証明書の暗証番号を間違えた場合には、マイナンバーカードにロックがかかってしまいますのでご注意ください。
    </Accordion> </AccordionGroup>

## **処理の流れ**
<Tabs>
    <Tab title="対面">
        <Steps>
            <Step title="利用者から同意取得（サービスプロバイダ事業者）">
                利用者から基本4情報（氏名・住所・生年月日・性別）の取得に関する同意を取得します。 
            </Step>
            <Step title="同意申請書データの作成・送信（サービスプロバイダ事業者）">
                利用者から同意を取得した後、SDKを使用して利用者のマイナンバーカードまたはスマートフォンのマイナンバーカードを、ICカードリーダーまたはスマートフォンのNFC機能で読み取り、6〜16桁の署名用電子証明書の暗証番号を入力することで、同意申請書データを生成し、APIでリクエストを送信します。
                
               ※スマートフォンのマイナンバーカード読み取りは、機種ごとに読み取り手順が変わります。
                <AccordionGroup>
                    <Accordion title="iPhoneのマイナンバーカードを読み取る">
                        <Steps>
                            <Step>Appleウォレットを起動し、マイナンバーカードを選択します。</Step>
                            <Step>Face IDまたはTouch IDによる認証を行います。</Step>
                            <Step>認証完了後、iPhoneの画面に「リーダーにかざしてください」の表示が出ている状態で、ICカードリーダーまたは読み取り用スマートフォンのNFC機能で読み取りを行います。</Step>
                        </Steps>
                    </Accordion>
                    <Accordion title="Androidスマホ用電子証明書を読み取る">
                        <Steps>
                            <Step>設定アプリより、NFC機能をオンにします。</Step>
                            <Step>NFC機能がオンになっていることを確認し、Android端末をICカードリーダーまたは読み取り用スマートフォンのNFC機能で読み取りを行います。</Step>
                            </Steps>
                    </Accordion>
                </AccordionGroup>
            </Step>
            <Step title="同意申請書データの送信（プラットフォーム事業者）">
                受信した同意申請書データをJ-LISに送信し、利用者の同意を申請します。J-LISは同意データを受信後、署名検証と失効確認を行い、問題がなければ同意結果をプラットフォーム事業者へ返却します。
            </Step>
            <Step title="同意結果の取得（プラットフォーム事業者）">
                同意申請が正常に完了した場合、J-LISから同意結果（受理番号および利用者同意の有効期限）が返却されます。
            </Step>
            <Step title="同意結果の保存・返却（プラットフォーム事業者）">
              取得した同意結果をデータベースに保管・管理し、サービスプロバイダ事業者へ返却します。また、サービスプロバイダ事業者も同様に、同意結果を自社のデータベースで保管・管理する必要があります。
            </Step>
        </Steps>
    </Tab>
    <Tab title="非対面">
        <Steps>
            <Step title="利用者から同意取得（サービスプロバイダ事業者）">
                利用者から基本4情報（氏名・住所・生年月日・性別）の取得に関する同意を取得します。 
            </Step>
            <Step title="同意申請書データの作成・送信（サービスプロバイダ事業者）">
                利用者から同意を取得した後、SDKを使用して利用者のマイナンバーカードを、スマートフォンのNFC機能で読み取り、6〜16桁の署名用電子証明書の暗証番号を入力することで、同意申請書データを生成し、APIでリクエストを送信します。
            </Step>
            <Step title="同意申請書データの送信（プラットフォーム事業者）">
                受信した同意申請書データをJ-LISに送信し、利用者の同意を申請します。J-LISは同意データを受信後、署名検証と失効確認を行い、問題がなければ同意結果をプラットフォーム事業者へ返却します。
            </Step>
            <Step title="同意結果の取得（プラットフォーム事業者）">
                同意申請が正常に完了した場合、J-LISから同意結果（受理番号および利用者同意の有効期限）が返却されます。
            </Step>
            <Step title="同意結果の保存・返却（プラットフォーム事業者）">
              取得した同意結果をデータベースに保管・管理し、サービスプロバイダ事業者へ返却します。また、サービスプロバイダ事業者も同様に、同意結果を自社のデータベースで保管・管理する必要があります。
            </Step>
        </Steps>
    </Tab>
</Tabs>
   
## **シーケンス図**

<Tabs>
    <Tab title="対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS
    
    利用者->>サービスプロバイダ事業者: 同意取得の要求
    サービスプロバイダ事業者->>SDK: 同意・署名用電子証明書の暗証番号の要求
    SDK->>利用者: 同意取得・署名用電子証明書の暗証番号の要求
    利用者->>利用者: 利用者からの同意取得
    利用者->>利用者: 署名用電子証明書の暗証番号入力
    利用者->>SDK: 同意取得・暗証番号の送信
    SDK->>SDK: 同意申請書の生成
    SDK->>サービスプロバイダ事業者: 同意申請書の返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 同意申請書の送信
    プラットフォーム事業者->>J-LIS: 同意の申請
    J-LIS->>プラットフォーム事業者: 同意結果の取得
    プラットフォーム事業者->>プラットフォーム事業者: 同意結果の保存
    プラットフォーム事業者->>サービスプロバイダ事業者: 同意結果の返却
    サービスプロバイダ事業者->>サービスプロバイダ事業者: 同意結果の保存
```
    </Tab>
    <Tab title="非対面">
```mermaid
    %%{init:{'theme':'natural'}}%%
    sequenceDiagram
    participant 利用者
    participant SDK
    participant サービスプロバイダ事業者
    participant プラットフォーム事業者
    participant J-LIS
    
    利用者->>サービスプロバイダ事業者: 同意取得の要求
    サービスプロバイダ事業者->>SDK: 同意・署名用電子証明書の暗証番号の要求
    SDK->>利用者: 同意取得・署名用電子証明書の暗証番号の要求
    利用者->>利用者: 利用者からの同意取得
    利用者->>利用者: 署名用電子証明書の暗証番号入力
    利用者->>SDK: 同意取得・暗証番号の送信
    SDK->>SDK: 同意申請書の生成
    SDK->>サービスプロバイダ事業者: 同意申請書の返却
    サービスプロバイダ事業者->>プラットフォーム事業者: 同意申請書の送信
    プラットフォーム事業者->>J-LIS: 同意の申請
    J-LIS->>プラットフォーム事業者: 同意結果の取得
    プラットフォーム事業者->>プラットフォーム事業者: 同意結果の保存
    プラットフォーム事業者->>サービスプロバイダ事業者: 同意結果の返却
    サービスプロバイダ事業者->>サービスプロバイダ事業者: 同意結果の保存
```
    </Tab>
</Tabs>

## **実装例**
 
<Tabs>
    <Tab title="iOS">
```swift
/** SDKの処理は省略（契約後に提供される）
* 同意申請書の作成
**/
        
// エンドポイント
let endpoint = "APIのエンドポイント"

var semaphore = DispatchSemaphore(value: 0)

let parameters = """
{
    "data": "同意申請書データ"
}
"""
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
/** SDKの処理は省略（契約後に提供される）
* 同意申請書の作成
**/

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

val client = OkHttpClient()

// リクエストボディの作成
val json = JSONObject()
json.put("data", "同意申請書データ")

val mediaType = "application/json".toMediaType()
val requestBody = json.toString().toRequestBody(mediaType)

// リクエスト作成
val request = Request.Builder()
    .url(endpoint)
    .post(requestBody)
    .addHeader("X-PTS-API-Key", "<token>")
    .addHeader("Content-Type", "application/json")
    .build()

// リクエストの送信・エラー処理の記述

```
    </Tab>
    <Tab title="React Native">
```typescript
/** SDKの処理は省略（契約後に提供される）
* 同意申請書の作成
**/
        
// エンドポイント
const endpoint = 'APIのエンドポイント';

// リクエスト作成
await fetch(endpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-PTS-API-Key': '<token>',
  },
  body: JSON.stringify({
    data: consentXmlData,
  }),
});
        
// リクエストの送信・エラー処理の記述
```
    </Tab>
    <Tab title="Windows">
```
/** SDKの処理は省略（契約後に提供される）
* 同意申請書の作成
**/

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

std::string responseData;

// リクエストボディの作成
Json::Value requestBody;
requestBody["data"] = "同意申請書データ";
std::string jsonString = Json::writeString(Json::StreamWriterBuilder(), requestBody);

// リクエスト作成
CURL* curl = curl_easy_init();
if (curl) {
    struct curl_slist* headers = curl_slist_append(nullptr, "X-PTS-API-Key: <token>");
    headers = curl_slist_append(headers, "Content-Type: application/json");
    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>