[PHP - Laravel] 팝빌 홈택스 현금영수증 조회 API 연동 가이드
[PHP - Laravel] 팝빌 홈택스 현금영수증 조회 API 연동 가이드
안녕하세요. 고객의 가치를 연결하는 비즈니스 파트너 링크허브 입니다.
본 포스팅에서는 PHP Laravel 개발환경에서 고객사들이 팝빌 홈택스 현금영수증 조회 API SDK를 쉽고 빠르게 이용할 수 있도록, 예시를 이용하여 연동 설정 방법을 안내드리겠습니다. 먼저, Composer를 이용하여 SDK 추가한 후 홈택스 현금영수증 조회 함수를 구현하는 순서로 진행하겠습니다.
팝빌 PHP Composer SDK는 PHP v7.1.3 이상의 환경에서 이용이 가능하며, API 호출과 응답의 메시지 인코딩은 "UTF-8 Character-Set"을 지원합니다.
"팝빌은 링크허브에서 자체 개발하고 직접 운영하는 홈택스 현금영수증 서비스 Brand Name 입니다."
아래 설명하는 예시는 [ Laravel 5.7 | PHP v7.1.16 ] 기준으로 작성되어 있어, 이용 중이신 개발환경과 차이가 있을 수 있는 점 감안해 주시기 바랍니다.
1. 서버환경 구성
SDK 설치를 위해 PHP Composer 와 PHP (v7.1.3 이상) 이 설치 되어 있어야 합니다.
$ php -v PHP 7.1.16 (cli) (built: Mar 31 2018 02:59:59) ( NTS ) Copyright (c) 1997-2018 The PHP Group Zend Engine v3.1.0, Copyright (c) 1998-2018 Zend Technologies
$ composer ______ / ____/___ ____ ___ ____ ____ ________ _____ / / / __ \/ __ `__ \/ __ \/ __ \/ ___/ _ \/ ___/ / /___/ /_/ / / / / / / /_/ / /_/ (__ ) __/ / \____/\____/_/ /_/ /_/ .___/\____/____/\___/_/ /_/ Composer version 1.8.3 2019-01-30 08:31:33 Usage: command [options] [arguments] Options: -h, --help Display this help message -q, --quiet Do not output any message -V, --version Display this application version --ansi Force ANSI output --no-ansi Disable ANSI output -n, --no-interaction Do not ask any interactive question --profile Display timing and memory usage information --no-plugins Whether to disable plugins. -d, --working-dir=WORKING-DIR If specified, use the given directory as working directory.
2. Popbill SDK Composer 설치 & Config 추가
Laravel 프로젝트에서 Composer를 통한 Popbill SDK 설치를 위해 아래와 같이 composer.json 파일의 "require" 필드 오브젝트에 Popbill SDK 정보를 추가합니다.
FilePath : composer.json
{ "name": "laravel/laravel", "type": "project", "description": "The Laravel Framework.", "keywords": [ "framework", "laravel" ], "license": "MIT", "require": { "php": "^7.1.3", "fideloper/proxy": "^4.0", "laravel/framework": "5.7.*", "laravel/tinker": "^1.0", "linkhub/popbill": "^1.0.14" },
// 생략..
composer.json 파일 수정후 composer update 커멘드를 실행하여 popbill 패키지를 설치합니다.
$ composer update Loading composer repositories with package information Updating dependencies (including require-dev) Package operations: 2 installs, 0 updates, 0 removals - Installing linkhub/linkhub (1.0.11): Loading from cache - Installing linkhub/popbill (1.0.14): Loading from cache Writing lock file Generating optimized autoload files > Illuminate\Foundation\ComposerScripts::postAutoloadDump > @php artisan package:discover --ansi Discovered Package: beyondcode/laravel-dump-server Discovered Package: fideloper/proxy Discovered Package: laravel/nexmo-notification-channel Discovered Package: laravel/slack-notification-channel Discovered Package: laravel/tinker Discovered Package: nesbot/carbon Discovered Package: nunomaduro/collision Package manifest generated successfully.
Popbill SDK의 환경설정을 위해 laravel 프로젝트 config 폴더에 popbill.php 파일을 추가합니다.
FilePath : /config/popbill.php
▶ 링크허브에서 발급받은 고객사 인증정보로 링크아이디(LinkID)와 비밀키(SecretKey) 값을 변경하시기 바랍니다.
'TESTER', // 파트너 신청시 발급받은 비밀키 'SecretKey' => 'SwWxqU+0TErBXy/9TVjIPEnI0VTUMMSQZtJf3Ed8q3I=', // 통신방식 기본은 CURL , PHP curl 모듈 사용에 문제가 있을 경우 STREAM 기재가능. // STREAM 사용시에는 php.ini의 allow_url_fopen = on 으로 설정해야함. 'LINKHUB_COMM_MODE' => 'CURL', // 연동환경 설정값, 개발용(true), 상업용(false) 'IsTest' => true, ];
3. API 구현
테스트를 위해 Laravel Controller 를 추가합니다.
$ php artisan make:controller TaskController Controller created successfully.
추가한 컨트롤러에 홈택스 현금영수증 조회 서비스를 구현하기 위해 사용할 클래스들을 use 구문으로 선언합니다. (use 구문으로 선언해야하는 클래스명은 아래의 예제 코드를 참조)
생성자 __construct() 함수를 추가하고, 아래의 코드를 참조하여 홈택스 현금영수증 조회 서비스 클래스 인스턴스를 생성하는 코드를 작성합니다.
FilePath : /app/Http/Controllers/TaskController.php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Linkhub\LinkhubException; use Linkhub\Popbill\JoinForm; use Linkhub\Popbill\CorpInfo; use Linkhub\Popbill\ContactInfo; use Linkhub\Popbill\ChargeInfo; use Linkhub\Popbill\PopbillException; use Linkhub\Popbill\PopbillHTCashbill; use Linkhub\Popbill\HTCBKeyType;
class TaskController extends Controller { public function __construct() {
// 통신방식 설정 define('LINKHUB_COMM_MODE', config('popbill.LINKHUB_COMM_MODE')); // 홈택스 현금영수증 서비스 클래스 초기화 $this->PopbillHTCashbill = new PopbillHTCashbill(config('popbill.LinkID'), config('popbill.SecretKey')); // 연동환경 설정값, 개발용(true), 상업용(false) $this->PopbillHTCashbill->IsTest(config('popbill.IsTest'));
}
// 통신방식 설정 define('LINKHUB_COMM_MODE', config('popbill.LINKHUB_COMM_MODE')); // 홈택스 현금영수증 서비스 클래스 초기화 $this->PopbillHTCashbill = new PopbillHTCashbill(config('popbill.LinkID'), config('popbill.SecretKey')); // 연동환경 설정값, 개발용(true), 상업용(false) $this->PopbillHTCashbill->IsTest(config('popbill.IsTest'));
// 컨트롤러 함수 추가 영역.
아래의 흐름도는 홈택스 현금영수증 조회를 구현하기 위한 함수 프로세스 순서도 입니다.
순서도에 따라서 함수를 구현하기 위해 TaskController에 RequestJob, GetJobState API를 각각 function으로 추가합니다. - Search API에 대한 예제는 제공되는 SDK 예제코드 /app/Http/Controllers/HTCashbillController.php 에 선언된 Search() 함수를 참조하시기 바랍니다.
RequestJob API 열기 RequestJob API 닫기 public function RequestJob(){ // 팝빌회원 사업자번호, '-'제외 10자리 $testCorpNum = '1234567890'; // 현금영수증, SELL-매출, BUY-매입 $CBType = HTCBKeyType::BUY; // 시작일자, 형식(yyyyMMdd) $SDate = '20180101'; // 종료일자, 형식(yyyyMMdd) $EDate = '20180501'; try { $jobID = $this->PopbillHTCashbill->RequestJob( $testCorpNum, $CBType, $SDate, $EDate); } catch(PopbillException | LinkhubException $pe) { $code = $pe->getCode(); $message = $pe->getMessage(); return '응답코드 : '.$code.PHP_EOL.'응답메시지 : '.$message } return '작업아이디(jobID) : '.$jobID; } RequestJob API 닫기
GetJobState API 열기 GetJobState API 닫기 public function GetJobState(){ // 팝빌회원 사업자번호, '-'제외 10자리 $testCorpNum = '1234567980'; // 수집 요청시 반환받은 작업아이디 $jobID = '019021509000000001'; try { $result = $this->PopbillHTCashbill->GetJobState($testCorpNum, $jobID); } catch (PopbillException | LinkhubException $pe) { $code = $pe->getCode(); $message = $pe->getMessage(); return view('PResponse', ['code' => $code, 'message' => $message]); } return view('JobState', ['Result' => [$result] ] ); } GetJobState API 닫기
TaskController에 추가한 함수를 호출할 수 있도록 Route에 Controller와 함수명을 매핑합니다.
FilePath : /routes/web.php
RequestJob 함수 호출시 반환되는 작업아이디(JobID)를 GetJobState 함수에 선언된 작업아이디 변수에 기재하여 함수호출 결과를 확인합니다.
예) RequestJob (수집요청) 함수호출 성공처리
예) GetJobState (수집상태확인) 함수호출 성공처리
예) 함수호출 실패처리 (코드, 메시지 반환)
GetJobState 응답항목의 jobState(수집상태) 값이 3(완료) 이면서 errorCode(오류코드) 값이 1(수집성공) 로 반환되면 해당 작업아이디(jobID)를 사용하여 Search API 를 호출합니다.
- Search API에 대한 예제는 제공되는 SDK 예제코드 /app/Http/Controllers/HTCashbillController.php 에 선언된 Search() 함수를 참조하시기 바랍니다.
- errorCode(오류코드) 값이 1이 아닌 값 (-로 시작하는 8자리 숫자값) 이 반환되는 경우 errReason(오류사유) 필드를 확인하시기 바랍니다.
[참고] 팝빌 연동 개발을 위한 테스트베드(개발용) 안내 - https://linkhub.tistory.com/91
팝빌에서 제공하는 다양한 API는 동일한 컨셉으로 개발되어 있어, 하나의 서비스를 이용한 경험이 있으면 다른 서비스들도 유사한 방법으로 빠르게 연동이 가능하니 많은 이용 부탁드립니다.
지금까지 PHP Laravel 개발환경에서 홈택스 현금영수증 조회 API를 연동하는 방법에 대해 안내드렸습니다. 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락주시기 바랍니다.
고객사의 편의를 위하여 이메일, 전화 등 다양한 채널을 열어놓고 있으니 언제든지 연락 주시기 바랍니다.
기술지원센터 / T. 1600-9854 / E. code@linkhub.co.kr
from http://linkhub.tistory.com/193 by ccl(S) rewrite - 2020-03-11 03:54:35
댓글
댓글 쓰기