Document API

업로드한 이미지를 인식하여 인식 결과를 텍스트로 응답합니다. 인식 결과는 Verify API 호출 시 입력으로 사용할 수 있습니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA eKYC 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

Content-Type: application/json인 경우

Base64로 인코딩된 이미지를 전송할 때 사용합니다.

images

images에 대한 설명은 다음과 같습니다.

Content-Type: multipart/form-data인 경우

이미지 파일을 직접 업로드할 때 사용합니다.

message.images

message.images에 대한 설명은 다음과 같습니다.

요청 예시

요청 예시는 다음과 같습니다.

Content-Type: application/json인 경우

요청 헤더 Content-Type이 application/json인 경우, 요청 예시는 다음과 같습니다.

사업자등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/biz-license/document' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-001",
  "timestamp": 1700000000000,
  "images": [
    {
      "name": "business-license",
      "format": "jpg",      
      "data": "{base64-encoded-image}"
    }
  ]
}'

신분증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/document' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
  "requestId": "request-002",
  "timestamp": 1700000000000,
  "images": [
    {
      "name": "identification-card",
      "format": "png",      
      "data": "{base64-encoded-image}"
    }
  ]
}'

Content-Type: multipart/form-data인 경우

요청 헤더 Content-Type이 multipart/form-data인 경우, 요청 예시는 다음과 같습니다.

사업자등록증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/biz-license/document' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message={"requestId": "request-001", "timestamp": 1700000000000, "images": [{"name": "business-license", "format": "jpg"}]}' \
--form 'file=@"{image-file-path}"'

신분증

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/id-card/document' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message={"requestId": "request-002", "timestamp": 1700000000000, "images": [{"name": "identification-card", "format": "png"}]}' \
--form 'file=@"{image-file-path}"'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

images

images에 대한 설명은 다음과 같습니다.

bizLicense

bizLicense에 대한 설명은 다음과 같습니다.

idCard

idCard에 대한 설명은 다음과 같습니다.

face

face에 대한 설명은 다음과 같습니다.

응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 CLOVA eKYC 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

사업자등록증

{
    "requestId": "request-001",
    "timestamp": 1700000000000,
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "images": [
        {
            "uid": "0123456789abcdef0123456789abcdef",
            "name": "business-license",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "bizLicense": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "bisAddress": [
                        {
                            "text": "경기도 성남시 분당구 불정로 6 (정자동, 그린팩토리)",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        { "x": 227.0, "y": 350.0 },
                                        { "x": 284.0, "y": 350.0 },
                                        { "x": 284.0, "y": 372.0 },
                                        { "x": 227.0, "y": 372.0 }
                                    ]
                                }
                            ]
                        }
                    ],
                    "bisItem": [
                        {
                            "text": "전자지급결제대행",
                            "boundingPolys": [...]
                        }
                    ],
                    "registerNumber": [
                        {
                            "text": "XXX-XX-XXXXX",
                            "boundingPolys": [...]
                        }
                    ],
                    "bisType": [
                        {
                            "text": "금융 및 보험업",
                            "boundingPolys": [...]
                        }
                    ],
                    "corpName": [
                        {
                            "text": "네이버파이낸셜 주식회사",
                            "boundingPolys": [...]
                        }
                    ],
                    "corpRegisterNum": [
                        {
                            "text": "111111-2222222",
                            "boundingPolys": [...]
                        }
                    ],
                    "documentType": [
                        {
                            "text": "사업자등록증",
                            "formatted": { "value": "사업자등록증" },
                            "boundingPolys": [...],
                            "maskingPolys": []
                        }
                    ],
                    "headAddress": [
                        {
                            "text": "경기도 성남시 분당구 불정로 6 (정자동, 그린팩토리)",
                            "boundingPolys": [...]
                        }
                    ],
                    "issuanceDate": [
                        {
                            "text": "2019년 11월 05일",
                            "boundingPolys": [...]
                        }
                    ],
                    "issuanceReason": [
                        {
                            "text": "정정",
                            "boundingPolys": [...]
                        }
                    ],
                    "openDate": [
                        {
                            "text": "2019년 11월 01일",
                            "boundingPolys": [...]
                        }
                    ],
                    "repName": [
                        {
                            "text": "홍길동",
                            "boundingPolys": [...]
                        }
                    ],
                    "taxType": [
                        {
                            "text": "법인사업자",
                            "boundingPolys": [...]
                        }
                    ]
                }
            },
            "inferDetailType": "BL_CORP",
            "inferDetailResource": "bl-corp"
        }
    ]
}

신분증

{
    "requestId": "request-002",
    "timestamp": 1700000000000,
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "images": [
        {
            "uid": "0123456789abcdef0123456789abcdef",
            "name": "identification-card",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "idCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "isConfident": true,
                    "ic": {
                        "name": [
                            {
                                "text": "홍길순",
                                "formatted": { "value": "홍길순" },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            { "x": 87.12531, "y": 128.30472 },
                                            { "x": 354.70047, "y": 122.730225 },
                                            { "x": 355.77777, "y": 174.43933 },
                                            { "x": 88.2026, "y": 180.01381 }
                                        ]
                                    }
                                ],
                                "maskingPolys": []
                            }
                        ],
                        "personalNum": [
                            {
                                "text": "111111-2222222",
                                "formatted": { "value": "111111-2222222" },
                                "boundingPolys": [...],
                                "maskingPolys": [...],
                                "maskingText": "111111-*******"
                            }
                        ],
                        "address": [
                            {
                                "text": "경기도 성남시 분당구 불정로 6 (정자동, 그린팩토리)",
                                "formatted": { "value": "경기도 성남시 분당구 불정로 6 (정자동, 그린팩토리)" },
                                "boundingPolys": [...],
                                "maskingPolys": []
                            }
                        ],
                        "issueDate": [
                            {
                                "text": "2012. 6. 1.",
                                "formatted": {
                                    "year": "2012",
                                    "month": "06",
                                    "day": "01"
                                },
                                "boundingPolys": [...],
                                "maskingPolys": [...],
                                "maskingText": "**********"
                            }
                        ],
                        "authority": [
                            {
                                "text": "경기도 성남시장",
                                "formatted": { "value": "경기도 성남시장" },
                                "boundingPolys": [...],
                                "maskingPolys": []
                            }
                        ]
                    },
                    "rois": [
                        {
                            "vertices": [
                                { "x": -28.767818, "y": 6.7013874 },
                                { "x": 756.80585, "y": -29.431211 },
                                { "x": 749.05365, "y": 466.8993 },
                                { "x": 8.251797, "y": 480.46704 }
                            ]
                        }
                    ],
                    "idtype": "ID Card"
                }
            },
            "face": {
                "result": "SUCCESS",
                "message": "Success",
                "faces": [
                    {
                        "boundingPoly": {
                            "vertices": [
                                { "x": 548.0829, "y": 73.06664 },
                                { "x": 648.30365, "y": 73.06664 },
                                { "x": 648.30365, "y": 215.3121 },
                                { "x": 548.0829, "y": 215.3121 }
                            ]
                        },
                        "boundingBox": [...],
                        "confidence": 0.99917346,
                        "landmark": [
                            {
                                "type": "CHIN",
                                "position": [543.59534, 134.98737]
                            },
                            ...
                        ],
                        "feature": [-0.020869667, 0.1342391, ...]
                    }
                ],
                "count": 1
            },
            "inferDetailType": "IC",
            "inferDetailResource": "ic",
            "isGrayScale": false
        }
    ]
}