クレジットカード

Prev Next

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

特化モデルエンジンを使用してクレジットカードの入力情報(key-value)を認識し、抽出します。

リクエスト

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

メソッド URI
POST /credit-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/credit-card' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--data '{
    "version": "V2",
    "requestId": "1234",
    "timestamp": "0",
    "images": [
        {
            "format": "png",
            "data": "{Base64でエンコードされた画像データ}",
            "name": "creaditcard_test2"
    }]
}'

Content-Type: multipart/form-dataの場合

リクエストヘッダのContent-Typeがmultipart/form-dataの場合のリクエストのサンプルコードは次の通りです。

curl --location --request POST 'https://cbgrx5natw.apigw.ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/credit-card' \
--header 'X-OCR-SECRET: {アプリの登録時に発行された Secret Key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 1724832750462, \"images\": [{\"format\": \"jpg\", \"name\": \"creditcard_test\"}]}"' \
--form '{file}.png"'

レスポンス

レスポンス形式を説明します。

レスポンスボディ

レスポンスボディの説明は次の通りです。

フィールド タイプ 必須の有無 説明
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 - 変換後画像ページインデックス
creditCard Object - クレジットカードの詳細情報
creditCard.result Object - クレジットカードの OCR認識結果

result

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

フィールド タイプ 必須の有無 説明
name Object - カード所有者名の詳細情報
number Object - カード番号の詳細情報
validThru Object - カードの有効期限の詳細情報

共通オブジェクト情報

共通オブジェクトの説明は次の通りです。

フィールド タイプ 必須の有無 説明
text String - 認識結果のテキスト
confidenceScore Float - 認識結果のテキストの信頼度
  • 0~1
  • 信頼度が高いほどテキストの精度が高い
boundingPoly Object - Bounding Poly情報
boudningPoly.vertices Array - Bounding Poly Verticesの詳細情報
subBoundingPolys Array - subBoundiongPolysの詳細情報

vertices

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

フィールド タイプ 必須の有無 説明
x Float - Bounding Poly X軸の座標
y Float - Bounding Poly Y軸の座標

subBoundingPolys

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

フィールド タイプ 必須の有無 説明
x Float - Sub Bounding Poly X軸の座標
y Float - Sub Bounding Poly Y軸の座標

レスポンスステータスコード

CLOVA OCR APIで共通して使用されるレスポンスステータスコードの詳細は、CLOVA OCRの共通レスポンスステータスコードをご参照ください。

レスポンス例

レスポンスのサンプルコードは次の通りです。

成功

呼び出しに成功した場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "V2",
    "requestId": "1234",
    "timestamp": 1725005676747,
    "images": [
        {
            "uid": "{uid}",
            "name": "creditcard_test",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            },
            "creditCard": {
                "result": {
                    "name": {
                        "text": "KAIY*** VENY***",
                        "confidence": 0.8576972,
                        "boundingPoly": {
                            "vertices": []
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 192.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 609.0
                                    },
                                    {
                                        "x": 407.0,
                                        "y": 651.0
                                    },
                                    {
                                        "x": 192.0,
                                        "y": 651.0
                                    }
                                ]
                            } 
                        ]
                    },
                    "number": {
                        "text": "512571781234****",
                        "confidence": 0.999885,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 187.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 450.0
                                },
                                {
                                    "x": 1007.0,
                                    "y": 506.0
                                },
                                {
                                    "x": 187.0,
                                    "y": 506.0
                                }
                            ]
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 187.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 450.0
                                    },
                                    {
                                        "x": 360.0,
                                        "y": 506.0
                                    },
                                    {
                                        "x": 187.0,
                                        "y": 506.0
                                    }
                                ]
                            },
                        ]
                    },
                    "validThru": {
                        "text": "09/23",
                        "confidence": 0.9999175,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 585.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 557.0
                                },
                                {
                                    "x": 735.0,
                                    "y": 600.0
                                },
                                {
                                    "x": 585.0,
                                    "y": 600.0
                                }
                            ]
                        },
                        "subBoundingPolys": []
                    }
                }
            }
        }
    ]
}

失敗

呼び出しに失敗した場合のレスポンスのサンプルコードは次の通りです。

{
    "version": "V2",
    "requestId": "4567",
    "timestamp": 1725003278037,
    "images": [
        {
            "uid": "{uid}",
            "name": "receipt_test2",
            "inferResult": "ERROR",
            "message": "Read page:0 error.",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}