Ncloud Clova OCR - Template OCR API 연동 PHP 샘플 예제

Ncloud (네이버 클라우드) Clova OCR API를 이용해 Template OCR을 사용하는 방법 안내입니다

Tip: 기술문서 사이트가 리뉴얼 되었습니다.

개요

Ncloud (네이버 클라우드) [Clova OCR]은 전송한 문서나 이미지를 인식하여 사용자가 지정한 영역의 텍스트와 데이터를 정확하게 추출하는 서비스입니다. 여기서는 API를 이용해서 Template OCR로 [사업자등록증]을 인식하는 예제를 PHP 코드로 정리해보겠습니다.

서비스 배포

테스트는 Template을 미리 생성한 상태에서 진행해보겠습니다. Template 생성 방법은 아래 링크의 문서에서 확인하시면 됩니다.

Ncloud Clova OCR 서비스 중에서 Template OCR 사용 방법

[배포 관리]에서 [서비스 배포] 버튼을 클릭해서 해당 템플릿을 서비스 배포합니다.

Ncloud (네이버 클라우드) Clova OCR 서비스 중에서 Template OCR을 사용하는 방법 안내

서비스 배포 확인 팝업창에서 [확인] 버튼을 클릭합니다.

[서비스 배포]가 완료되면 아래와 같이 배포 상태와 배포 종료 시간을 확인할 수 있습니다.

API Gateway 연동

[설정] - [API Gateway 연동] 탭에서 [연동] 버튼을 클릭합니다.

[API Gateway 연동]은 기본이 자동 연동입니다. API 연동에 필요한 [Secret Key]를 만들기 위해서 [생성] 버튼을 클릭합니다.

생성된 [Secret key]와 [API Gateway Invoke URL]을 복사해서 API 연동 코드에 사용합니다.

인식 필드

API 연동 코드를 작성하기 전에 이전에 생성했던 템플릿에서 인식 필드를 다시 한번 확인했보겠습니다.

필드 01: 등록번호
필드 02: 법인명
필드 03: 대표자
필드 04: 사업장 소재지
필드 05: 업태
필드 06: 종목

PHP 샘플 코드

Clova OCR API는 크게 2가지 방법으로 나눌 수 있습니다.

파일 URL을 전달하는 방법
파일을 업로드하는 방법

아래 PHP 코드는 2가지 방법으로 각각 구현되어 있습니다. 그리고 각 코드의 상세 설명은 아래쪽에서 정리해보겠습니다.

<?php  

  // Secret Key
  $ncloud_clova_ocr_secretkey = "Ijkouhuh89bj89yBHt86ghvhj&T*^VHJ&T*R^FVHJHJ";  

  // API Gateway Invoke URL
  $api_url = "https://***.apigw.ntruss.com/custom/v1/28410/****중간 생략****/infer";

  // Template ID
  $ncloud_clova_ocr_template_ids = [28222];
    
  $unixtimestamp =  round(microtime(true) * 1000);

  // http 호출 헤더값 설정
  $http_header = array();        
  $http_header[0] = "X-OCR-SECRET: ".$ncloud_clova_ocr_secretkey."";
  $http_header[1] = "Content-Type:application/json; charset=utf-8";

  $ocr_request_id = "ocr-test".$unixtimestamp;

  // 전송할 값들을 배열 형태로 저장
  $postvars = [
    "version"=> "V2",
    "requestId"=> $ocr_request_id,
    "timestamp"=> $unixtimestamp,
    "lang"=> "ko",
    "images"=> [
      [
        "format"=> "jpg",
        "name"=> "ocr-test",
        "data"=> null,
        "url"=> "https://kr.object.ncloudstorage.com/(버킷 이름)/ocr-test.jpg",
        "templateIds"=> $ncloud_clova_ocr_template_ids
      ]
    ]
  ];

  // 배열 형태로 저장한 값들을 json 형태로 변환
  $json_portvars = json_encode($postvars);

  // api 호출
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $api_url);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);  
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $http_header);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $json_portvars);

  $json_response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  
  if ($json_response && $status_code == "200")
  {
    $obj_response_array = json_decode($json_response, true);

    $obj_clova_ocr_data = $obj_response_array["images"][0];

    // 사업자 등록번호
    $business_number = $obj_clova_ocr_data["fields"][0];
    $business_number= $business_number["inferText"];

    //=============== 중간 생략 ================= //

    // 종목
    $business_item = $obj_clova_ocr_data["fields"][5];
    $business_item= $business_item["inferText"];

    echo("사업자 등록번호:".$business_number."<br />");
    echo("종목:".$business_item."<br />");
  } 
  else 
  {
    $obj_error_response_array = json_decode($json_response, true);
  }

  
?>

<?php  

  // 업로드한 파일을 바이너리로 읽어서 BASE64로 인코딩
  $ocr_upload_file = $_FILES["clova_ocr_upload_file"];
  $ocr_upload_file_tmp_name = $ocr_upload_file["tmp_name"];

  $ocr_upload_file_binary = fread(fopen($ocr_upload_file_tmp_name, "r"), filesize($ocr_upload_file_tmp_name));
  $ocr_upload_file_string = base64_encode($ocr_upload_file_binary);

  // Secret Key
  $ncloud_clova_ocr_secretkey = "Ijkouhuh89bj89yBHt86ghvhj&T*^VHJ&T*R^FVHJHJ";  

  // API Gateway Invoke URL
  $api_url = "https://***.apigw.ntruss.com/custom/v1/28410/****중간 생략****/infer";

  // Template ID
  $ncloud_clova_ocr_template_ids = [28222];
    
  $unixtimestamp =  round(microtime(true) * 1000);

  // http 호출 헤더값 설정
  $http_header = array();        
  $http_header[0] = "X-OCR-SECRET: ".$ncloud_clova_ocr_secretkey."";
  $http_header[1] = "Content-Type:application/json; charset=utf-8";

  $ocr_request_id = "ocr-test".$unixtimestamp;

  // 전송할 값들을 배열 형태로 저장
  $postvars = [
    "version"=> "V2",
    "requestId"=> $ocr_request_id,
    "timestamp"=> $unixtimestamp,
    "lang"=> "ko",
    "images"=> [
      [
        "format"=> "jpg",
        "name"=> "ocr-test",
        "data"=> $clova_ocr_upload_file_string,
        "url"=> null,
        "templateIds"=> $ncloud_clova_ocr_template_ids
      ]
    ]
  ];

  // 배열 형태로 저장한 값들을 json 형태로 변환
  $json_portvars = json_encode($postvars);

  // api 호출
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $api_url);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);  
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $http_header);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $json_portvars);

  $json_response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);

  curl_close($ch);

  
  if ($json_response && $status_code == "200")
  {
    $obj_response_array = json_decode($json_response, true);

    $obj_clova_ocr_data = $obj_response_array["images"][0];

    // 사업자 등록번호
    $business_number = $obj_clova_ocr_data["fields"][0];
    $business_number= $business_number["inferText"];

    //=============== 중간 생략 ================= //

    // 종목
    $business_item = $obj_clova_ocr_data["fields"][5];
    $business_item= $business_item["inferText"];

    echo("사업자 등록번호:".$business_number."<br />");
    echo("종목:".$business_item."<br />");
  } 
  else 
  {
    $obj_error_response_array = json_decode($json_response, true);
  }

  
?>

코드 상세 설명

우선, 도메인에서 API Gateway 연동 후에 생성된 Secret Key와 Invoke URL을 복사해서 입력하고, Template ID도 설정합니다.

<?php  
  // Secret Key
  $ncloud_clova_ocr_secretkey = "Ijkouhuh89bj89y****중간 생략****j&T*^VHJ&T*R^FVHJHJ";  

  // API Gateway Invoke URL
  $api_url = "https://***.apigw.ntruss.com/custom/v1/*****/****중간 생략****/infer";

  // Template ID
  $ncloud_clova_ocr_template_ids = [28222];
?>

다음으로 http 호출 헤더값으로, 위에서 변수에 저장했던 Secret Key와 Content-Type을 설정합니다.

<?php
  // http 호출 헤더값 설정
  $http_header = array();        
  $http_header[0] = "X-OCR-SECRET: ".$ncloud_clova_ocr_secretkey."";
  $http_header[1] = "Content-Type:application/json; charset=utf-8";
?>

다음으로 POST로 전송할 값들을 json 형태로 저장합니다.

<?php
  // 전송할 값들을 배열 형태로 저장
  $postvars = [
    "version"=> "V2",
    "requestId"=> $ocr_request_id,
    "timestamp"=> $unixtimestamp,
    "lang"=> "ko",
    "images"=> [
      [
        "format"=> "jpg",
        "name"=> "ocr-test",
        "data"=> null,
        "url"=> "https://kr.object.ncloudstorage.com/(버킷 이름)/ocr-test.jpg",
        "templateIds"=> $ncloud_clova_ocr_template_ids
      ]
    ]
  ];

  // 배열 형태로 저장한 값들을 json 형태로 변환
  $json_portvars = json_encode($postvars);
?>

<?php
  // 업로드한 파일을 바이너리로 읽어서 BASE64로 인코딩
  $ocr_upload_file = $_FILES["clova_ocr_upload_file"];
  $ocr_upload_file_tmp_name = $ocr_upload_file["tmp_name"];

  $ocr_upload_file_binary = fread(fopen($ocr_upload_file_tmp_name, "r"), filesize($ocr_upload_file_tmp_name));
  $ocr_upload_file_string = base64_encode($ocr_upload_file_binary);

  // 전송할 값들을 배열 형태로 저장
  $postvars = [
    "version"=> "V2",
    "requestId"=> $ocr_request_id,
    "timestamp"=> $unixtimestamp,
    "lang"=> "ko",
    "images"=> [
      [
        "format"=> "jpg",
        "name"=> "ocr-test",
        "data"=> $ocr_upload_file_string,
        "url"=> null,
        "templateIds"=> $ncloud_clova_ocr_template_ids
      ]
    ]
  ];

  // 배열 형태로 저장한 값들을 json 형태로 변환
  $json_portvars = json_encode($postvars);
?>

version: “V2”로 고정
requestId: 임의의 값
timestamp: UNIX TimeStamp
lang: 판독할 문서의 언어
images: 판독할 문서의 정보
- format: 문서 포맷 (jpg, jpeg, png, tiff, pdf 등)
- name: 임의의 값
- data: 파일을 업로드할 경우의 파일 데이터, URL을 전송할 경우 이 값은 null로 설정
- url: 파일의 url을 전송할 경우에 사용, 파일을 업로드할 경우 이 값은 null로 설정
- templateIds: 판독에 사용할 Template 아이디들을 배열 형태로 설정

준비를 모두 마쳤으면 API를 호출합니다.

<?php
  // api 호출
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_URL, $api_url);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);  
  curl_setopt($ch, CURLOPT_POST, TRUE);
  curl_setopt($ch, CURLOPT_HTTPHEADER, $http_header);
  curl_setopt($ch,CURLOPT_POSTFIELDS, $json_portvars);

  $json_response = curl_exec($ch);
  $err = curl_error($ch);
  $status_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
?>

마지막으로 API 호출 후 반환된 결과 값을 파싱해서 출력해봅니다.

<?php
    $obj_response_array = json_decode($json_response, true);

    $obj_clova_ocr_data = $obj_response_array["images"][0];

    // 사업자 등록번호
    $business_number = $obj_clova_ocr_data["fields"][0];
    $business_number= $business_number["inferText"];

    //=============== 중간 생략 ================= //

    // 종목
    $business_item = $obj_clova_ocr_data["fields"][5];
    $business_item= $business_item["inferText"];

    echo("사업자 등록번호:".$business_number."<br />");
    echo("종목:".$business_item."<br />");
?>

Template을 생성할 때 설정했던 인식 필드에서 [필드 01]은 첫번째 값으로 반환되므로 여기서는 $obj_clova_ocr_data[“fields”][0]에 해당됩니다. 마찬가지로 나머지 필드도 순서대로 가져오면 인식된 값을 확인할 수 있습니다.

결과

참고 URL

Ncloud CLOVA OCR 기본 가이드
- https://guide.ncloud-docs.com/docs/ko/clovaocr-overview
Ncloud CLOVA OCR Template 생성 가이드
- https://guide.ncloud-docs.com/docs/clovaocr-template

문서 업데이트 내역

날짜	내용
2024-02-19	문서 최초 생성

Tags: