CLOVA OCR Document API

Version Date Changes
v1.0.0 2021-03-04 최초 작성
v1.0.2 2021-07-22 foundValuesSum -> foundValueSum
신분증에 maskingPolys 추가
v1.0.3 2021-09-16 신분증에 외국인등록증 추가
v1.0.4 2022-04-21 신분증 테두리 위치 표기
외국인 등록증에 alienRegNumEtc 추가
신용카드에 이름 추가
v1.0.5 2023-05-25 여권 MRZ API
v1.0.6 2023-11-23 영수증 부가세 및 할인금액 추가
v1.0.7 2024-09-26 콘텐츠 항목 정리 및 문구 개선

본 문서에서는 Document OCR의 공통요청 및 응답 바디에 대해 설명하고 API 구현 예제를 제공합니다.

참고
  • Document OCR은 Post URL과 헤더를 기준으로 상품을 구분하며 요청 바디는 모두 동일합니다.
  • Post URL과 헤더, 에러코드에 대한 정보는 CLOVA OCR 개요 문서를 참조해 주십시오.
{
  "version": "V2",
  "requestId": "string",
  "timestamp": 0,
  "images": [
    {
      "format": "jpg",
      "name": "document ocr test",
      "data": "/9j/4AAQ*****************"
    }
  ]
}
JSON

Content-Type : application/json

  • CURL example:
curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--data-raw '{"images":[{"format":"jpg","name":"demo","data":"your image base64 bytes"}],"requestId":"guide-json-demo","version":"V2","timestamp":1584062336793}'
Plain text
  • JSON 요청 바디 필드
필드명 필수 여부 타입 설명 제약 사항
version Y string V2로 고정
requestId Y string 임의의 UUID 값 입력
timestamp Y integer 임의의 timestamp 값을 숫자로 입력
images Y string JSON array로 작성하며, 호출당 1개의 이미지 array만 작성 가능
images.format Y string jpg, jpeg, png, pdf, tiff 중 택일하여 이미지 포맷을 입력 pdf, tiff는 단일 페이지 형식을 지원합니다.
image.data Y string BASE64로 인코딩된 이미지 바이트를 입력 특화 문서의 경우 보안을 위해 인코딩된 이미지 바이트만 지원합니다.
image.name Y string 임의의 이미지명 입력 이미지를 식별하는 데 사용되며, 응답 결과 검증에 사용하실 수 있습니다.

Content-Type : multipart/form-data

  • CURL example:
curl --request POST 'your apigw invoke url' \
--header 'X-OCR-SECRET: your secret key' \
--form 'message={"images":[{"format":"png","name":"demo"}],"requestId":"guide-demo","version":"V2","timestamp":1584062336793}' \
--form 'file=@image.png'
Plain text
  • Form Data 요청 바디 필드
필드명 필수 여부 타입 설명 제약 사항
version Y string V2로 고정
requestId Y string 임의의 UUID 값 입력
timestamp Y integer 임의의 timestamp 값을 숫자로 입력
images Y string JSON array로 작성하며, 호출당 1개의 이미지 array만 작성 가능
images.format Y string jpg, jpeg, png, pdf, tiff 중 택일하여 이미지 포맷을 입력 pdf, tiff는 단일 페이지 형식을 지원
image.name Y string 임의의 이미지명 입력 이미지를 식별하는 데 사용됨
응답 결과 검증에 사용 가능		 
{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1613984672273,
    "images": [{
        "receipt": {
            "meta": {
                "estimatedLanguage": "ko"
            },
            "result": {
                "storeInfo": {
                    "name": {
                        "text": "emart everyday",
                        "formatted": {
                            "value": "emart everyday"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 263.0,
                                    "y": 96.0
                                },
                                {
                                    "x": 390.0,
                                    "y": 100.0
                                },
                                {
                                    "x": 389.0,
                                    "y": 141.0
                                },
                                {
                                    "x": 262.0,
                                    "y": 137.0
                                }
                            ]
                        }]
                    },
                    "subName": {
                        "text": "분당정지2점",
                        "formatted": {
                            "value": "분당정지2점"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 530.0,
                                    "y": 102.0
                                },
                                {
                                    "x": 611.0,
                                    "y": 102.0
                                },
                                {
                                    "x": 611.0,
                                    "y": 122.0
                                },
                                {
                                    "x": 530.0,
                                    "y": 122.0
                                }
                            ]
                        }]
                    },
                    "bizNum": {
                        "text": "212-81-25544",
                        "formatted": {
                            "value": "212-81-25544"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 402.0,
                                    "y": 125.0
                                },
                                {
                                    "x": 515.0,
                                    "y": 124.0
                                },
                                {
                                    "x": 515.0,
                                    "y": 141.0
                                },
                                {
                                    "x": 402.0,
                                    "y": 142.0
                                }
                            ]
                        }]
                    },
                    "addresses": [{
                        "text": "경기 성남시분당구 정자일로 120",
                        "formatted": {
                            "value": "경기 성남시분당구 정자일로 120"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 401.0,
                                    "y": 144.0
                                },
                                {
                                    "x": 432.0,
                                    "y": 144.0
                                },
                                {
                                    "x": 432.0,
                                    "y": 165.0
                                },
                                {
                                    "x": 401.0,
                                    "y": 165.0
                                }
                            ]
                        }]
                    }],
                    "tel": [{
                        "text": "(031)786-1171",
                        "formatted": {
                            "value": "0317861171"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 569.0,
                                    "y": 122.0
                                },
                                {
                                    "x": 716.0,
                                    "y": 118.0
                                },
                                {
                                    "x": 716.0,
                                    "y": 140.0
                                },
                                {
                                    "x": 570.0,
                                    "y": 144.0
                                }
                            ]
                        }]
                    }]
                },
                "paymentInfo": {
                    "date": {
                        "text": "2020-04-16",
                        "formatted": {
                            "year": "2020",
                            "month": "04",
                            "day": "16"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 261.0,
                                    "y": 256.0
                                },
                                {
                                    "x": 432.0,
                                    "y": 260.0
                                },
                                {
                                    "x": 431.0,
                                    "y": 284.0
                                },
                                {
                                    "x": 260.0,
                                    "y": 280.0
                                }
                            ]
                        }]
                    },
                    "time": {
                        "text": "20: 11",
                        "formatted": {
                            "hour": "20",
                            "minute": "11",
                            "second": "00"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 437.0,
                                    "y": 261.0
                                },
                                {
                                    "x": 468.0,
                                    "y": 261.0
                                },
                                {
                                    "x": 468.0,
                                    "y": 279.0
                                },
                                {
                                    "x": 437.0,
                                    "y": 279.0
                                }
                            ]
                        }]
                    },
                    "cardInfo": {
                        "company": {
                            "text": "신 한",
                            "formatted": {
                                "value": "신한"
                            },
                            "boundingPolys": [{
                                "vertices": [{
                                        "x": 309.0,
                                        "y": 585.0
                                    },
                                    {
                                        "x": 334.0,
                                        "y": 585.0
                                    },
                                    {
                                        "x": 334.0,
                                        "y": 610.0
                                    },
                                    {
                                        "x": 309.0,
                                        "y": 610.0
                                    }
                                ]
                            }]
                        },
                        "number": {
                            "text": "4221**8666",
                            "formatted": {
                                "value": "4221**8666"
                            },
                            "boundingPolys": [{
                                "vertices": [{
                                        "x": 522.0,
                                        "y": 586.0
                                    },
                                    {
                                        "x": 716.0,
                                        "y": 592.0
                                    },
                                    {
                                        "x": 716.0,
                                        "y": 612.0
                                    },
                                    {
                                        "x": 522.0,
                                        "y": 606.0
                                    }
                                ]
                            }]
                        }
                    },
                    "confirmNum": {
                        "text": "28672931",
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 522.0,
                                    "y": 586.0
                                },
                                {
                                    "x": 716.0,
                                    "y": 592.0
                                },
                                {
                                    "x": 716.0,
                                    "y": 612.0
                                },
                                {
                                    "x": 522.0,
                                    "y": 606.0
                                }
                            ]
                        }]
                    }
                },
                "subResults": [{
                    "items": [{
                        "name": {
                            "text": "씨그램 레몬350ml",
                            "formatted": {
                                "value": "씨그램 레몬350ml"
                            },
                            "boundingPolys": [{
                                "vertices": [{
                                        "x": 310.0,
                                        "y": 345.0
                                    },
                                    {
                                        "x": 372.0,
                                        "y": 345.0
                                    },
                                    {
                                        "x": 372.0,
                                        "y": 369.0
                                    },
                                    {
                                        "x": 310.0,
                                        "y": 369.0
                                    }
                                ]
                            }]
                        },
                        "count": {
                            "text": "2",
                            "formatted": {
                                "value": "2"
                            },
                            "boundingPolys": [{
                                "vertices": [{
                                        "x": 601.0,
                                        "y": 348.0
                                    },
                                    {
                                        "x": 615.0,
                                        "y": 348.0
                                    },
                                    {
                                        "x": 615.0,
                                        "y": 365.0
                                    },
                                    {
                                        "x": 601.0,
                                        "y": 365.0
                                    }
                                ]
                            }]
                        },
                        "price": {
                            "price": {
                                "text": "1,600",
                                "formatted": {
                                    "value": "1600"
                                },
                                "boundingPolys": [{
                                    "vertices": [{
                                            "x": 662.0,
                                            "y": 347.0
                                        },
                                        {
                                            "x": 716.0,
                                            "y": 347.0
                                        },
                                        {
                                            "x": 716.0,
                                            "y": 367.0
                                        },
                                        {
                                            "x": 662.0,
                                            "y": 367.0
                                        }
                                    ]
                                }]
                            },
                            "unitPrice": {
                                "text": "800",
                                "formatted": {
                                    "value": "800"
                                },
                                "boundingPolys": [{
                                    "vertices": [{
                                            "x": 541.0,
                                            "y": 347.0
                                        },
                                        {
                                            "x": 577.0,
                                            "y": 347.0
                                        },
                                        {
                                            "x": 577.0,
                                            "y": 368.0
                                        },
                                        {
                                            "x": 541.0,
                                            "y": 368.0
                                        }
                                    ]
                                }]
                            }
                        }
                    }]
                }],
                "totalPrice": {
                    "price": {
                        "text": "1,600",
                        "formatted": {
                            "value": "1600"
                        },
                        "boundingPolys": [{
                            "vertices": [{
                                    "x": 651.0,
                                    "y": 546.0
                                },
                                {
                                    "x": 717.0,
                                    "y": 548.0
                                },
                                {
                                    "x": 717.0,
                                    "y": 569.0
                                },
                                {
                                    "x": 651.0,
                                    "y": 567.0
                                }
                            ]
                        }]
                    }
                }
            }
        },
        "uid": "5b9de1f9765448eca574efc1a4231bbe",
        "name": "testV2Demo",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "validationResult": {
            "result": "NO_REQUESTED"
        }
    }]
}
JSON

영수증 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
receipt json object receipt 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌표값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. receipt 객체 필드

필드명 유형 설명
meta json object 메타 정보
meta.estimatedLanguage string OCR에서 추정한 언어
(en: 영어, ja: 일본어, ko: 한국어)
result json object 인식 결과
result.storeInfo json object 매장 정보
result.storeInfo.poiInfo PoiObject[] POI 그라운딩 결과
result.storeInfo.name StringObject 상호명
result.storeInfo.subName StringObject 지점명
result.storeInfo.bizNum StringObject 사업자번호
result.storeInfo.movieName StringObject 영화 제목 (영화표 관련 항목)
result.storeInfo.addresses StringObject[] 매장 주소
result.storeInfo.tel TelObject[] 매장 전화번호
result.paymentInfo json object 결제 정보
result.paymentInfo.date DateObject 결제 날짜
result.paymentInfo.time TimeObject 결제 시간
result.paymentInfo.cardInfo json object 거래 카드 정보
result.paymentInfo.cardInfo.company StringObject 카드사 이름
result.paymentInfo.cardInfo.number StringObject 카드 번호
result.paymentInfo.confirmNum BaseObject 결제 번호
result.subResults json array 항목 그룹 정보
result.subResults.items json array 인식된 항목 정보 (메뉴 등)
result.subResults.items.name StringObject 항목명
result.subResults.items.code StringObject 항목 코드
result.subResults.items.count FloatObject 항목 수량
result.subResults.items.price json object 가격정보
result.subResults.items.price.price FloatObject 가격
result.subResults.items.price.unitPrice FloatObject 단가
result.totalPrice json object 총 금액 정보
result.totalPrice.price FloatObject 총 금액
result.subTotal FloatObject 총 합계 정보
result.subTotal.taxPrice FloatObject 부과세
result.subTotal.discountPrice FloatObject 할인금액 
{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1613984821070,
    "images": [{
        "bizLicense": {
            "meta": {
                "estimatedLanguage": "ko"
            },
            "result": {
                "birth": [{
                    "text": "1951 년 12 03 일",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 396.0,
                                "y": 254.0
                            },
                            {
                                "x": 421.0,
                                "y": 254.0
                            },
                            {
                                "x": 421.0,
                                "y": 265.0
                            },
                            {
                                "x": 396.0,
                                "y": 265.0
                            }
                        ]
                    }]
                }],
                "bisAddress": [{
                    "text": "경상남도 사천시 사천용 보공로 54",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 193.0,
                                "y": 288.0
                            },
                            {
                                "x": 235.0,
                                "y": 288.0
                            },
                            {
                                "x": 235.0,
                                "y": 300.0
                            },
                            {
                                "x": 193.0,
                                "y": 300.0
                            }
                        ]
                    }]
                }],
                "bisArea": [],
                "bisItem": [{
                    "text": "비주거용 건물 임대업(점포, 자기자)",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 368.0,
                                "y": 325.0
                            },
                            {
                                "x": 399.0,
                                "y": 325.0
                            },
                            {
                                "x": 399.0,
                                "y": 334.0
                            },
                            {
                                "x": 368.0,
                                "y": 334.0
                            }
                        ]
                    }]
                }],
                "registerNumber": [{
                    "text": "611-01-99810",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 290.0,
                                "y": 210.0
                            },
                            {
                                "x": 386.0,
                                "y": 211.0
                            },
                            {
                                "x": 386.0,
                                "y": 227.0
                            },
                            {
                                "x": 290.0,
                                "y": 225.0
                            }
                        ]
                    }]
                }],
                "bisType": [{
                    "text": "부동산업 및 임대업",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 221.0,
                                "y": 322.0
                            },
                            {
                                "x": 262.0,
                                "y": 322.0
                            },
                            {
                                "x": 262.0,
                                "y": 333.0
                            },
                            {
                                "x": 221.0,
                                "y": 333.0
                            }
                        ]
                    }]
                }],
                "companyName": [{
                    "text": "동성자동차종합정비",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 194.0,
                                "y": 232.0
                            },
                            {
                                "x": 293.0,
                                "y": 233.0
                            },
                            {
                                "x": 293.0,
                                "y": 247.0
                            },
                            {
                                "x": 194.0,
                                "y": 245.0
                            }
                        ]
                    }]
                }],
                "coRepName": [],
                "corpName": [],
                "corpRegisterNum": [],
                "coRepSocialNum": [],
                "documentType": [{
                    "text": "사업자등록증",
                    "formatted": {
                        "value": "사업자등록증"
                    },
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 199.0,
                                "y": 157.0
                            },
                            {
                                "x": 396.0,
                                "y": 160.0
                            },
                            {
                                "x": 396.0,
                                "y": 189.0
                            },
                            {
                                "x": 198.0,
                                "y": 186.0
                            }
                        ]
                    }]
                }],
                "headAddress": [],
                "issuanceDate": [{
                    "text": "2017 년 06 월 29일",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 225.0,
                                "y": 623.0
                            },
                            {
                                "x": 259.0,
                                "y": 623.0
                            },
                            {
                                "x": 259.0,
                                "y": 637.0
                            },
                            {
                                "x": 225.0,
                                "y": 637.0
                            }
                        ]
                    }]
                }],
                "issuanceReason": [{
                    "text": "2017 년 06 월 29일",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 225.0,
                                "y": 623.0
                            },
                            {
                                "x": 259.0,
                                "y": 623.0
                            },
                            {
                                "x": 259.0,
                                "y": 637.0
                            },
                            {
                                "x": 225.0,
                                "y": 637.0
                            }
                        ]
                    }]
                }],
                "openDate": [{
                    "text": "2014 년 06 월 09 일",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 193.0,
                                "y": 271.0
                            },
                            {
                                "x": 218.0,
                                "y": 271.0
                            },
                            {
                                "x": 218.0,
                                "y": 280.0
                            },
                            {
                                "x": 193.0,
                                "y": 280.0
                            }
                        ]
                    }]
                }],
                "repName": [{
                    "text": "김영두",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 193.0,
                                "y": 251.0
                            },
                            {
                                "x": 228.0,
                                "y": 251.0
                            },
                            {
                                "x": 228.0,
                                "y": 264.0
                            },
                            {
                                "x": 193.0,
                                "y": 264.0
                            }
                        ]
                    }]
                }],
                "socialNumber": [],
                "taxType": [{
                    "text": "일반과세자",
                    "boundingPolys": [{
                        "vertices": [{
                                "x": 238.0,
                                "y": 185.0
                            },
                            {
                                "x": 357.0,
                                "y": 187.0
                            },
                            {
                                "x": 357.0,
                                "y": 209.0
                            },
                            {
                                "x": 238.0,
                                "y": 207.0
                            }
                        ]
                    }]
                }]
            }
        },
        "uid": "ecf05843a1f444b6943e9d202475c3eb",
        "name": "testV2Demo",
        "inferResult": "SUCCESS",
        "message": "SUCCESS",
        "validationResult": {
            "result": "NO_REQUESTED"
        }
    }]
}
JSON

사업자등록증 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
bizLicense json object bizLicense 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌표값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. bizLicense 객체 필드

필드명 유형 설명
meta json object 메타 정보
meta.estimatedLanguage string OCR에서 추정한 언어
(en: 영어, ja: 일본어, ko: 한국어)
result json object 인식 결과 객체
result.birth BaseObject[] 생년월일
result.bisAddress BaseObject[] 사업자 주소
result.bisArea BaseObject[] 사업장 소재지
result.bisItem BaseObject[] 사업 항목
result.registerNumber BaseObject[] 사업자등록번호
result.bisType BaseObject[] 업종
result.companyName BaseObject[] 상호
result.coRepName BaseObject[] 공동 대표자 이름
result.corpName BaseObject[] 법인(기업)명
result.corpRegisterNum BaseObject[] 사업자등록번호
result.coRepSocialNum BaseObject[] 공동 대표자의 주민등록번호
result.documentType StringObject[] 문서 유형
result.headAddress BaseObject[] 본사 주소
result.issuanceDate BaseObject[] 발행 일자
result.issuanceReason BaseObject[] 발행 사유
result.openDate BaseObject[] 사업 시작일
result.repName BaseObject[] 대표자 이름
result.socialNumber BaseObject[] 주민등록번호
result.taxType BaseObject[] 과세 유형 
{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1613984515468,
    "images": [
        {
            "creditCard": {
                "result": {
                    "number": {
                        "text": "5307123456789012",
                        "confidence": 0.96435016,
                        "boundingPoly": {
                            "vertices": [
                                {
                                    "x": 64.0,
                                    "y": 218.0
                                },
                                {
                                    "x": 582.0,
                                    "y": 222.0
                                },
                                {
                                    "x": 582.0,
                                    "y": 265.0
                                },
                                {
                                    "x": 64.0,
                                    "y": 261.0
                                }
                            ]
                        },
                        "subBoundingPolys": [
                            {
                                "vertices": [
                                    {
                                        "x": 65.0,
                                        "y": 222.0
                                    },
                                    {
                                        "x": 175.0,
                                        "y": 225.0
                                    },
                                    {
                                        "x": 174.0,
                                        "y": 260.0
                                    },
                                    {
                                        "x": 64.0,
                                        "y": 257.0
                                    }
                                ]
                            },
                            {
                                "vertices": [
                                    {
                                        "x": 202.0,
                                        "y": 225.0
                                    },
                                    {
                                        "x": 312.0,
                                        "y": 225.0
                                    },
                                    {
                                        "x": 312.0,
                                        "y": 262.0
                                    },
                                    {
                                        "x": 202.0,
                                        "y": 262.0
                                    }
                                ]
                            },
                            {
                                "vertices": [
                                    {
                                        "x": 340.0,
                                        "y": 225.0
                                    },
                                    {
                                        "x": 445.0,
                                        "y": 225.0
                                    },
                                    {
                                        "x": 445.0,
                                        "y": 260.0
                                    },
                                    {
                                        "x": 340.0,
                                        "y": 260.0
                                    }
                                ]
                            },
                            {
                                "vertices": [
                                    {
                                        "x": 470.0,
                                        "y": 222.0
                                    },
                                    {
                                        "x": 582.0,
                                        "y": 222.0
                                    },
                                    {
                                        "x": 582.0,
                                        "y": 260.0
                                    },
                                    {
                                        "x": 470.0,
                                        "y": 260.0
                                    }
                                ]
                            }
                        ]
                    }
                }
            },
            "uid": "5f824ebe5b9744bb81bd3e1ef7f42e4e",
            "name": "testV2Demo",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}
JSON

신용카드 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
creditCard json object creditCard 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌표값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. creditCard 객체 필드

필드명 유형 설명
meta json object 메타 정보
meta.estimatedLanguage string OCR에서 추정한 언어
(en: 영어, ja: 일본어, ko: 한국어)
result json object 인식 결과 객체
result.number Field object field 객체 참조
result.validThru Field object field 객체 참조
result.name Field object 카드 소유자 이름
field 객체 참조

주민등록증 응답 예시 

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1613984543939,
    "images": [
        {
            "idCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "isConfident": true,
                    "ic": {
                        "name": [
                            {
                                "text": "소닉",
                                "formatted": {
                                    "value": "소닉"
                                },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 93.0,
                                                "y": 135.0
                                            },
                                            {
                                                "x": 257.0,
                                                "y": 135.0
                                            },
                                            {
                                                "x": 257.0,
                                                "y": 161.0
                                            },
                                            {
                                                "x": 93.0,
                                                "y": 161.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "personalNum": [
                            {
                                "text": "910623-1062372",
                                "formatted": {
                                    "value": "910623-1062372"
                                },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 83.0,
                                                "y": 166.0
                                            },
                                            {
                                                "x": 260.0,
                                                "y": 166.0
                                            },
                                            {
                                                "x": 260.0,
                                                "y": 186.0
                                            },
                                            {
                                                "x": 83.0,
                                                "y": 186.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "address": [
                            {
                                "text": "서울특별시 종로구 종로1가 24 르메이에르 종로타운",
                                "formatted": {
                                    "value": "서울특별시 종로구 종로1가 24 르메이에르 종로타운"
                                },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 43.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 148.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 148.0,
                                                "y": 255.0
                                            },
                                            {
                                                "x": 43.0,
                                                "y": 255.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 47.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 150.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 150.0,
                                                "y": 234.0
                                            },
                                            {
                                                "x": 47.0,
                                                "y": 234.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 154.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 240.0,
                                                "y": 232.0
                                            },
                                            {
                                                "x": 240.0,
                                                "y": 255.0
                                            },
                                            {
                                                "x": 154.0,
                                                "y": 255.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 156.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 219.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 219.0,
                                                "y": 234.0
                                            },
                                            {
                                                "x": 156.0,
                                                "y": 234.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 224.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 302.0,
                                                "y": 212.0
                                            },
                                            {
                                                "x": 302.0,
                                                "y": 235.0
                                            },
                                            {
                                                "x": 224.0,
                                                "y": 235.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 305.0,
                                                "y": 213.0
                                            },
                                            {
                                                "x": 333.0,
                                                "y": 213.0
                                            },
                                            {
                                                "x": 333.0,
                                                "y": 234.0
                                            },
                                            {
                                                "x": 305.0,
                                                "y": 234.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "issueDate": [
                            {
                                "text": "2011.3. 6.",
                                "formatted": {
                                    "year": "2011",
                                    "month": "03",
                                    "day": "06"
                                },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 261.0,
                                                "y": 314.0
                                            },
                                            {
                                                "x": 351.0,
                                                "y": 314.0
                                            },
                                            {
                                                "x": 351.0,
                                                "y": 336.0
                                            },
                                            {
                                                "x": 261.0,
                                                "y": 336.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 354.0,
                                                "y": 314.0
                                            },
                                            {
                                                "x": 376.0,
                                                "y": 314.0
                                            },
                                            {
                                                "x": 376.0,
                                                "y": 334.0
                                            },
                                            {
                                                "x": 354.0,
                                                "y": 334.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        ],
                        "authority": [
                            {
                                "text": "소닉대통령추진회 소덕회장",
                                "formatted": {
                                    "value": "소닉대통령추진회 소덕회장"
                                },
                                "boundingPolys": [
                                    {
                                        "vertices": [
                                            {
                                                "x": 172.0,
                                                "y": 338.0
                                            },
                                            {
                                                "x": 346.0,
                                                "y": 338.0
                                            },
                                            {
                                                "x": 346.0,
                                                "y": 366.0
                                            },
                                            {
                                                "x": 172.0,
                                                "y": 366.0
                                            }
                                        ]
                                    },
                                    {
                                        "vertices": [
                                            {
                                                "x": 347.0,
                                                "y": 338.0
                                            },
                                            {
                                                "x": 435.0,
                                                "y": 336.0
                                            },
                                            {
                                                "x": 435.0,
                                                "y": 363.0
                                            },
                                            {
                                                "x": 348.0,
                                                "y": 365.0
                                            }
                                        ]
                                    }
                                ]
                            }
                        ]
                    },
                    "idtype": "ID Card"
                }
            },
            "uid": "0012374f247f4e70966d35eaa3c41d2a",
            "name": "testV2Demo",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}
JSON

여권 응답 예시

{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1684203696126,
    "images": [
        {
            "passport": {
                "passportResult": {
                    "documentClassCode": {
                        "rawText": "P<",
                        "refinedText": "Passport",
                        "postprocessed": [
                            1
                        ]
                    },
                    "issuingStateCode": {
                        "rawText": "KOR",
                        "refinedText": "Korea (the Republic of)",
                        "postprocessed": []
                    },
                    "firstName": {
                        "rawText": "HONG",
                        "refinedText": "HONG",
                        "postprocessed": []
                    },
                    "lastName1": {
                        "rawText": "GILSOON",
                        "refinedText": "GILSOON",
                        "postprocessed": []
                    },
                    "lastName2": {
                        "rawText": "-",
                        "refinedText": "-",
                        "postprocessed": []
                    },
                    "documentNumber": {
                        "rawText": "M123A4567",
                        "refinedText": "M123A4567",
                        "postprocessed": []
                    },
                    "checkDigitForDocumentNumber": {
                        "rawText": "0",
                        "refinedText": "0",
                        "postprocessed": []
                    },
                    "nationality": {
                        "rawText": "KOR",
                        "refinedText": "Korea (the Republic of)",
                        "postprocessed": []
                    },
                    "dateOfBirth": {
                        "rawText": "870201",
                        "refinedText": "1987/02/01",
                        "postprocessed": []
                    },
                    "age": {
                        "rawText": "",
                        "refinedText": 36,
                        "postprocessed": []
                    },
                    "checkDigitForDateOfBirth": {
                        "rawText": "0",
                        "refinedText": "0",
                        "postprocessed": []
                    },
                    "gender": {
                        "rawText": "F",
                        "refinedText": "Female",
                        "postprocessed": []
                    },
                    "dateOfExpiry": {
                        "rawText": "300815",
                        "refinedText": "2030/08/15",
                        "postprocessed": []
                    },
                    "checkDigitForDateOfExpiry": {
                        "rawText": "0",
                        "refinedText": "0",
                        "postprocessed": []
                    },
                    "personalNumber": {
                        "rawText": "V2000000000000",
                        "refinedText": "V2000000000000",
                        "postprocessed": []
                    },
                    "checkDigitForPersonalNumber": {
                        "rawText": "0",
                        "refinedText": "0",
                        "postprocessed": []
                    },
                    "finalCheckDigit": {
                        "rawText": "0",
                        "refinedText": "0",
                        "postprocessed": []
                    },
                    "mrzType": {
                        "rawText": "",
                        "refinedText": "ID-3",
                        "postprocessed": []
                    },
                    "mrzLines": {
                        "rawText": "PMKORHONG<<GILSOON<<<<<<<<<<<<<<<<<<<<<<<<<<<<\nM123A45670KOR8702010F3008150V20000000000000000",
                        "refinedText": "PMKORHONG<<GILSOON<<<<<<<<<<<<<<<<<<<<<<<<<<<<\nM123A45670KOR8702010F3008150V20000000000000000",
                        "postprocessed": [
                            1
                        ]
                    },
                    "isExpired": {
                        "rawText": "",
                        "refinedText": false,
                        "postprocessed": []
                    }
                }
            },
            "uid": "8f8a04985a6e429e97c3ca4184b3c0e4",
            "name": "test 1",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}
JSON

신분증 OCR의 응답 바디를 설명합니다.
신분증은 주민등록증(구형/신형), 운전면허증(구형/신형), 외국인등록증, 여권 인식을 지원합니다.

응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
idCard json object idCard 객체 참조
passport json object passport 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. idCard 객체 필드

필드명 유형 설명
meta json object 메타 정보
meta.estimatedLanguage string OCR에서 추정한 언어
(en: 영어, ja: 일본어, ko: 한국어)
result json object 인식 결과 객체
result.isConfident boolean 신뢰성 자격 요건을 반영하는 지표
각 ID 유형에 필요한 세부 정보가 있으면 true로 출력되고, 그렇지 않으면 false로 출력됨
result.IDType string 신분증 유형
반환 값은 "신분증", "운전면허증", "여권", "알 수 없음" 중 하나임
result.rois BoundingPoly[] 객체 테두리 위치 정보
result.ic json object 주민등록증 정보
result.ic.name StringObject[] 이름(한국어)
result.ic.personalNum StringObject[] 주민등록번호
result.ic.address StringObject[] 주소
result.ic.issueDate DateObject[] 발급 일자
result.ic.authority StringObject[] 발급 기관
result.dl json object 운전면허증 정보
result.dl.type BaseObject[] 면허 유형
result.dl.num StringObject[] 면허 번호
result.dl.name StringObject[] 이름(한국어)
result.dl.personalNum StringObject[] 주민등록번호
result.dl.address StringObject[] 주소
result.dl.renewStartDate DateObject[] 갱신기간 시작일
result.dl.renewEndDate DateObject[] 갱신기간 종료일
result.dl.condition StringObject[] 면허 조건
result.dl.code StringObject[] 면허 코드
result.dl.organDonation BaseObject[] 장기 및 조직 기증 등록
result.dl.issueDate DateObject[] 발급 일자
result.dl.authority StringObject[] 발급 기관
result.pp json object 여권 정보
result.pp.type StringObject[] 여권 유형
result.pp.issueCountry BaseObject[] 발급 국가
result.pp.num StringObject[] 여권 번호
result.pp.surName StringObject[] 성
result.pp.givenName StringObject[] 이름
result.pp.nationality StringObject[] 국적
result.pp.birthDate DateObject[] 생년월일
result.pp.personalNum StringObject[] 주민등록번호
result.pp.sex StringObject[] 성별
result.pp.issueDate DateObject[] 발급 일자
result.pp.expireDate DateObject[] 만료 일자
result.pp.authority BaseObject[] 발행 기관
result.pp.fullNameKor StringObject[] 이름(한국어)
result.pp.MRZ1 StringObject[] 기계판독영역(Machine Readable Zone, MRZ) 1
result.pp.MRZ2 StringObject[] 기계판독영역(Machine Readable Zone, MRZ) 2
result.ac json object 외국인 등록증 정보
result.ac.alienRegNum StringObject[] 외국인 등록번호
result.ac.sex StringObject[] 성별
result.ac.name StringObject[] 이름
result.ac.nationality StringObject[] 국적
result.ac.visaType StringObject[] 비자 유형
result.ac.issueDate DateObject[] 발급 일자
result.ac.authority StringObject[] 발급 기관
result.ac.authorityEng StringObject[] 발급 기관(영문)
result.ac.alienRegNumEtc StringObject[] 외국인 등록번호 등

3. passport 객체 필드

필드명 유형 설명
passportResult json object 인식 결과
passportResult.documentClassCode MrzString 문서 코드. "여권"
passportResult.issuingStateCode MrzString 발급 국가
passportResult.firstName MrzString 이름
passportResult.lastName1 MrzString 첫번째 성
passportResult.lastName2 MrzString 두번째 성
passportResult.documentNumber MrzString 여권번호
passportResult.checkDigitForDocumentNumber MrzString 문서 번호에 대한 확인 숫자
passportResult.nationality MrzString 국적
passportResult.dateOfBirth MrzString 생년월일
passportResult.age MrzInt 나이
passportResult.checkDigitForDateOfBirth MrzString 생년월일에 대한 확인 숫자
passportResult.gender MrzString 성별
passportResult.dateOfExpiry MrzString 만료일자
passportResult.checkDigitForDateOfExpiry MrzString 만료일자에 대한 확인 숫자
passportResult.personalNumber MrzString 주민등록번호
passportResult.checkDigitForPersonalNumber MrzString 주민등록번호에 대한 확인 숫자
passportResult.finalCheckDigit MrzString 최종 확인 숫자
passportResult.mrzType MrzString 기계판독영역(Machine Readable Zone, MRZ) 타입
passportResult.mrzLines MrzString 기계판독영역(Machine Readable Zone, MRZ) 텍스트
passportResult.isExpired Mrzbool 만료됨 
{
    "version": "V2",
    "requestId": "string",
    "timestamp": 1613984872349,
    "images": [
        {
            "nameCard": {
                "meta": {
                    "estimatedLanguage": "ko"
                },
                "result": {
                    "name": [
                        {
                            "text": "홍길동",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 286.0,
                                            "y": 194.0
                                        },
                                        {
                                            "x": 348.0,
                                            "y": 194.0
                                        },
                                        {
                                            "x": 348.0,
                                            "y": 266.0
                                        },
                                        {
                                            "x": 286.0,
                                            "y": 266.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "nameFurigana": [],
                    "company": [
                        {
                            "text": "우리은행",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 317.0,
                                            "y": 274.0
                                        },
                                        {
                                            "x": 356.0,
                                            "y": 274.0
                                        },
                                        {
                                            "x": 356.0,
                                            "y": 316.0
                                        },
                                        {
                                            "x": 317.0,
                                            "y": 316.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "department": [],
                    "address": [
                        {
                            "text": "(홍길동)",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 338.0,
                                            "y": 189.0
                                        },
                                        {
                                            "x": 414.0,
                                            "y": 189.0
                                        },
                                        {
                                            "x": 414.0,
                                            "y": 288.0
                                        },
                                        {
                                            "x": 338.0,
                                            "y": 288.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "position": [
                        {
                            "text": "소장",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 286.0,
                                            "y": 194.0
                                        },
                                        {
                                            "x": 348.0,
                                            "y": 194.0
                                        },
                                        {
                                            "x": 348.0,
                                            "y": 266.0
                                        },
                                        {
                                            "x": 286.0,
                                            "y": 266.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "mobile": [
                        {
                            "text": "010-1234-5678",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 297.0,
                                            "y": 183.0
                                        },
                                        {
                                            "x": 396.0,
                                            "y": 183.0
                                        },
                                        {
                                            "x": 396.0,
                                            "y": 305.0
                                        },
                                        {
                                            "x": 297.0,
                                            "y": 305.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "tel": [
                        {
                            "text": "123-4567-8901",
                            "boundingPolys": [
                                {
                                    "vertices": [
                                        {
                                            "x": 338.0,
                                            "y": 189.0
                                        },
                                        {
                                            "x": 414.0,
                                            "y": 189.0
                                        },
                                        {
                                            "x": 414.0,
                                            "y": 288.0
                                        },
                                        {
                                            "x": 338.0,
                                            "y": 288.0
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "fax": [],
                    "email": [],
                    "homepage": []
                }
            },
            "uid": "3277149ad2324de0b412669f7eac474a",
            "name": "testV2Demo",
            "inferResult": "SUCCESS",
            "message": "SUCCESS",
            "validationResult": {
                "result": "NO_REQUESTED"
            }
        }
    ]
}
JSON

명함 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
nameCard json object nameCard 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌표값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. nameCard 객체 필드

필드명 유형 설명
meta json object 메타 정보
meta.estimatedLanguage string OCR에서 추정한 언어 (en: 영어, ja: 일본어, ko: 한국어)
result json object 인식 결과 객체
result.name StringObject[] 이름 정보
result.nameFurigana StringObject[] 후리가나 이름 정보(언어가 ja일 때만 응답)
result.company StringObject[] 회사 정보
result.department StringObject[] 부서 정보
result.address StringObject[] 주소 정보
result.position StringObject[] 직급 정보
result.mobile TelObject[] 휴대폰 정보
result.tel TelObject[] 전화 정보
result.fax TelObject[] 팩스 정보
result.email StringObject[] 이메일 정보
result.homepage StringObject[] 홈페이지 정보 
{
  "version": "V2",
  "requestId": "string",
  "timestamp": 1621394368343,
  "images": [
    {
      "medicalReceipt": {
        "result": [
          {
            "id": 60,
            "keyTexts": "선택항목|비급여|계",
            "valueText": "53435",
            "confidence": 0.9542916,
            "keyCells": [
              {
                "boundingPoly": {
                  "vertices": [
                    {
                      "x": 303,
                      "y": 16
                    },
                    {
                      "x": 596,
                      "y": 16
                    },
                    {
                      "x": 596,
                      "y": 33
                    },
                    {
                      "x": 303,
                      "y": 33
                    }
                  ]
                },
                "depth": 1,
                "formatted": "선택항목",
                "group": "column",
                "value": "선택항목"
              },
              {
                "boundingPoly": {
                  "vertices": [
                    {
                      "x": 513,
                      "y": 34
                    },
                    {
                      "x": 598,
                      "y": 34
                    },
                    {
                      "x": 598,
                      "y": 50
                    },
                    {
                      "x": 513,
                      "y": 50
                    }
                  ]
                },
                "depth": 2,
                "formatted": "비급여",
                "group": "column",
                "value": "비급여"
              }
            ],
            "valueCell": {
              "boundingPoly": {
                "vertices": [
                  {
                    "x": 513,
                    "y": 195
                  },
                  {
                    "x": 597,
                    "y": 195
                  },
                  {
                    "x": 597,
                    "y": 212
                  },
                  {
                    "x": 513,
                    "y": 212
                  }
                ]
              },
              "confidence": 0.9542916,
              "value": "53435"
            }
          }
        ],
        "checksum": {
          "sumPaidByPatient": {
            "found": false,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [],
            "foundTotalSum": 0,
            "difference": 0
          },
          "sumPaidByInsurer": {
            "found": false,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [],
            "foundTotalSum": 0,
            "difference": 0
          },
          "sumPaidByPatientFull": {
            "found": false,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [],
            "foundTotalSum": 0,
            "difference": 0
          },
          "sumTreatmentCost": {
            "found": false,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [],
            "foundTotalSum": 0,
            "difference": 0
          },
          "sumTreatmentCostEtc": {
            "found": false,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [],
            "foundTotalSum": 0,
            "difference": 0
          },
          "totalAmount": {
            "found": true,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [
              40
            ],
            "foundTotalSum": 1541717,
            "difference": 1541717
          },
          "totalPaid": {
            "found": true,
            "foundValueIds": [],
            "foundValueSum": 0,
            "foundTotalIds": [
              84
            ],
            "foundTotalSum": 102130,
            "difference": 102130
          }
        }
      },
      "uid": "ef80a5d290284373acad3ba23cb4edfc",
      "name": "test 1",
      "inferResult": "SUCCESS",
      "message": "SUCCESS",
      "validationResult": {
        "result": "NO_REQUESTED"
      }
    }
  ]
}
JSON

의료비영수증 OCR의 응답 바디를 설명합니다.
응답 바디 하위의 객체에 대해서는 하단의 "공통 객체 정보"를 참고해주시기 바랍니다.

1. 응답 바디 필드

필드명 유형 설명
uid string API의 유효성 검사를 위해 제공되는 고유 ID로, 유효성 검사 요청을 추적하는 데 사용
name string 요청 바디의 images.name에 입력한 이미지명
inferResult string 이미지 인식 결과
SUCCESS: 이미지 인식 성공
FAILURE: 이미지 인식 실패
ERROR: 이미지 인식 처리예외
message string 이미지 인식 성공 시 SUCCESS 표시
이미지 인식 실패 시 오류 메시지 표시
medicalReceipt json object medicalReceipt 객체 참조
validationResult json object 유효성 검사 결과
validationResult.result string 유효성 검사 결과 코드
NO_REQUESTED: 검증 작업을 요청하지 않음
UNCHECKED: 동작 응답이 확인되지 않거나 응답 미수락
ERROR: 검증 실행에 오류 발생
VALID: 검증 결과가 유효함
INVALID: 검증 결과가 유효하지 않음

※ UNCHECKED,ERROR,INVALID는 유효성 검사 실패로 표시됨
validationResult.message string Validation 세부 메시지로 항상 응답되는 값은 아님
convertedImageInfo json object 이미지 포맷이 pdf 또는 tiff인 경우 응답
좌표값은 이미지로 변환된 호출 파일을 기준으로 함
convertedImageInfo.width integer 변환 이미지 가로 길이
convertedImageInfo.height integer 변환 이미지 세로 길이
convertedImageInfo.pageIndex integer pdf 또는 tiff의 페이지 인덱스

2. medicalReceipt 객체 필드

필드명 유형 설명
checksum json object Checksum results
checksum.sumPaidByPatient Checksum 본인부담금 합계
checksum.sumPaidByInsurer Checksum 공단부담금 합계
checksum.sumPaidByPatientFull Checksum 전액본인부담금 합계
checksum.sumTreatmentCostEtc Checksum 선택진료료 합계
checksum.sumTreatmentCostEtc Checksum 선택진료료이외 합계
checksum.totalAmount Checksum 총액확인
checksum.totalPaid Checksum 환자부담액
result MedicalReceiptResult[] List of value cell results

2. medicalReceiptResult 객체 필드

필드명 유형 설명
id int 셀 ID
keyTexts string “|“ 로 분류된 문자 텍스트
valueText string 응답 셀의 값
confidence float 응답 셀의 신뢰도
keyCells KeyCell[] 키 값 리스트
valueCell ValueCell 응답셀 객체

Document OCR 각 상품의 응답 바디는 아래의 공통 하위 객체를 응답 전문에 반환합니다.
본 챕터에서는 공통 하위 객체에 대한 세부사항을 설명합니다.

field 객체 필드

필드명 유형 설명
text string 인식된 텍스트
confidence float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음
boundingPoly BoundingPoly object boundingPoly 객체 참조
subBoundingPolys BoundingPoly[] boundingPoly 객체 참조

boundingPoly 객체 필드

필드명 유형 설명
vertices vertices object vertices 객체 참조

vertices 객체 필드

필드명 유형 설명
x float x축 좌표값
y float y축 좌표값

baseObject 객체 필드

필드명 유형 설명
text string 인식된 텍스트
boundingPolys BoundingPoly[] boundingPoly 객체 참조
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

dateObject 객체 필드

필드명 유형 설명
text string 인식된 텍스트
formatted json object 인식된 텍스트에 대한 추가 정보
formatted.year string 연. 네 자리 숫자로 연도를 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
formatted.month string 월. 두 자리 숫자로 월을 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
formatted.day string 일. 두 자리 숫자로 날짜를 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
boundingPolys BoundingPoly[] boundingPoly 객체 참조
maskingPolys BoundingPoly[] 개인정보 마스킹
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

timeObject 객체 필드

필드명 유형 설명
text string 인식된 텍스트
formatted json object 인식된 텍스트에 대한 추가 정보
formatted.hour string 시. 두 자리 숫자로 시를 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
formatted.minute string 분. 두 자리 숫자로 분을 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
formatted.second string 초. 두 자리 숫자로 초를 나타냄.
빈 문자열인 경우를 제외하면 ISO 8601 표준 포맷을 따름.
boundingPolys BoundingPoly[] boundingPoly 객체 참조
maskingPolys BoundingPoly[] 개인정보 마스킹
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

TelObject 객체 필드

필드명 유형 설명
text string 인식된 텍스트
formatted json object 인식된 텍스트에 대한 추가 정보
formatted.value string 전화번호 유형을 나타내는 서식 텍스트.
주로 숫자 문자열 형태로 표시되지만 전화 식별자(+)를 포함할 수 있음.
인식 세분화에 실패하면 빈 문자열일 수 있음.
boundingPolys BoundingPoly[] boundingPoly 객체 참조
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

FloatObject 객체 필드

필드명 유형 설명
text string 인식 텍스트
formatted json object 인식된 텍스트에 대한 추가 정보
formatted.value string 실수 유형을 나타내는 서식 있는 텍스트.
실수 문자열 유형. 품목의 개수와 가격을 설명하는 데 유용함.
인식 세분화에 실패하면 빈 문자열일 수 있음.
boundingPolys BoundingPoly[] boundingPoly 객체 참조
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

StringObject 객체 필드

필드명 유형 설명
text string 인식 텍스트
formatted json object 인식된 텍스트에 대한 추가 정보
formatted.value string 정제된 텍스트. 정제 과정은 각 신분증의 분류에 따라 다름
빈 문자열일 수 있음.
boundingPolys BoundingPoly[] boundingPoly 객체 참조
maskingPolys BoundingPoly[] 개인정보
keyText string 인식된 텍스트와 관련된 키 값
confidenceScore float 인식한 텍스트에 대한 신뢰도를 0~1 사이로 나타내며 값이 클수록 정확도가 높음

PoiObject 객체 필드

필드명 유형 설명
gid string 고유 ID
title string 상호명
phone string 전화번호
address string 주소
roadAddress string 도로명주소
biznum string 사업자번호 (아직 정식으로 지원되지 않아 null일 수 있으나 추후 추가될 수 있음)
confidence string 신뢰도 (0~1 사이의 값을 가지며 값이 클수록 정확도가 높음)

Checksum 객체 필드

필드명 유형 설명
found json object 체크섬 필드의 발견 여부를 나타내는 구분자
foundValueIds int[] 발견된 값 셀의 ID 목록
foundValueSum float 발견된 값의 합
foundTotalIds int[] 발견된 전체 셀의 ID 목록
foundTotalSum float 발견된 전체 값의 합
difference float 값과 전체 셀의 차이

KeyCell 객체 필드

필드명 유형 설명
boundingPoly BoundingPoly 셀 테두리 상자 좌표
depth string 발견된 키 셀의 깊이
formatted string 키 셀의 그라운딩 텍스트
group string 열/행별 키를 구분하기 위한 식별자
value string 키 셀의 그라운딩되지 않은 텍스트

ValueCell 객체 필드

필드명 유형 설명
boundingPoly BoundingPoly 셀 테두리 상자 좌표
confidence float 값 셀 신뢰도
value string 값 셀의 텍스트

MrzString 객체 필드

필드명 유형 설명
rawText string 원본 텍스트
refinedText string 정제된 텍스트
postprocessed int32 정제 방식

Mrzbool 객체 필드

Field Name Data Type Description
rawText string 원본 텍스트
refinedText bool 정제된 텍스트
postprocessed int32 정제 방식

MrzInt 객체 필드

Field Name Data Type Description
rawText string 원본 텍스트
refinedText int 정제된 텍스트
postprocessed int32 정제 방식

다음은 각 언어별 CLOVA OCR Document API 구현 예제입니다

multipart/form-data 요청 예제 

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;
 
import org.json.JSONArray;
import org.json.JSONObject;
 
public class OCRAPIDemo {
 
    public static void main(String[] args) {
        String apiURL = "YOUR_API_URL";
        String secretKey = "YOUR_SECRET_KEY";
        String imageFile = "YOUR_IMAGE_FILE";
 
        try {
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setUseCaches(false);
            con.setDoInput(true);
            con.setDoOutput(true);
            con.setReadTimeout(30000);
            con.setRequestMethod("POST");
            String boundary = "----" + UUID.randomUUID().toString().replaceAll("-", "");
            con.setRequestProperty("Content-Type", "multipart/form-data; boundary=" + boundary);
            con.setRequestProperty("X-OCR-SECRET", secretKey);
 
            JSONObject json = new JSONObject();
            json.put("version", "V2");
            json.put("requestId", UUID.randomUUID().toString());
            json.put("timestamp", System.currentTimeMillis());
            JSONObject image = new JSONObject();
            image.put("format", "jpg");
            image.put("name", "demo");
            JSONArray images = new JSONArray();
            images.put(image);
            json.put("images", images);
            String postParams = json.toString();
 
            con.connect();
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            long start = System.currentTimeMillis();
            File file = new File(imageFile);
            writeMultiPart(wr, postParams, file, boundary);
            wr.close();
 
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if (responseCode == 200) {
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
            }
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
 
            System.out.println(response);
        } catch (Exception e) {
            System.out.println(e);
        }
    }
 
    private static void writeMultiPart(OutputStream out, String jsonMessage, File file, String boundary) throws
        IOException {
        StringBuilder sb = new StringBuilder();
        sb.append("--").append(boundary).append("\r\n");
        sb.append("Content-Disposition:form-data; name=\"message\"\r\n\r\n");
        sb.append(jsonMessage);
        sb.append("\r\n");
 
        out.write(sb.toString().getBytes("UTF-8"));
        out.flush();
 
        if (file != null && file.isFile()) {
            out.write(("--" + boundary + "\r\n").getBytes("UTF-8"));
            StringBuilder fileString = new StringBuilder();
            fileString
                .append("Content-Disposition:form-data; name=\"file\"; filename=");
            fileString.append("\"" + file.getName() + "\"\r\n");
            fileString.append("Content-Type: application/octet-stream\r\n\r\n");
            out.write(fileString.toString().getBytes("UTF-8"));
            out.flush();
 
            try (FileInputStream fis = new FileInputStream(file)) {
                byte[] buffer = new byte[8192];
                int count;
                while ((count = fis.read(buffer)) != -1) {
                    out.write(buffer, 0, count);
                }
                out.write("\r\n".getBytes());
            }
 
            out.write(("--" + boundary + "--\r\n").getBytes("UTF-8"));
        }
        out.flush();
    }
}
Java
import requests
import uuid
import time
import json
 
api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'
 
request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo'
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}
 
payload = {'message': json.dumps(request_json).encode('UTF-8')}
files = [
  ('file', open(image_file,'rb'))
]
headers = {
  'X-OCR-SECRET': secret_key
}
 
response = requests.request("POST", api_url, headers=headers, data = payload, files = files)
 
print(response.text.encode('utf8'))
Python
<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_file = "YOUR_IMAGE_FILE";
 
  $params->version = "V2";
  $params->requestId = uniqid();
  $params->timestamp = time();
  $image->format = "jpg";
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);
   
  $boundary = uniqid();
  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  $post_form = array("message" => $json, "file" => new CURLFILE($image_file));
  curl_setopt($ch, CURLOPT_POSTFIELDS, $post_form);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);
 
  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>
PHP

application/json 요청 예제 

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.UUID;
 
import org.json.JSONArray;
import org.json.JSONObject;
 
public class OCRGeneralAPIDemo {
 
    public static void main(String[] args) {
        String apiURL = "YOUR_API_URL";
        String secretKey = "YOUR_SECRET_KEY";
 
        try {
            URL url = new URL(apiURL);
            HttpURLConnection con = (HttpURLConnection)url.openConnection();
            con.setUseCaches(false);
            con.setDoInput(true);
            con.setDoOutput(true);
            con.setRequestMethod("POST");
            con.setRequestProperty("Content-Type", "application/json; charset=utf-8");
            con.setRequestProperty("X-OCR-SECRET", secretKey);
 
            JSONObject json = new JSONObject();
            json.put("version", "V2");
            json.put("requestId", UUID.randomUUID().toString());
            json.put("timestamp", System.currentTimeMillis());
            JSONObject image = new JSONObject();
            image.put("format", "jpg");
            image should be public, otherwise, should use data
            FileInputStream inputStream = new FileInputStream("YOUR_IMAGE_FILE");
            byte[] buffer = new byte[inputStream.available()];
            inputStream.read(buffer);
            inputStream.close();
            image.put("data", buffer);
            image.put("name", "demo");
            JSONArray images = new JSONArray();
            images.put(image);
            json.put("images", images);
            String postParams = json.toString();
 
            DataOutputStream wr = new DataOutputStream(con.getOutputStream());
            wr.writeBytes(postParams);
            wr.flush();
            wr.close();
 
            int responseCode = con.getResponseCode();
            BufferedReader br;
            if (responseCode == 200) {
                br = new BufferedReader(new InputStreamReader(con.getInputStream()));
            } else {
                br = new BufferedReader(new InputStreamReader(con.getErrorStream()));
            }
            String inputLine;
            StringBuffer response = new StringBuffer();
            while ((inputLine = br.readLine()) != null) {
                response.append(inputLine);
            }
            br.close();
 
            System.out.println(response);
        } catch (Exception e) {
            System.out.println(e);
        }
    }
 
}
Java
import requests
import uuid
import time
import base64
import json
 
api_url = 'YOUR_API_URL'
secret_key = 'YOUR_SECRET_KEY'
image_file = 'YOUR_IMAGE_FILE'
with open(image_file,'rb') as f:
file_data = f.read()
 
request_json = {
    'images': [
        {
            'format': 'jpg',
            'name': 'demo',
            'data': base64.b64encode(file_data).decode()
        }
    ],
    'requestId': str(uuid.uuid4()),
    'version': 'V2',
    'timestamp': int(round(time.time() * 1000))
}
 
payload = json.dumps(request_json).encode('UTF-8')
headers = {
  'X-OCR-SECRET': secret_key,
  'Content-Type': 'application/json'
}
 
response = requests.request("POST", api_url, headers=headers, data = payload)
 
print(response.text)
Python
<?php
  $client_secret = "YOUR_SECRET_KEY";
  $url = "YOUR_API_URL";
  $image_file = "YOUR_IMAGE_FILE";
 
  $params->version = "V2";
  $params->requestId = "uuid";
  $params->timestamp = time();
  $image->format = "jpg";
  $image->data = base64_encode(file_get_contents($image_file));
  $image->name = "demo";
  $images = array($image);
  $params->images = $images;
  $json = json_encode($params);
 
  $is_post = true;
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_POST, $is_post);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
  $headers = array();
  $headers[] = "X-OCR-SECRET: ".$client_secret;
  $headers[] = "Content-Type:application/json; charset=utf-8";
  curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
  $response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
  curl_close ($ch);
 
  echo $status_code;
  if($status_code == 200) {
    echo $response;
  } else {
    echo "ERROR: ".$response;
  }
?>
PHP