券面記載事項・顔写真の検証

このページでは、Verify SDK を使用して取得した券面記載事項、氏名イメージ・顔画像、署名・証明書のデータを用いて、 第二世代在留カードの券面記載事項、氏名イメージ・顔画像のパース・検証を行う方法を説明します。

あらかじめAPI のセットアップを完了しておいてください。

プレビュー機能

SecondGenerationResidenceCardService の各メソッドは現在プレビュー機能として提供されています。SLA 対象外となり、予告なく仕様変更が行われる可能性があります。詳細はプレビュー機能の利用をご覧ください。

シーケンス

アプリとバックエンドの連携

Verify SDK を用いて取得した券面記載事項、氏名イメージ・顔画像、署名・証明書などの情報は、 何らかの方法でバックエンドサーバーに共有してデータのパース・検証を行ってください。

以下の実装例では、アプリとバックエンドの間での連携については省略しています。

要確認

Verify CardInfo API の利用は、必ず バックエンドサーバーを経由して行ってください。 API トークンをアプリケーションに含めて配布することは Verify CardInfo API の不正利用につながるため、絶対に行わないでください。

実装例

クライアントライブラリのセットアップ方法は、クライアントライブラリをご参照ください。

ParseContent は、券面記載事項・氏名イメージ・顔画像のパースに加えて、署名・証明書による署名検証を行います。 署名検証に失敗した場合はエラーが返却されます。証明書の有効期限の状態はレスポンスの certificateStatus で確認できます。

Go

package main

import (
	"context"
	"encoding/base64"
	"fmt"
	"log"
	"net/http"

	"buf.build/gen/go/pocketsign/apis/connectrpc/go/pocketsign/cardinfo/v1/cardinfov1connect"
	cardinfov1 "buf.build/gen/go/pocketsign/apis/protocolbuffers/go/pocketsign/cardinfo/v1"
	"connectrpc.com/connect"
)

var (
	// APIエンドポイントを指定します。この値は環境によって異なります。
	baseUrl = "https://verify.mock.p8n.app"

	// Verify CardInfo APIのトークンです。ご自身のトークンに置き換えてください。
	token = "<YOUR_API_TOKEN>"

	// Verify SDKによって第二世代在留カードから読み出されたデータです。これらの値は、アプリ上で作成したものを何らかの方法で予め受け取っておいてください。
	rawCardInfoContent              = "<CARD_INFO_CONTENT_BASE64>"
	rawNameImageAndFaceImageContent = "<NAME_IMAGE_AND_FACE_IMAGE_CONTENT_BASE64>"
	rawSignatureAndCertificate      = "<SIGNATURE_AND_CERTIFICATE_BASE64>"
)

func run() error {
	// Base64をデコードしてバイト列にします。
	cardInfoContent, err := base64.StdEncoding.DecodeString(rawCardInfoContent)
	if err != nil {
		return err
	}
	nameImageAndFaceImageContent, err := base64.StdEncoding.DecodeString(rawNameImageAndFaceImageContent)
	if err != nil {
		return err
	}
	signatureAndCertificate, err := base64.StdEncoding.DecodeString(rawSignatureAndCertificate)
	if err != nil {
		return err
	}

	// 第二世代在留カードパースリクエストを作成します。
	request := connect.NewRequest(cardinfov1.SecondGenerationResidenceCardServiceParseContentRequest_builder{
		// 第二世代在留カードから読み出されたデータを設定します。
		CardInfoContent:              cardInfoContent,
		NameImageAndFaceImageContent: nameImageAndFaceImageContent,
		SignatureAndCertificate:      signatureAndCertificate,
	}.Build())

	// リクエストにAPIトークンを設定します。
	request.Header().Set("Authorization", "Bearer "+token)

	// リクエストにプレビュー版にオプトインするためのヘッダを設定します。
	request.Header().Set("X-P8N-OptIn", "PREVIEW")

	// APIクライアントを作成します。
	client := cardinfov1connect.NewSecondGenerationResidenceCardServiceClient(http.DefaultClient, baseUrl)

	// 第二世代在留カードのパースリクエストを送信します。
	response, err := client.ParseContent(context.Background(), request)
	if err != nil {
		return err
	}

	// 結果を表示します。
	secondGenerationResidenceCard := response.Msg.GetSecondGenerationResidenceCard()
	cardInfo := secondGenerationResidenceCard.GetCardInfo()

	fmt.Println("証明書ステータス:", response.Msg.GetCertificateStatus())
	fmt.Println("有効期限の満了日:", cardInfo.GetExpirationDate())
	fmt.Println("生年月日:", cardInfo.GetDateOfBirth())
	fmt.Println("性別:", cardInfo.GetGender())
	fmt.Println("国籍・地域:", cardInfo.GetNationalityRegion())
	fmt.Println("在留資格:", cardInfo.GetStatusOfResidence())
	fmt.Println("在留期間:", cardInfo.GetPeriodOfStay())
	fmt.Println("在留資格許可の種類:", cardInfo.GetPermissionType())
	fmt.Println("在留資格許可年月日:", cardInfo.GetPermissionDate())
	fmt.Println("就労制限の有無:", cardInfo.GetWorkRestriction())
	fmt.Println("在留期間の満了日:", cardInfo.GetPeriodOfStayExpirationDate())
	fmt.Printf("氏名イメージ: %s\n", base64.StdEncoding.EncodeToString(secondGenerationResidenceCard.GetNameImage()))
	fmt.Printf("顔画像: %s\n", base64.StdEncoding.EncodeToString(secondGenerationResidenceCard.GetFaceImage()))
	return nil
}

func main() {
	if err := run(); err != nil {
		log.Fatalln(err)
	}
}

パース・検証に成功すると、以下のように結果が表示されます。

取得した第二世代在留カードの券面記載事項や顔画像は、本人確認などに利用できます。

証明書ステータス: RESIDENCE_CARD_CERTIFICATE_STATUS_GOOD
有効期限の満了日: 20301231
生年月日: 19980107
性別: 1
国籍・地域: USA
在留資格: X14
在留期間: 0000
在留資格許可の種類: AK
在留資格許可年月日: 20250101
就労制限の有無: 2
在留期間の満了日: 20301231
氏名イメージ: SUkqADYBAAD//OoIahDghOMkDJxkgZmIcGQgIaxDghOMkDJxkgZm...（省略）
顔画像: AAAADGpQICANCocKAAAAFGZ0eXBqcDIgAAAAAGpwMiAAAAAtanAyaAA...（省略）

備考

1 歳の誕生日の半年前より前に交付されたカードには顔画像が格納されていないため、faceImage は空になります。 容貌一致確認などに顔画像を利用する場合は、顔画像が空であるケースのハンドリングを実装してください。

注意

certificateStatus はカードに格納された公開鍵証明書の有効期限の状態を表します。

• GOOD: 証明書は有効期限内です。
• EXPIRED: 証明書の有効期限が切れています。

署名検証に成功していれば、証明書が有効期限切れであってもエラーにはならず、パース結果とあわせて EXPIRED が返却されます。

また、1 歳の誕生日の半年前より前に交付された第二世代在留カード等には署名・公開鍵証明書が格納されておらず署名検証を実施できないため、certificateStatus は設定されません。この場合もパース結果は返却されます。

備考

読み出した氏名イメージ・住居地イメージの画像形式は TIFF 形式（MMR 圧縮）となります。利用する際には TIFF 形式の画像を取り扱えるライブラリを使用してください。

また、顔画像の画像形式は JPEG2000 形式となります。利用する際には JPEG2000 形式の画像を取り扱えるライブラリを使用してください。

券面記載事項の値

券面記載事項の各項目は、コード値または固定書式の文字列として返却されます。 画面表示や資格の判定に利用する際は、値をそのまま表示せず、コード値の意味を解釈してください。

項目	メソッド名	値の形式
有効期限の満了日	GetExpirationDate	YYYYMMDD
生年月日	GetDateOfBirth	YYYYMMDD
性別	GetGender	1: 男、2: 女、3: 不詳
国籍・地域	GetNationalityRegion	国籍・地域コード
在留資格	GetStatusOfResidence	在留資格期間コード
在留期間	GetPeriodOfStay	YYMM または DDD。無期限の場合は 0000
在留資格許可の種類	GetPermissionType	許可の種類コード
在留資格許可年月日	GetPermissionDate	YYYYMMDD
就労制限の有無	GetWorkRestriction	1 / 2 / 4 / 9 のいずれか
在留期間の満了日	GetPeriodOfStayExpirationDate	YYYYMMDD

国籍・地域コード、在留資格期間コード、許可の種類コードは公開されておらず、出入国在留管理庁からコード表データの貸与を受ける必要があります。 貸与の申出方法については、出入国在留管理庁が公開している第二世代在留カード等仕様書の公開についての「コード表データの貸与」をご確認ください。

注記

第二世代特別永住者証明書には在留資格許可の種類・在留資格許可年月日・就労制限の有無・在留期間の満了日の項目が存在しないため、これらは未設定（空文字列）で返却されます。 カード種別による違いについてはデータの利用の流れ > カード種別による読み出し可能なデータの違いをご覧ください。

その他のデータのパース

readSecondGenerationResidenceCardContent 以外の読み出しで取得したデータは、以下のメソッドでパースします。 いずれも SecondGenerationResidenceCardService のメソッドです。

Verify SDK の読み出し	Verify CardInfo API のメソッド	パース結果
readResidenceCardNumberContent	ParseCardNumberContent	在留カード等番号
readAddressImageContent	ParseAddressImageContent	住居地イメージ
readActivityPermissionContent	ParseActivityPermissionContent	資格外活動許可欄（包括許可・個別許可）
readApplicationStatusForExtensionOfPeriodOfStayContent	ParseApplicationStatusForExtensionOfPeriodOfStayContent	在留期間等更新申請欄
readMiscellaneousContent	ParseMiscellaneousContent	その他の記載事項

ParseContent 以外のメソッドは署名検証を行わず、データのパースのみを行います。 署名検証は ParseContent で券面記載事項・氏名イメージ・顔画像に対して行われます。

---

次のステップ

その他、API の詳しい使い方やエラーの詳細等については、API リファレンスをご覧ください。