- 印刷する
- PDF
外国人登録証
- 印刷する
- PDF
Classic/VPC環境で利用できます。
特化モデルエンジンを使用して外国人登録証の入力情報(key-value)を認識し、抽出します。
リクエスト
リクエスト形式を説明します。リクエスト形式は次の通りです。
メソッド | URI |
---|---|
POST | /id-card |
リクエストヘッダ
CLOVA OCR APIで共通して使用されるヘッダの詳細は、CLOVA OCRのリクエストヘッダをご参照ください。
リクエストボディ
リクエストボディの説明は次の通りです。
Content-Type: application/json
の場合
リクエストヘッダのContent-Type
がapplication/json
の場合のリクエストボディの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
version | String | - | バージョン情報
|
requestId | String | Required | 任意の API呼び出しの UUID |
timestamp | Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
images | Array | Required | imagesの詳細情報 |
Content-Type: multipart/form-data
の場合
リクエストヘッダのContent-Type
がmultipart/form-data
の場合のリクエストボディの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
message | Object | Required | リクエストデータ情報 |
message.version | String | Required | バージョン情報
|
message.requestId | String | Required | 任意の API呼び出しの UUID |
message.timestamp | Integer | Required | 任意の APIの呼び出し時刻(Timestamp) |
message.images | Array | Required | imagesの詳細情報 |
file | File | Required | OCR認識画像ファイル |
images
images
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
format | String | Required | 画像の形式
|
name | String | Required | 任意の画像名
|
data | String | Required | Base64でエンコードされた画像データ
|
リクエスト例
リクエストのサンプルコードは次の通りです。
Content-Type: application/json
の場合
リクエストヘッダのContent-Type
がapplication/json
の場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
"version": "V2",
"requestId": "string",
"timestamp": 0,
"images": [
{
"format": "png",
"name": "alienRegistration_test",
"data":"{Base64でエンコードされた画像データ}"
}
]
}'
Content-Type: multipart/form-data
の場合
リクエストヘッダのContent-Type
がmultipart/form-data
の場合のリクエストのサンプルコードは次の通りです。
curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/id-card' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 0, \"images\": [{\"format\": \"png\", \"name\": \"alienRegistration_test\"}]}"' \
--form 'file=@"{file}"'
レスポンス
レスポンス形式を説明します。
レスポンスボディ
レスポンスボディの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
version | String | - | バージョン情報
|
requestId | String | - | API呼び出し UUID |
timestamp | Integer | - | APIの呼び出し時刻(Timestamp) |
images | Array | - | imagesの詳細情報 |
images
images
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
uid | String | - | 外国人登録証画像の UID
|
name | String | - | 外国人登録証の画像名
|
inferResult | String | - | 外国人登録証の画像認識結果
|
message | String | - | 結果メッセージ |
validationResult | Object | - | 有効性検査の結果情報 |
validationResult.result | String | - | 有効性検査の結果コード
|
validationResult.message | String | - | 有効性検査結果の詳細メッセージ
|
convertedImageInfo | Object | - | 変換後の画像情報
|
convertedImageInfo.width | Integer | - | 変換後画像の横長 |
convertedImageInfo.height | Integer | - | 変換後画像の縦長 |
convertedImageInfo.pageIndex | Integer | - | 変換後画像ページインデックス |
idCard | Object | - | 身分証明書の詳細情報 |
idCard.meta | Object | - | メタ情報 |
idCard.meta.estimatedLanguage | String | - | OCR推定言語
|
idCard.result | Object | - | 身分証明書の OCR認識結果 |
result
result
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
isConfident | Boolean | - | 各タイプの詳細情報を保有するかどうか
|
ac | Object | - | 外国人登録証情報 |
ac.personalNum | Array | - | 外国人登録証の詳細情報 |
ac.sex | Array | - | 性別の詳細情報 |
ac.name | Array | - | 氏名の詳細情報 |
ac.nationality | Array | - | 国籍の詳細情報 |
ac.visaType | Array | - | ビザタイプの詳細情報 |
ac.issueDate | Array | - | 発行日の詳細情報 |
ac.authority | Array | - | 発行機関の詳細情報 |
ac.authorityEng | Array | - | 発行機関の詳細情報(英語) |
ac.alienRegNumEtc | Array | - | 外国人登録番号のその他の詳細情報 |
rois | Array | - | オブジェクト枠線の位置情報 |
idType | String | - | 身分証明書タイプ
|
alienRegNum
ac.alienRegNum
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の番号テキスト |
formatted | Object | - | 認識結果の番号テキスト情報 |
formatted.value | String | - | 認識結果の番号テキストの値 |
keyText | String | - | 認識結果の番号テキストのキー |
confidenceScore | Float | - | 認識結果の番号テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
sex
ac.sex
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の性別テキスト |
formatted | Object | - | 認識結果の性別テキスト情報 |
formatted.value | String | - | 認識結果の性別テキストの値 |
keyText | String | - | 認識結果の性別テキストのキー |
confidenceScore | Float | - | 認識結果の性別テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
name
ac.name
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の名前テキスト |
formatted | Object | - | 認識結果の名前テキスト情報 |
formatted.value | String | - | 認識結果の名前テキストの値 |
keyText | String | - | 認識結果の名前テキストのキー |
confidenceScore | Float | - | 認識結果の名前テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
nationality
ac.nationality
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の国籍テキスト |
formatted | Object | - | 認識結果の国籍テキスト情報 |
formatted.value | String | - | 認識結果の国籍テキストの値 |
keyText | String | - | 認識結果の国籍テキストのキー |
confidenceScore | Float | - | 認識結果の国籍テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
visaType
ac.visaType
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果のビザタイプテキスト |
formatted | Object | - | 認識結果のビザタイプテキスト情報 |
formatted.value | String | - | 認識結果のビザタイプテキストの値 |
keyText | String | - | 認識結果のビザタイプテキストのキー |
confidenceScore | Float | - | 認識結果のビザタイプテキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
num
pp.num
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の番号テキスト |
formatted | Object | - | 認識結果の番号テキスト情報 |
formatted.value | String | - | 認識結果の番号テキストの値 |
keyText | String | - | 認識結果の番号テキストのキー |
confidenceScore | Float | - | 認識結果の番号テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
日付オブジェクト情報
日付オブジェクトの説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の日付テキスト |
formatted | Object | - | 認識結果の日付テキスト情報 |
formatted.year | String | - | 認識結果の日付の年度(yyyy) |
formatted.month | String | - | 認識結果の日付の月(MM) |
formatted.day | String | - | 認識結果の日付の日(dd) |
keyText | String | - | 認識結果の発行テキストのキー |
confidenceScore | Float | - | 認識結果の日付テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
authority
ac.authority
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の発行機関テキスト |
formatted | Object | - | 認識結果の発行機関テキスト情報 |
formatted.value | String | - | 認識結果の発行機関テキストの値 |
keyText | String | - | 認識結果の発行機関テキストのキー |
confidenceScore | Float | - | 認識結果の発行機関テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
authorityEng
ac.authorityEng
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果の発行機関テキスト(英語) |
formatted | Object | - | 認識結果の発行機関テキスト情報 |
formatted.value | String | - | 認識結果の発行機関テキストの値 |
keyText | String | - | 認識結果の発行機関テキストのキー |
confidenceScore | Float | - | 認識結果の発行機関テキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
alienRegNumEtc
ac.alienRegNumEtc
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
text | String | - | 認識結果のテキスト |
formatted | Object | - | 認識結果のテキスト情報 |
formatted.value | String | - | 認識結果のテキストの値 |
keyText | String | - | 認識結果のテキストのキー |
confidenceScore | Float | - | 認識結果のテキストの信頼度
|
boundingPolys | Array | - | boundingPolyの詳細情報 |
maskingPolys | Array | - | maskingPolyの詳細情報 |
rois
rois
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
フィールド | タイプ | 必須の有無 | 説明 |
--- | --- | --- | --- |
x | Float | - | オブジェクト枠線の位置 X軸の座標 |
y | Float | - | オブジェクト枠線の位置 Y軸の座標 |
boundingPolys
boundingPolys
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
vertices | Array | - | verticesの詳細情報 |
maskingPolys
maskingPolys
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
vertices | Array | - | verticesの詳細情報 |
boundingPolyVertices
boundingPolyVertices
の説明は次の通りです。
フィールド | タイプ | 必須の有無 | 説明 |
---|---|---|---|
x | Float | - | X軸の座標 |
y | Float | - | Y軸の座標 |
レスポンスステータスコード
CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。
レスポンス例
レスポンスのサンプルコードは次の通りです。
成功
呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725415136556,
"images": [
{
"uid": "{uid}",
"name": "alienRegistration_test",
"inferResult": "SUCCESS",
"message": "SUCCESS",
"validationResult": {
"result": "NO_REQUESTED"
},
"idCard": {
"meta": {
"estimatedLanguage": "ko"
},
"result": {
"isConfident": true,
"ac": {
"alienRegNum": [
{
"text": "123***-123****",
"formatted": {
"value": "123***-123****"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 250.44644,
"y": 86.428566
},
{
"x": 399.24106,
"y": 86.428566
},
{
"x": 399.24106,
"y": 104.10713
},
{
"x": 250.44644,
"y": 104.10713
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 323.0759,
"y": 84.660706
},
{
"x": 401.0089,
"y": 84.660706
},
{
"x": 401.0089,
"y": 105.874985
},
{
"x": 323.0759,
"y": 105.874985
}
]
}
]
}
],
"sex": [
{
"text": "F",
"formatted": {
"value": "F"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 457.27267,
"y": 86.69321
},
{
"x": 491.81177,
"y": 87.496445
},
{
"x": 491.4664,
"y": 102.34618
},
{
"x": 456.92734,
"y": 101.542946
}
]
}
],
"maskingPolys": []
}
],
"name": [
{
"text": "HONG S*******",
"formatted": {
"value": "HONG S*******"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 250.30173,
"y": 137.56241
},
{
"x": 307.85138,
"y": 136.8519
},
{
"x": 308.07855,
"y": 155.25519
},
{
"x": 250.52892,
"y": 155.96568
}
]
}
],
"maskingPolys": []
}
],
"nationality": [
{
"text": "REPUBLIC OF UTOPIA",
"formatted": {
"value": "REPUBLIC OF UTOPIA"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 251.42857,
"y": 180.71428
},
{
"x": 344.24106,
"y": 180.71428
},
{
"x": 344.24106,
"y": 198.88393
},
{
"x": 251.42857,
"y": 198.88393
}
]
}
],
"maskingPolys": []
}
],
"visaType": [
{
"text": "企業投資(D-8)",
"formatted": {
"value": "企業投資(D-8)"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 250.44643,
"y": 225.40178
},
{
"x": 312.8125,
"y": 225.40178
},
{
"x": 312.8125,
"y": 245.04465
},
{
"x": 250.44643,
"y": 245.04465
}
]
}
],
"maskingPolys": []
}
],
"issueDate": [
{
"text": "2011.1.1 1234.",
"formatted": {
"year": "2011",
"month": "01",
"day": "01"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 71.69643,
"y": 292.67856
},
{
"x": 102.63393,
"y": 292.67856
},
{
"x": 102.63393,
"y": 302.00894
},
{
"x": 71.69643,
"y": 302.00894
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 69.91906,
"y": 290.60785
},
{
"x": 485.82584,
"y": 262.38263
},
{
"x": 486.8961,
"y": 278.1529
},
{
"x": 70.989296,
"y": 306.3781
}
]
}
]
}
],
"authority": [
{
"text": "ソウル出入国・外国人庁庁長",
"formatted": {
"value": "ソウル出入国・外国人庁庁長"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 300.07544,
"y": 285.12625
},
{
"x": 492.13126,
"y": 285.91016
},
{
"x": 492.02887,
"y": 310.99646
},
{
"x": 299.97308,
"y": 310.21255
}
]
}
],
"maskingPolys": []
}
],
"authorityEng": [
{
"text": "CHIEF, SEOUL IMMIGRATION OFFICE",
"formatted": {
"value": "CHIEF, SEOUL IMMIGRATION OFFICE"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 302.00894,
"y": 308.88394
},
{
"x": 338.3482,
"y": 308.88394
},
{
"x": 338.3482,
"y": 321.1607
},
{
"x": 302.00894,
"y": 321.1607
}
]
}
],
"maskingPolys": []
}
],
"alienRegNumEtc": [
{
"text": "B4***",
"formatted": {
"value": "B4***"
},
"keyText": "",
"confidenceScore": 0.0,
"boundingPolys": [
{
"vertices": [
{
"x": 128.6607,
"y": 292.67853
},
{
"x": 160.58034,
"y": 292.67853
},
{
"x": 160.58034,
"y": 301.51782
},
{
"x": 128.6607,
"y": 301.51782
}
]
}
],
"maskingPolys": [
{
"vertices": [
{
"x": 127.77678,
"y": 291.7946
},
{
"x": 161.46426,
"y": 291.7946
},
{
"x": 161.46426,
"y": 302.40176
},
{
"x": 127.77678,
"y": 302.40176
}
]
}
]
}
]
},
"rois": [
{
"vertices": [
{
"x": 11.189065,
"y": 9.545465
},
{
"x": 537.28156,
"y": 9.624473
},
{
"x": 538.10034,
"y": 341.7781
},
{
"x": 11.295485,
"y": 342.03995
}
]
}
],
"idtype": "Alien Registration Card"
}
}
}
]
}
失敗
呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。
{
"version": "V2",
"requestId": "1234",
"timestamp": 1725235840459,
"images": [
{
"uid": "{uid}",
"name": "alienRegistration_test",
"inferResult": "ERROR",
"message": "Read page:0 error.",
"validationResult": {
"result": "NO_REQUESTED"
}
}
]
}