外国人登録証

Prev Next

Classic/VPC環境で利用できます。

特化モデルエンジンを使用して外国人登録証の入力情報(key-value)を認識し、抽出します。

リクエスト

リクエスト形式を説明します。リクエスト形式は次の通りです。

メソッド URI
POST /id-card

リクエストヘッダ

CLOVA OCR APIで共通して使用されるヘッダの詳細は、CLOVA OCRのリクエストヘッダをご参照ください。

リクエストボディ

リクエストボディの説明は次の通りです。

Content-Type: application/jsonの場合

リクエストヘッダのContent-Typeがapplication/jsonの場合のリクエストボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
version String - バージョン情報
  • V2のみ使用
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 バージョン情報
  • V2のみ使用
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 画像の形式
  • jpg | jpeg | png | pdf | tif | tiff
    • 画像: jpg、jpeg、png
    • 単一ページ: pdf、tif、tiff
  • 画像の形式のうち、1つを選択して入力
name String Required 任意の画像名
  • 画像の識別とレスポンス結果の確認時に使用
data String Required Base64でエンコードされた画像データ
  • Content-Type: application/jsonの場合に入力可能

リクエスト例

リクエストのサンプルコードは次の通りです。

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 - バージョン情報
  • V2のみ使用
requestId String - API呼び出し UUID
timestamp Integer - APIの呼び出し時刻(Timestamp)
images Array - imagesの詳細情報

images

imagesの説明は次の通りです。

フィールド タイプ 必須の有無 説明
uid String - 外国人登録証画像の UID
  • API有効性検査時に使用
name String - 外国人登録証の画像名
  • 画像の識別とレスポンス結果の確認時に使用
inferResult String - 外国人登録証の画像認識結果
  • SUCCESS | FAILURE | ERROR
    • SUCCESS: 認識成功
    • FAILURE: 認識失敗
    • ERROR: 認識処理例外
message String - 結果メッセージ
validationResult Object - 有効性検査の結果情報
validationResult.result String - 有効性検査の結果コード
  • NO_REQUESTED | UNCHECKED | ERROR | VALID | INVALID
    • NO_REQUESTED: 検証をリクエストしていない(有効性検査失敗)
    • UNCHECKED: 検証の有無を確認できない
    • ERROR: 検証中にエラー発生(有効性検査失敗)
    • VALID: 検証中にエラー発生(有効性検査成功)
    • INVALID: 検証合格失敗
validationResult.message String - 有効性検査結果の詳細メッセージ
  • 必ずしも返される値ではない
convertedImageInfo Object - 変換後の画像情報
  • formatがpdfまたはtiffの場合
  • 座標は呼び出し画像ファイルを基準に設定
convertedImageInfo.width Integer - 変換後画像の横長
convertedImageInfo.height Integer - 変換後画像の縦長
convertedImageInfo.pageIndex Integer - 変換後画像ページインデックス
idCard Object - 身分証明書の詳細情報
idCard.meta Object - メタ情報
idCard.meta.estimatedLanguage String - OCR推定言語
  • ko | en | ja
    • ko:韓国語
    • en: 英語
    • ja: 日本語
idCard.result Object - 身分証明書の OCR認識結果

result

resultの説明は次の通りです。

フィールド タイプ 必須の有無 説明
isConfident Boolean - 各タイプの詳細情報を保有するかどうか
  • true | false
    • true: 保有
    • false: 保有しない
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 - 身分証明書タイプ
  • Alien Registration Card

alienRegNum

ac.alienRegNumの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の番号テキスト
formatted Object - 認識結果の番号テキスト情報
formatted.value String - 認識結果の番号テキストの値
keyText String - 認識結果の番号テキストのキー
confidenceScore Float - 認識結果の番号テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

sex

ac.sexの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の性別テキスト
formatted Object - 認識結果の性別テキスト情報
formatted.value String - 認識結果の性別テキストの値
keyText String - 認識結果の性別テキストのキー
confidenceScore Float - 認識結果の性別テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

name

ac.nameの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の名前テキスト
formatted Object - 認識結果の名前テキスト情報
formatted.value String - 認識結果の名前テキストの値
keyText String - 認識結果の名前テキストのキー
confidenceScore Float - 認識結果の名前テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

nationality

ac.nationalityの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の国籍テキスト
formatted Object - 認識結果の国籍テキスト情報
formatted.value String - 認識結果の国籍テキストの値
keyText String - 認識結果の国籍テキストのキー
confidenceScore Float - 認識結果の国籍テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

visaType

ac.visaTypeの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果のビザタイプテキスト
formatted Object - 認識結果のビザタイプテキスト情報
formatted.value String - 認識結果のビザタイプテキストの値
keyText String - 認識結果のビザタイプテキストのキー
confidenceScore Float - 認識結果のビザタイプテキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

num

pp.numの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の番号テキスト
formatted Object - 認識結果の番号テキスト情報
formatted.value String - 認識結果の番号テキストの値
keyText String - 認識結果の番号テキストのキー
confidenceScore Float - 認識結果の番号テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
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 - 認識結果の日付テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

authority

ac.authorityの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の発行機関テキスト
formatted Object - 認識結果の発行機関テキスト情報
formatted.value String - 認識結果の発行機関テキストの値
keyText String - 認識結果の発行機関テキストのキー
confidenceScore Float - 認識結果の発行機関テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

authorityEng

ac.authorityEngの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果の発行機関テキスト(英語)
formatted Object - 認識結果の発行機関テキスト情報
formatted.value String - 認識結果の発行機関テキストの値
keyText String - 認識結果の発行機関テキストのキー
confidenceScore Float - 認識結果の発行機関テキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPolys Array - boundingPolyの詳細情報
maskingPolys Array - maskingPolyの詳細情報

alienRegNumEtc

ac.alienRegNumEtcの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果のテキスト
formatted Object - 認識結果のテキスト情報
formatted.value String - 認識結果のテキストの値
keyText String - 認識結果のテキストのキー
confidenceScore Float - 認識結果のテキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
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"
            }
        }
    ]
}