AI Service > Document Recognizer > API v2.0 Guide

Overview of v2.0 API

Changes from v1.0

  1. Enhanced security with the electronic envelope method.

Domain

Name Domain
OCR Public API Domain https://ocr.api.nhncloudservice.com

Prerequisites (AppKey, SecretKey)

  • AppKey and SecretKey are required to use the API.
  • You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

Caution

  • Check whether the request or response is Base64 encoded.
  • Check the detailed mode of encryption and decryption (eg AES-256/CBC/PKCS7Padding).
  • The symmetric key used for encryption must be generated as a 32-byte random number.

Issue Public Key

Request

  • You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method URI
GET /v2.0/appkeys/{appKey}/public-keys/credit-card

[Request Header]

Name Value Description
Authorization {secretKey} Security key issued from the console

[Request Body]

curl -X GET 'https://ocr.api.nhncloudservice.com/v2.0/appkeys/{appKey}/public-keys/credit-card' \
-H 'Authorization: ${secretKey}'

Response

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "key": "String",
        "version": "1.0"
     }
}

[Header]

Name Type Description
isSuccessful Boolean API success or not
resultCode Integer Result code
resultMessage String Result message (success on success, error content on failure)

[Field]

Name Type Description
result Object Public key required for encryption
result.key String Public key (Base64 encoded)
result.version String version of public key
  • The public key is Base64 encoded.

Credit Card API

Credit Card Analysis API

Request

  • You can find the {appKey} and {secretKey} in the URL & Appkey menu at the top of the console.

[URI]

Method URI
POST /v2.0/appkeys/{appKey}/credit-card

[Request Header]

Name Value Description
Authorization {secretKey} Security key issued from the console
X-Key-Version {x-key-version} Version of the public key issued
Symmetric-Key {symmetricKey} Symmetric key encrypted with the issued public key
  • {symmetricKey} must be created as a 32- byte random number.
  • {symmetricKey} must be encrypted with theRSA/ECB/PKCS1Padding method (using public key).

[Field]

Name Type Description Encryption Description
image multipart/form-data Image file Image encrypted with a symmetric key
  • Image files must be encrypted with theAES-256/CBC/PKCS7Padding method (using a symmetric key).

[Request Body]

curl -X POST '[https://ocr.api.nhncloudservice.com/v1.0/appkeys/{appKey}/credit-card](https://ocr.api.nhncloudservice.com/v1.0/appkeys/{appKey}/credit-card)' \
-F 'image=@sample.png' \
-H 'Authorization: ${secretKey}' \
-H 'X-Key-Version: ${x-key-version}' \
-H 'Symmetric-Key: ${symmetricKey}'

Response

[Response Body]

{
    "header": {
        "isSuccessful": true,
        "resultCode": 0,
        "resultMessage": "SUCCESS"
    },
    "result": {
        "fileType": "png",
        "resolution": "low",
        "cardNums": [
                    {
                        "value": "1111",
                        "conf": 0.87
                    },
                    {
                        "value": "2222",
                        "conf": 0.99
                    },
                    {
                        "value": "3333",
                        "conf": 0.97
                    },
                    {
                        "value": "4444",
                        "conf": 0.89
                    },
                ],
                "totalCardNum": "111222233334444",
                "cardNumBoxes": [
                    {
                        "x1": 62,
                        "y1": 256,
                        "x2": 192,
                        "y2": 256,
                        "x3": 192,
                        "y3": 301,
                        "x4": 62,
                        "y4": 301
                    },
                    ...
                ],
                "validThru": {
                    "value": "04/19",
                    "conf": 0.53
                },
                "validThruBox": {
                    "x1": 316,
                    "y1": 315,
                    "x2": 426,
                    "y2": 315,
                    "x3": 426,
                    "y3": 347,
                    "x4": 316,
                    "y4": 347
                }
        }
    }
}

[Header]

Name Type Description
isSuccessful Boolean Analysis API success or not
resultCode Integer Result code
resultMessage String Result message (success on success, error content on failure)

[Field]

Name Type Description Whether encrypted or not
fileType String File extension (.jpg, .png)
resolution String normal: the resolution is the recommended resolution (760*480px) or above, low: the resolution is below the recommended resolution
cardNums List List of card number recognition results
cardNums[0].value String Recognition result O
cardNums[0].conf Double Confidence of the recognition result
totalCardNum List Full card number recognition result O
cardNumBoxes List List of coordinates of the card number recognition area (bounding box)
cardNumBoxes[0] Object Coordinates of recognized area { x1, y1, x2, y2, x3, y3, x4, y4 }
validThru.value String Expiration date recognition content O
validThru.conf Double Confidence of expiration date recognition result
validThruBox Object Coordinates of the expiration date recognition area { x1, y1, x2, y2, x3, y3, x4, y4 }
  • Encrypted items (cardNums[0].value, totalCardNum, etc.) are encrypted with the AES-256/CBC/PKCS7Padding method (using symmetric key).

  • boxes[0] Bounding box

TOP