의료비영수증

특화 모델 엔진을 사용하여 의료비영수증의 입력 정보(key-value)를 인식하고 추출합니다.

요청

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

메서드	URI	설명
POST	/medical-receipt	의료비영수증

요청 헤더

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

요청 바디

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

`Content-Type: application/json`인 경우

요청 헤더 Content-Type이 application/json인 경우의 요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`version`	String	-	버전 정보 `V2`만 사용
`requestId`	String	Required	임의의 API 호출 UUID
`timestamp`	Integer	Required	임의의 API 호출 시각(Timestamp)
`images`	Array	Required	images 세부 정보

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

요청 헤더 Content-Type이 multipart/form-data인 경우의 요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`message`	Object	Required	요청 데이터 정보
`message.version`	String	Required	버전 정보 `V2`만 사용
`message.requestId`	String	Required	임의의 API 호출 UUID
`message.timestamp`	Integer	Required	임의의 API 호출 시각(Timestamp)
`message.images`	Array	Required	images 세부 정보
`file`	File	Required	OCR 인식 이미지 파일

`images`

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

필드	타입	필수 여부	설명
`format`	String	Required	이미지 형식 `jpg` \| `jpeg` \| `png` \| `pdf` \| `tif` \| `tiff` 이미지: `jpg`, `jpeg`, `png` 단일 페이지: `pdf`, `tif`, `tiff` 이미지 형식 중 하나를 선택하여 입력
`name`	String	Required	임의의 이미지 이름 이미지 식별 및 응답 결과 확인 시 사용
`data`	String	Required	Base64 인코딩된 이미지 데이터 `Content-Type: application/json`일 때 입력 가능

요청 예시

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

`Content-Type: application/json`인 경우

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

curl --location --request POST 'https://cbgrx5natw.apigw.fin-ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/medical-receipt' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {앱 등록 시 발급받은 Secret Key}' \
--data '{
    "version": "V2",
    "requestId": "string",
    "timestamp": 0,
    "images": [
        { 
            "format": "png", 
            "name": "medical_receipt_test", 
            "data":"{Base64 인코딩된 이미지 데이터}"
        }
    ]
 }'

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

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

curl --location --request POST 'https://cbgrx5natw.apigw.fin-ntruss.com/custom/v1/{DomainId}/{InvokeKey}/document/medical-receipt' \
--header 'Content-Type: application/json' \
--header 'X-OCR-SECRET: {앱 등록 시 발급받은 Secret Key}' \
--form 'message="{\"version\": \"V2\", \"requestId\": \"1234\", \"timestamp\": 0, \"images\": [{\"format\": \"png\", \"name\": \"medical_receipt_test\"}]}"' \
--form 'file=@"{file}"'

응답

응답 형식을 설명합니다.

응답 바디

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

필드	타입	필수 여부	설명
`version`	String	-	버전 정보 `V2`만 사용
`requestId`	String	-	API 호출 UUID
`timestamp`	Integer	-	API 호출 시각(Timestamp)
`images`	Array	-	images 세부 정보

`images`

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

필드	타입	필수 여부	설명
`uid`	String	-	의료비영수증 이미지 UID API 유효성 검사 시 사용
`name`	String	-	의료비영수증 이미지 이름 이미지 식별 및 응답 결과 확인 시 사용
`inferResult`	String	-	의료비영수증 이미지 인식 결과 `SUCCESS` \| `FAILURE` \| `ERROR` `SUCCESS`: 인식 성공 `FAILURE`: 인식 실패 `ERROR`: 인식 처리 예외
`message`	String	-	결과 메시지
`validationResult`	Object	-	유효성 검사 결과 정보
`validationResult.result`	String	-	유효성 검사 결과 코드 `NO_REQUESTED` \| `UNCHECKED` \| `ERROR` \| `VALID` \| `INVALID` `NO_REQUESTED`: 검증 작업 미요청(유효성 검사 실패) `UNCHECKED`: 검증 여부 확인 불가 `ERROR`: 검증 시 에러 발생(유효성 검사 실패) `VALID`: 검증 결과 유효(유효성 검사 성공) `INVALID`: 검증 통과 실패
`validationResult.message`	String	-	유효성 검사 결과 세부 메시지 항상 응답되는 값은 아님
`medicalReceipt`	Object	-	의료비영수증 세부 정보
`medicalReceipt.result`	Object	-	의료비영수증 OCR 인식 결과
`medicalReceipt.checksum`	Object	-	의료비영수증 OCR 금액 인식 결과

`result`

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

필드	타입	필수 여부	설명
`id`	Integer	-	셀 ID
`keyTexts`	String	-	“\|“ 로 나눠지거나 단일 텍스트로 이루어진 키 값
`valueText`	String	-	셀에서 인식된 텍스트
`confidence`	Float	-	인식된 텍스트의 신뢰도
`keyCells`	Array	-	keyCell 상세 정보
`valueCell`	Array	-	valueCell 상세 정보

`checksum`

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

필드	타입	필수 여부	설명
`sumPaidByPatient`	Checksum	-	본인부담금 합계 상세 정보
`sumPaidByInsurer`	Checksum	-	공단부담금 합계 상세 정보
`sumPaidByPatientFull`	Checksum	-	전액본인부담금 합계 상세 정보
`sumTreatmentCost`	Checksum	-	선택진료비 합계 상세 정보
`sumTreatmentCostEtc`	Checksum	-	선택진료비 외 합계 상세 정보
`totalAmount`	Checksum	-	총액 상세 정보
`totalPaid`	Checksum	-	환자부담액 상세 정보

keyCell

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

필드	타입	필수 여부	설명
`boundingPoly`	Array	-	boundingPoly 세부 정보
`depth`	String	-	키 셀의 뎁스
`formatted`	String	-	키 셀의 그라운딩 텍스트
`group`	String	-	키 셀의 열/행 구분자
`value`	String	-	키 셀의 그라운딩되지 않은 텍스트

valueCell

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

필드	타입	필수 여부	설명
`boundingPoly`	Array	-	boundingPoly 세부 정보
`confidence`	Float	-	value 셀의 신뢰도
`value`	String	-	value 셀의 텍스트

`boundingPoly`

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

필드	타입	필수 여부	설명
`vertices`	Array	-	vertices 세부 정보

`boundingPolyVertices`

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

필드	타입	필수 여부	설명
`x`	Float	-	X축 좌표 값
`y`	Float	-	Y축 좌표 값

found

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

필드	타입	필수 여부	설명
`found`	Boolean	-	Checksum 상세 정보 보유 여부 `true` \| `false` `true`: 보유 `false`: 미보유
`foundValueIds`	Int	-	발견된 value 셀의 ID 목록
`foundValueSum`	String	-	발견된 value 셀의 합계
`foundTotalIds`	Int	-	발견된 전체 셀의 ID 목록
`foundTotalSum`	Int	-	발견된 전체 값의 합계
`difference`	Float	-	값과 전체 셀의 차액

응답 예시

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

성공

호출이 성공한 경우의 응답 예시는 다음과 같습니다.

{
  "version": "V2",
  "requestId": "1234",
  "timestamp": 1747728974248,
  "images": [
    {
      "uid": "{uid}",
      "name": "medical_receipt_test",
      "inferResult": "SUCCESS",
      "message": "SUCCESS",
      "validationResult": {
        "result": "NO_REQUESTED"
      },
      "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
          }
        }
      }
    }
  ]
}

실패

호출이 실패한 경우의 응답 예시는 다음과 같습니다.

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

의료비영수증

요청

요청 헤더

요청 바디

Content-Type: application/json인 경우

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

images

요청 예시

Content-Type: application/json인 경우

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

응답

응답 바디

images

result

checksum

keyCell

valueCell

boundingPoly

boundingPolyVertices

found

응답 예시

성공

실패

`Content-Type: application/json`인 경우

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

`images`

`Content-Type: application/json`인 경우

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

`images`

`result`

`checksum`

`boundingPoly`

`boundingPolyVertices`