[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) 값을 변경하시기 바랍니다.

<?php

return [

    // 파트너 신청시 발급받은 링크아이디
    'LinkID' => '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

<?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\PopbillStatement;
use Linkhub\Popbill\Statement;
use Linkhub\Popbill\StatementDetail;

class TaskController extends Controller
{
  public function __construct() {

    // 통신방식 설정
    define('LINKHUB_COMM_MODE', config('popbill.LINKHUB_COMM_MODE'));

    // 전자명세서 서비스 클래스 초기화
    $this->PopbillStatement = new PopbillStatement(config('popbill.LinkID'), config('popbill.SecretKey'));

    // 연동환경 설정값, 개발용(true), 상업용(false)
    $this->PopbillStatement->IsTest(config('popbill.IsTest'));
  }


// 컨트롤러 함수 추가 영역.
}

TaskController에 전자명세서 발행 API를 호출하는 함수를 추가합니다.

public function RegistIssue(){

    // 팝빌 회원 사업자번호, '-' 제외 10자리
    $testCorpNum = '1234567890';

    // 전자명세서 문서관리번호
    // 1~24자리 숫자, 영문, '-', '_' 조합으로 사업자별로 중복되지 않도록 구성
    $mgtKey = '20190213-001';

    // 명세서 종류코드 - 121(거래명세서), 122(청구서), 123(견적서) 124(발주서), 125(입금표), 126(영수증)
    $itemCode = '121';

    // 메모
    $memo = '즉시발행 메모';

    // 전자명세서 객체 생성
    $Statement = new Statement();

    /************************************************************
     *                       전자명세서 정보
     ************************************************************/

    // [필수] 기재상 작성일자
    $Statement->writeDate = '20190213';

    // [필수] (영수, 청구) 중 기재
    $Statement->purposeType = '영수';

    // [필수]  과세형태, (과세, 영세, 면세) 중 기재
    $Statement->taxType = '과세';

    // 맞춤양식코드, 미기재시 기본양식으로 처리
    $Statement->formCode = '';

    // 명세서 종류 코드
    $Statement->itemCode = $itemCode;

    // 전자명세서 문서관리번호
    $Statement->mgtKey = $mgtKey;

    /************************************************************
     *                         공급자 정보
     ************************************************************/
    $Statement->senderCorpNum = $testCorpNum;
    $Statement->senderTaxRegID = '';
    $Statement->senderCorpName = '공급자 상호';
    $Statement->senderCEOName = '공급자 대표자 성명';
    $Statement->senderAddr = ' 공급자 주소';
    $Statement->senderBizClass = '공급자 업종';
    $Statement->senderBizType = '공급자 업태';
    $Statement->senderContactName = '공급자 담당자명';
    $Statement->senderTEL = '070-7070-0707';
    $Statement->senderHP = '010-000-2222';
    $Statement->senderEmail = 'test@test.com';

    /************************************************************
     *                         공급받는자 정보
     ************************************************************/
    $Statement->receiverCorpNum = '8888888888';
    $Statement->receiverTaxRegID = '';						// 공급받는자 종사업장 식별번호, 필요시 기재. 형식은 숫자 4자리
    $Statement->receiverCorpName = '공급받는자 상호';
    $Statement->receiverCEOName = '공급받는자 대표자 성명';
    $Statement->receiverAddr = '공급받는자 주소';
    $Statement->receiverBizClass = '공급받는자 업종';
    $Statement->receiverBizType = '공급받는자 업태';
    $Statement->receiverContactName = '공급받는자 담당자명';
    $Statement->receiverTEL = '010-0000-1111';
    $Statement->receiverHP = '010-1111-2222';
    $Statement->receiverEmail = 'test@test.com';

    /************************************************************
     *                       전자명세서 기재정보
     ************************************************************/
    $Statement->supplyCostTotal = '200000' ;				// [필수] 공급가액 합계
    $Statement->taxTotal = '20000';							// [필수] 세액 합계
    $Statement->totalAmount = '220000';						// [필수] 합계금액 (공급가액 합계+세액합계)
    $Statement->serialNum = '123';							// 기재상 일련번호 항목
    $Statement->remark1 = '비고1';
    $Statement->remark2 = '비고2';
    $Statement->remark3 = '비고3';
    $Statement->businessLicenseYN = False;					//사업자등록증 첨부 여부
    $Statement->bankBookYN = False;							//통장사본 첨부 여부
    $Statement->smssendYN = False;							//발행시 안내문자 전송여부

    /************************************************************
     *                       상세항목(품목) 정보
     ************************************************************/
    $Statement->detailList = array();
    $Statement->detailList[0] = new StatementDetail();
    $Statement->detailList[0]->serialNum = '1';					//품목 일련번호 1부터 순차 기재
    $Statement->detailList[0]->purchaseDT = '20190101';			//거래일자 yyyyMMdd
    $Statement->detailList[0]->itemName = '품명';
    $Statement->detailList[0]->spec = '규격';
    $Statement->detailList[0]->unit = '단위';
    $Statement->detailList[0]->qty = '1000';						//수량
    $Statement->detailList[0]->unitCost = '1000000';
    $Statement->detailList[0]->supplyCost = '10000000';
    $Statement->detailList[0]->tax = '1000000';
    $Statement->detailList[0]->remark = '11,000,000';
    $Statement->detailList[0]->spare1 = '1000000';
    $Statement->detailList[0]->spare2 = '1000000';
    $Statement->detailList[0]->spare3 = 'spare3';
    $Statement->detailList[0]->spare4 = 'spare4';
    $Statement->detailList[0]->spare5 = 'spare5';

    $Statement->detailList[1] = new StatementDetail();
    $Statement->detailList[1]->serialNum = '2';					//품목 일련번호 순차기재
    $Statement->detailList[1]->purchaseDT = '20190101';			//거래일자 yyyyMMdd
    $Statement->detailList[1]->itemName = '품명';
    $Statement->detailList[1]->spec = '규격';
    $Statement->detailList[1]->unit = '단위';
    $Statement->detailList[1]->qty = '1';
    $Statement->detailList[1]->unitCost = '100000';
    $Statement->detailList[1]->supplyCost = '100000';
    $Statement->detailList[1]->tax = '10000';
    $Statement->detailList[1]->remark = '비고';
    $Statement->detailList[1]->spare1 = 'spare1';
    $Statement->detailList[1]->spare2 = 'spare2';
    $Statement->detailList[1]->spare3 = 'spare3';
    $Statement->detailList[1]->spare4 = 'spare4';
    $Statement->detailList[1]->spare5 = 'spare5';

    /************************************************************
     * 전자명세서 추가속성
     * - 추가속성에 관한 자세한 사항은 "[전자명세서 API 연동매뉴얼] >
     *   5.2. 기본양식 추가속성 테이블"을 참조하시기 바랍니다.
     ************************************************************/
    $Statement->propertyBag = array(
        'Balance' => '50000',
        'Deposit' => '100000',
        'CBalance' => '150000'
    );

    try {
        $result = $this->PopbillStatement->RegistIssue($testCorpNum, $Statement, $memo);
        $code = $result->code;
        $message = $result->message;
    }
    catch(PopbillException | LinkhubException $pe) {
        $code = $pe->getCode();
        $message = $pe->getMessage();
    }

    return '응답코드 : '.$code.PHP_EOL.'응답메시지 : '.$message;

  }

TaskController에 추가한 함수를 호출할 수 있도록 Route에 Controller와 함수명을 매핑합니다.

FilePath : /routes/web.php

<?php

/*
|--------------------------------------------------------------------------
| Web Routes
|--------------------------------------------------------------------------
|
| Here is where you can register web routes for your application. These
| routes are loaded by the RouteServiceProvider within a group which
| contains the "web" middleware group. Now create something great!
|
*/

Route::get('/', function () {
    return view('index');
});

// 전자명세서 Route Mapping
Route::get('/Statement','TaskController@RegistIssue');

② 전자명세서 발행 처리결과를 응답 메시지를 통해 확인합니다.

예) 함수호출 성공처리

예) 함수호출 실패처리

③ 발행된 전자명세서는 팝빌 개발용(test.popbill.com) 사이트에서 확인할 수 있습니다.

[참고] 팝빌 연동 개발을 위한 테스트베드(개발용) 안내 - https://linkhub.tistory.com/91

팝빌에서 제공하는 다양한 API는 동일한 컨셉으로 개발되어 있어, 하나의 서비스를 이용한 경험이 있으면 다른 서비스들도 유사한 방법으로 빠르게 연동이 가능하니 많은 이용 부탁드립니다. 

지금까지 PHP Laravel 개발환경에서 전자명세서 API를 연동하는 방법에 대해 안내드렸습니다. 내용에 대한 추가적인 문의가 있으면 기술지원센터로 편하게 연락주시기 바랍니다.

---

고객사의 편의를 위하여 이메일, 전화 등 다양한 채널을 열어놓고 있으니 언제든지 연락 주시기 바랍니다.

기술지원센터 / T. 1600-9854 / E. code@linkhub.co.kr