第２回 SmartHRのライブラリkijiを使ってe-Govを動かす（e-Gov公開資料編）

一般ソフトウェア開発事業者等が、e-Gov外部連携APIを利用したソフトウェアサービスを開発するための流れ及び公開資料を紹介します。

本編以外にも、[e-Gov仕様編](https://qiita.com/itaruMatumoto/items/a4a4d74b5a1ff9ea0b8b "第１回 SmartHRのライブラリkijiを使ってe-Govを動かす（e-Gov仕様編）")、[実行環境構築編](https://qiita.com/itaruMatumoto/items/33dc5131ffc08f349448 "第３回 SmartHRのライブラリkijiを使ってe-Govを動かす（実行環境構築編）")、[動作確認編](https://qiita.com/itaruMatumoto/items/318c9aaa74d238b58941 "第４回 SmartHRのライブラリkijiを使ってe-Govを動かす（動作確認編）")がありますので、必要に応じて参照して下さい。

# １．開発の流れ
一般ソフトウェア開発事業者等（以下、開発事業業者）は、e-Gov（総務省）にソフトウェア開発の申込を行う必要があります。

①ソフトウェア開発の申込を行う
②e-Govから検証環境利用申込に関する書類が送られてくる
③開発事業者は必要事項（利用者ID等）記入の上、検証環境利用申込書をe-Govに送る
④e-Govから検証環境に関する資料が送られてくる
⑤開発事業者はソフトウェアサービスを開発する
⑥開発事業者は最終確認試験の申込を行う
⑦開発事業者は最終確認試験結果を提出する
⑧e-Govからの合格判定によりソフトウェアサービスが使用可能になる

③にて、開発事業者は検証環境利用申込書に次の内容を記載します。

| No | 検証環境利用申込書に記入する内容 |
|:--:|:-------|
| 1 | 法人団体名 |
| 2 | ソフトウェア名 |
| 3 | 利用者ID（最大3名まで申請可能） |
| 4 | 検証環境で利用する外部連携APIを〇で指定する。利用者ID登録、利用者認証、一括申請については必須となる。 |

④にて、e-Govから検証環境に関する資料が送られてきます。開発事業者は、これらの情報を厳重に管理する必要があります。

| No | 検証環境に関する資料 |
|:--:|:-------|
| 1 | 検証環境利用通知書（検証環境URL、ソフトウェアID、利用者ID、Basic認証用ID及びパスワード） |
| 2 | APIテスト用データ情報（ソフトウェアIDだけが使える補正通知一覧取得API、部分補正API、補正再提出API向けのテストデータ） |
| 3 | 最終確認試験テスト仕様書兼成績書 |

検証環境URLについては、本番環境とは異なるリクエストURLとなります。このタイミングでは、検証環境利用申込書に記載した利用者IDがe-Govに登録されており、この利用者IDに紐づいて次の証明書が管理されています。

| 証明書の状態 | 証明書ファイル名 |
|:--:|:-------|
| 有効 | e-GovEE01_sha2.pfx |
| 有効期間切れ | e-GovEE04_sha2.pfx |
| 失効 | e-GovEE05_sha2.pfx |

# ２．公開資料について
e-Govから開発事業者向けに用意された資料が[ダウンロード](https://www.e-gov.go.jp/shinsei/interface_api/download.html)できます。ここには、利用ガイド、規約、申込書、仕様書、検証環境テスト用電子証明書等があります。

| No | 利用ガイド、申込様式等 |
|:--:|:-------|
| 1 | 外部連携API　API概要 |
| 2 | 外部連携API　利用ガイド |
| 3 | 外部連携API　各種申込書（一式）|
| 4 | 外部連携API　利用規約 |
| 5 | 外部連携API　個人情報の取扱について |

| No | 仕様書、申請書XML構造定義 |
|:--:|:-------|
| 1 | 外部連携API　API（Version 1）仕様書 |
| 2 | 外部連携API　情報セキュリティ要求仕様書 |
| 3 | 外部連携API　申請データ仕様共通データ仕様書 |
| 4 | 対象手続一覧 |
| 5 | 手続情報一覧／提出先一覧（一式）|
| 6 | 申請書XML構造定義【社会保険関係手続】（一式）|
| 7 | 申請書XML構造定義【雇用保険関係手続】（一式）|
| 8 | 申請書XML構造定義【労働保険適用徴収関係手続】（一式）|

| No | 検証環境テスト用手続 |
|:--:|:-------|
| 1 | APIテスト用手続一覧|
| 2 | APIテスト用手続一覧（別紙　APIテスト用手続ステータス遷移一覧）|
| 3 | 申請書XML構造定義【APIテスト用手続き】|

| No | 検証環境テスト用電子証明書 |
|:--:|:-------|
| 1 | 電子証明書 |

ここでは、仕様書、検証環境テスト用手続、電子証明書について紹介します。

## ２．１ 仕様書
### （１）API（Version 1）仕様書
APIを利用して電子申請を行うためのリクエストURIとそのパラメタ、httpリクエストボディに指定する送信XML及びe-Govが返却するレスポンスボディ（応答XML）に関する仕様について記載されています。

### （２）情報セキュリティ要求仕様書
開発事業者がソフトウェアを開発する上で遵守すべきセキュリティ要求事項について記載されています。

### （３）申請データ仕様共通データ仕様書
全手続共通のデータ仕様及び各手続毎の個別仕様について記載されています。
構成管理XML、構成情報XML、申請書XMLについて、XMLのタグ構造が定義されています。

### （４）申請データ仕様及び申請書XML構造定義書
各手続毎の申請データに関する個別仕様が記載されています。

## ２．２ 検証環境テスト用手続
検証環境にて、外部連携APIに係るテストを行う際に利用できるテスト用手続に関する公開仕様です。

| No | 申請書XML構造定義【APIテスト用手続き】 |
|:--:|:-------------------------------------|
| 1 | APIテスト用手続一覧|
| 2 | APIテスト用手続一覧（別紙　APIテスト用手続ステータス遷移一覧）|
| 3 | 申請書XML構造定義【APIテスト用手続】|

- 検証環境では、正常系及びエラー系合わせて、標準形式３８種類、個別署名形式４５種類の労働・社会保険関係の手続が用意されています
- 各手続には、手続に関する条件（署名有無、添付書類、提出先、取り下げ等）、到達以降の可能処理等が定義されています
- 各手続は３２の様式パターンのいずれかに属しており、様式パターンの内容に従ってデータ項目を設定する必要があります

「APIテスト用手続き一覧」では、テスト用手続について次の内容を確認できます。

- 各手続の申請書様式は、APIに係るテストを行う上で必要なテストケースを網羅できるようにパターン化し、適切な手続き情報を設定して整備しています。
- 公文書発出対象の手続、コメント通知対象の手続については、それぞれサンプルの公文書及びコメント内容が通知されます。
- 添付書類として許容しているファイル形式の拡張子は、「doc」、「xls」、「pdf」、「docx」、「xlsx」、「txt」です。
- 手続識別子の上３桁が「950」の手続については、申請後のステータスが自動的に遷移されます。

「APIテスト用手続一覧（別紙　APIテスト用手続ステータス遷移一覧）」では、ステータスの自動遷移について確認できます。以下2例ほど紹介します。

- 標準形式のうち、手続識別子＝950A010002010000については、手続名「健康保険・厚生年金保険事業所関係変更（訂正）届／電子申請」であり、公文書が発出されます。ソフトウェアサービスが一括申請を行うと（到達）→（審査中）→（審査終了）と自動的に遷移し、（審査終了）になった時に公文書を取得する事ができます。
- 標準形式のうち、手続識別子＝950A010700007000については、手続名「健康保険・厚生年金保険被保険者資格取得届、船員保険・厚生年金保険被保険者資格取得届／電子申請」であり、公文書は発出されません。ソフトウェアサービスが一括申請を行うと（到達）→（審査中）と自動的に遷移します。さらにソフトウェアサービスが、到達番号を指定して取下げ依頼を行うと、（審査中-取下げ処理中）→（手続終了-取下げ済み）に自動遷移します。

## ２．３ 電子証明書
検証環境で使用するSHA-256版の電子証明書について説明します。

| No | ファイル名 | 説明 |
|:--:|:----------|:-----|
| 1 | e-GovEE01_sha2.pfx |利用者IDに予め設定される有効な証明書|
| 2 | e-GovEE02_sha2.pfx |有効な証明書|
| 3 | e-GovEE03_sha2.pfx |有効な証明書|
| 4 | e-GovEE04-1_sha2.pfx |利用者IDに予め設定される有効期限の切れた証明書|
| 5 | e-GovEE04-2_sha2.pfx|有効な証明書|
| 6 | e-GovEE05_sha2.pfx|利用者IDに予め設定される失効している証明書|

電子証明書のサフィックスは証明書のフォーマットを表します。「.pfx」は、PKCS#12(PFX)形式の鍵と証明書のフォーマットであり、サーバの鍵を証明書チェーン全体と一緒に格納して保護できる形式です。Microsoft社製品でよく使われる形式です。

opensslコマンドを使って、証明書の内容を確認します。途中でパスワードが求められた場合、「gpkitest」と入力します。

```:opensslの実行結果
>openssl pkcs12 -info -in e-GovEE01_sha2.pfx
Enter Import Password:（「gpkitest」と入力）
MAC Iteration 2000
MAC verified OK
PKCS7 Data
Shrouded Keybag: pbeWithSHA1And3-KeyTripleDES-CBC, Iteration 2000
Bag Attributes
    localKeyID: 01 00 00 00
    friendlyName: le-d39d0281-d8cb-4396-b002-b4366119c8e4
    Microsoft CSP Name: Microsoft Enhanced Cryptographic Provider v1.0
Key Attributes
    X509v3 Key Usage: 10
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQITLitdILmV8cCAggA
MBQGCCqGSIb3DQMHBAiXSoB8We54iwSCBMiWf80URxShHlnQltb0fsWst7cAZF2D
/FnXM/8RRrMuK561dB5f+7ImMTtJobdOYOEpeO8sqxhGGeEnivFPMhvrsdGKMZul
nCoQBk0ug0iG2vnlQZAP6RPhbo9u4H3ZtTxJeO4DnYdJJj681vxlkEwhQ+Xv7arV
ZkDAmP20E3tKsobuIKNoLDF6HvrsW6k3bSeYcQqjm71BUAZe9DR2JnBNilbnN7gn
NXtsl8B2bGj8/bATsF37elW/zRkm+35vhcV4jLOEJY67ZF9uVAmSgjGXDuEo3pWO
jrX3t5ErsDXXObjw35cVVTvXUZl6s98p2QC3D/hThUf+MBE+pjO3AnNdb0Pjikmf
Fx1VSaeRW1vpf6/oOdwBUGPJuUXyZm1t93/AiYMOG5r9UFLRoFoHKYeCUte+BO2o
N6M2wUSgekzQejrZeT6ATvRpA15yQ6laAFw6LwPRbJ3zykCch2UAPJaspXgUzdfA
9jGzGuq9xIOgeVe+Gi2OdLBk+hAc0qF+zkrwuhswWT3vSSNQ2/mlfl3kI7MPzcvB
82mzC0aPCts8oG0JVL3m/WpnfO6XFnB5GRB10mo7NyiecjHOEPCfsjOcsTr/Bl1N
EPkh4Rt+o315l4UFtIw8nfK8xiw9ag6Lc8n3IUy9+fUWe/MmZxsvKfMyUe8x8RJA
gubv1R8RUqPg+rq6rCydlPE3RlMwro5ooF5sblWANPpNJwyTOr1CEJHTyWzzdMnz
pdbVj0Tz9P3YvR9+KUmv5FPO+Ke/G0KLVbvg14OUfTr5xFEihUrYPOWtRlGlGOyT
le+rGFAzIsRTJvFU6RGsktGTXyzmPBxY2YPuTnDnkdUCLl8UIcXUPMeWRSIh5YC0
zpPgwLlDdy0dnDSIYo5j2yjhYCYcx0MkkZpkn896RcFkK/QnX5L+EvCz6GIZVxAi
yEzD6lFs4Uamm7E/6MbfyoxxbfIOq8BKoufhSbu/QzUlVw/f1+HXjROaTjB2zRuo
GmuWMugdhEMkKl1R4MTpIhoORdQNYGRWcJfbvSZx6gAmTDMoYkt5h05+haNyXY3t
VkLIlHnpRcQR+JgFghyp0j49kmgyKjRZ6XyCgRnUazE9GOalCZLRZuFQEIlgjNRQ
i5f+LI1UNULxD3PJR8A6AMXiasfk94t4qlpH5xc2HVC44Hrk/gX9vfIYBodw43qX
/r0Z2H/27Qte0IRAZ3jzBV46wN2Y0fqKVQNFchIIJleSebd/ka317ICI8gphf+Js
7Y//jUfl03X7oB2GviVHNzvtjJy0AgAlHkltEgswSbWmd3e+lsCtRpnpe4f1qj76
nYTy0AYtvcZwsE7EaCDYGz/KGQVJjorKVgK12N27catPUcDX3NPMhv9YVe1rcVhT
Iku2X6b0c+YmDSGs05m0LUp8HMN/RUAVg+77atjBT72yqABzV2OcZDc9vHCZfYg2
hO/NSfITPB/Jun/gd4VgjH8sO9Eupa/DgZKQ7b858Md6kjK37iKu8cxvG9VfizFj
/msgnKpZmB0lXnvb7hQUgbeOXC0HP1VswZqq1JBzvFICcFo+4KZQquig2SJytR5o
bFxOWp1zXMllQWSunt1aMnmun/B68BU6SiNXNjnTn+gAd+i3avys8X1VLZBFAwKF
6wY=
-----END ENCRYPTED PRIVATE KEY-----
PKCS7 Encrypted data: pbeWithSHA1And40BitRC2-CBC, Iteration 2000
Certificate bag
Bag Attributes
    localKeyID: 01 00 00 00
subject=/C=JP/O=DemoMin1/OU=CA1/CN=Ichiro Madoguchi
issuer=/C=JP/O=DemoMin1/OU=CA1
-----BEGIN CERTIFICATE-----
MIIEizCCA3OgAwIBAgIEWCsMRzANBgkqhkiG9w0BAQsFADAuMQswCQYDVQQGEwJK
UDERMA8GA1UECgwIRGVtb01pbjExDDAKBgNVBAsMA0NBMTAeFw0xOTEwMjUwMTE2
NTZaFw0yNDEwMjQxNDU5NTlaMEkxCzAJBgNVBAYTAkpQMREwDwYDVQQKDAhEZW1v
TWluMTEMMAoGA1UECwwDQ0ExMRkwFwYDVQQDDBBJY2hpcm8gTWFkb2d1Y2hpMIIB
IjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsD81VFFmGM26HYdeGrGzbPba
deBzU4WxIE1r6qeZLxjz7DiV42tjo8QFulWZk6hmCeb5j9ChKp+BA/9Yj6usccKH
ZrPQmbcXUZkXRXz9z/7CLxp8b1zAzJakZ0g7o9iU3a3TpyeP6V+GFtkO8YqfthEs
JsYzx82dUi85Bm4l5pnztozPdXRZd2VJpdwzGqtqw6N9PKzMNWux5C0jklkaPeP5
P6NHLfeN51+phkY2xkdJlry629PeKjZAwN0Z8Xu0JdubCvA95UctoZgBoOjpgDtW
ImV3o9hDpwu+1tMlEBhNZIuKOr2G38qRZ9iJUyoK+XhbzyBUu0A2cwCj0MshbwID
AQABo4IBlDCCAZAwDgYDVR0PAQH/BAQDAgbAMBEGCWCGSAGG+EIBAQQEAwIGQDBO
BgNVHRIERzBFpEMwQTELMAkGA1UEBhMCSlAxHjAcBgNVBAoMFeaooeaTrOawkemW
k+iqjeiovOWxgDESMBAGA1UECwwJ77yj77yh77yRMB8GA1UdIAEB/wQVMBMwEQYP
AoM4ho4xCAEBAAKMmyVkMGgGA1UdEQRhMF+kXTBbMQswCQYDVQQGEwJKUDEeMBwG
A1UECgwV5qih5pOs5rCR6ZaT6KqN6Ki85bGAMRIwEAYDVQQLDAnvvKPvvKHvvJEx
GDAWBgNVBAMMD+eqk+WPo+OAgOS4gOmDjjBQBgNVHR8ESTBHMEWgQ6BBpD8wPTEL
MAkGA1UEBhMCSlAxETAPBgNVBAoMCERlbW9NaW4xMQwwCgYDVQQLDANDQTExDTAL
BgNVBAMMBENSTDEwHwYDVR0jBBgwFoAUFNPnlvRSx8XFOnRlLumW95h4I18wHQYD
VR0OBBYEFD6UH9Exye9dEpz9MHJ3sbUDpoZSMA0GCSqGSIb3DQEBCwUAA4IBAQBb
CKyFGsqMv6+HkrY0OK+4v40PJQAa/KbOC3JTKooLfNCNXTiTwtWAl1sGN+Ow8pIp
8Yvj16VcYpi8zO4TmNe8NT+u/e2OvBXwJ9OxOs9UNI2m/mXGcSSJ7eXMR3aVCniD
U7IaQeicquQttLP9IOk9Ao1W+BM35y5bITA/BMO5tzgaimp4G484QtF/XLi40rGh
aZAHGEfvl0abJXPumjajhnGv7SCkjw4+9qdz5Dtp6kl+GVshQgo6ofpEWhVzdhfq
KhNy8dNRL7C/gOTYm+M9SAFk9syL5xKXRyMUGDOheypiJrW/QyOjrxs6cFa5VqaZ
WcRIq8yVPwABCpGG/hjU
-----END CERTIFICATE-----
```

- 「-----BEGIN ENCRYPTED PRIVATE KEY-----」から「-----END ENCRYPTED PRIVATE KEY-----」で囲まれている部分が秘密鍵です。
- 「-----BEGIN CERTIFICATE-----」から「-----END CERTIFICATE-----」で囲まれている部分が証明書（公開鍵）です。
- subjectは証明される人、issuerは証明する人を意味します。
- subject=/C=JP/O=DemoMin1/OU=CA1/CN=Ichiro Madoguchi、issuer=/C=JP/O=DemoMin1/OU=CA1であり、テスト向けの自己署名証明書なので、発行者（issuer）と主体者（Subject）が同じ組織です。

e-Govでは、ソフトウェア開発事業者が検証環境利用申し込み時に希望した利用者IDに紐づけて、３つの証明書を管理した状態になっています。有効な証明書については、通常テストで利用します。また、有効期限の切れた証明書及び失効している証明書については、e-Govで管理する証明書を更新するテストで利用します。

| 証明書の状態 | 証明書ファイル名 |
|:--:|:-------|
| 有効 | e-GovEE01_sha2.pfx |
| 有効期間切れ | e-GovEE04_sha2.pfx |
| 失効 | e-GovEE05_sha2.pfx |

# ３．最終確認試験について
最終確認試験については、ソフトウェアサービスとe-Gov間のデータ送受信がe-Govの仕様に従って問題なく出来ているかを確認します。ソフトウェアサービスのアプリケーションとしての機能を確認するものではありません。

SmartHRのライブラリkijiでは、RSpecを利用して最終確認試験を自動化しています。

| No | API名称 | 確認するための条件 | HTTPレスポンスコード|
|--:|:--|:--|:--|
| 1 | 利用者ID登録 | 追加する利用者IDを指定 | "201"であること |
| 2 | 利用者認証 | e-Govに登録済みの利用者IDを指定 | "200"であること |
| 3 | 一括申請 | 一括申請ファイルを指定 | "202"であること |
| 4 | 送信案件一覧情報取得 (ID指定) | 一括申請時の送信番号を指定 |"200"であること |
| 5 | 送信案件一覧情報取得 (日付指定) | 取得対象期間を指定 | "200"であること |
| 6 | 申請案件一覧情報取得 | 一括申請時の送信番号を指定 | "200"であること |
| 7 | 状況照会 | 申請案件一覧情報取得で取得した到達番号を指定 | "200"であること |
| 8 | 取下げ | 取下げ可能な到達番号の取下げデータを指定 | "200"であること |
| 9 | 補正通知一覧取得 | 状況照会の補正可能な到達番号を指定 | "200"であること |
| 10 | 補正(再提出) | 補正(再提出)可能な到達番号を指定 | "202"であること |
| 11 | 補正(部分補正) | 補正(部分補正)可能な到達番号を指定 | "202"であること |
| 12 | 補正(補正申請) | 補正(補正申請)可能な到達番号を指定 | "202"であること |
| 13 | 公文書・コメント一覧取得 | 状況照会の公文書メッセージが設定された到達番号を指定 | "200"であること |
| 14 | 公文書取得 | 取得期限内の通知番号の公文書を指定 | "200"であること |
| 15 | 公文書取得完了 | 公文書取得で取得した公文書を指定 | "200"であること |
| 16 | 公文書署名検証 | 公文書取得で取得した公文書を指定 | "200"であること |
| 17 | コメント通知取得 | 取得期限内の通知番号のコメント通知を指定 | "200"であること |
| 18 | コメント通知取得完了 | コメント通知取得で取得したコメント通知を指定 | "200"であること |
| 19 | 電子納付対応金融機関一覧取得 | － | "200"であること |
| 20 | 電子納付情報一覧取得 | 納付可能な到達番号を指定 | "200"であること |
| 21 | 証明書識別情報追加 | 新規登録する証明書を指定 | "200"であること |
| 22 | 証明書識別情報更新 | 更新登録する証明書を指定 | "200"であること |
| 23 | 証明書識別情報削除 | 削除する証明書を指定 | "200"であること |

次は[実行環境構築編](https://qiita.com/itaruMatumoto/items/33dc5131ffc08f349448 "第３回 SmartHRのライブラリkijiを使ってe-Govを動かす（実行環境構築編）")に続きます。