링크허브 공식블로그 :: [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. 전자세금계산서 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 구문으로 선언해야하는 클래스명은 Laravel 예제 코드를 참조)

생성자 __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\PopbillTaxinvoice;
use Linkhub\Popbill\TIENumMgtKeyType;
use Linkhub\Popbill\Taxinvoice;
use Linkhub\Popbill\TaxinvoiceDetail;
use Linkhub\Popbill\TaxinvoiceAddContact;


class TaskController extends Controller
{
  public function __construct() {

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

    // 세금계산서 서비스 클래스 초기화
    $this->PopbillTaxinvoice = new PopbillTaxinvoice(config('popbill.LinkID'), config('popbill.SecretKey'));

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

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

TaskController에 세금계산서 발행 API를 호출하는 함수를 추가합니다.


public function RegistIssue(){

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

    // 팝빌회원 아이디
    $testUserID = 'testkorea';

    // 세금계산서 문서관리번호
    // - 최대 24자리 숫자, 영문, '-', '_' 조합으로 사업자별로 중복되지 않도록 구성
    $invoicerMgtKey = '20190213-001';

    // 지연발행 강제여부
    $forceIssue = false;

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

    // 안내메일 제목, 미기재시 기본제목으로 전송
    $emailSubject = '';

    // 거래명세서 동시작성 여부
    $writeSpecification = false;

    // 거래명세서 동시작성시 명세서 관리번호
    // - 최대 24자리 숫자, 영문, '-', '_' 조합으로 사업자별로 중복되지 않도록 구성
    $dealInvoiceMgtKey = '';

    /************************************************************
     *                        세금계산서 정보
     ************************************************************/
    // 세금계산서 객체 생성
    $Taxinvoice = new Taxinvoice();

    // [필수] 작성일자, 형식(yyyyMMdd) 예)20150101
    $Taxinvoice->writeDate = '20190213';

    // [필수] 발행형태, '정발행', '역발행', '위수탁' 중 기재
    $Taxinvoice->issueType = '정발행';

    // [필수] 과금방향,
    // - '정과금'(공급자 과금), '역과금'(공급받는자 과금) 중 기재, 역과금은 역발행시에만 가능.
    $Taxinvoice->chargeDirection = '정과금';

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

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

    // [필수] 발행시점
    $Taxinvoice->issueTiming = '직접발행';

    /************************************************************
     *                         공급자 정보
     ************************************************************/
    // [필수] 공급자 사업자번호
    $Taxinvoice->invoicerCorpNum = $testCorpNum;

    // 공급자 종사업장 식별번호, 4자리 숫자 문자열
    $Taxinvoice->invoicerTaxRegID = '';

    // [필수] 공급자 상호
    $Taxinvoice->invoicerCorpName = '공급자상호';

    // [필수] 공급자 문서관리번호, 최대 24자리 숫자, 영문, '-', '_' 조합으로 사업자별로 중복되지 않도록 구성
    $Taxinvoice->invoicerMgtKey = $invoicerMgtKey;

    // [필수] 공급자 대표자성명
    $Taxinvoice->invoicerCEOName = '공급자 대표자성명';

    // 공급자 주소
    $Taxinvoice->invoicerAddr = '공급자 주소';

    // 공급자 종목
    $Taxinvoice->invoicerBizClass = '공급자 종목';

    // 공급자 업태
    $Taxinvoice->invoicerBizType = '공급자 업태';

    // 공급자 담당자 성명
    $Taxinvoice->invoicerContactName = '공급자 담당자성명';

    // 공급자 담당자 메일주소
    $Taxinvoice->invoicerEmail = 'tester@test.com';

    // 공급자 담당자 연락처
    $Taxinvoice->invoicerTEL = '070-4304-2991';

    // 공급자 휴대폰 번호
    $Taxinvoice->invoicerHP = '010-111-222';

    // 발행시 알림문자 전송여부 (정발행에서만 사용가능)
    // - 공급받는자 주)담당자 휴대폰번호(invoiceeHP1)로 전송
    // - 전송시 포인트가 차감되며 전송실패하는 경우 포인트 환불처리
    $Taxinvoice->invoicerSMSSendYN = false;

    /************************************************************
     *                      공급받는자 정보
     ************************************************************/

    // [필수] 공급받는자 구분, '사업자', '개인', '외국인' 중 기재
    $Taxinvoice->invoiceeType = '사업자';

    // [필수] 공급받는자 사업자번호
    $Taxinvoice->invoiceeCorpNum = '8888888888';

    // 공급받는자 종사업장 식별번호, 4자리 숫자 문자열
    $Taxinvoice->invoiceeTaxRegID = '';

    // [필수] 공급자 상호
    $Taxinvoice->invoiceeCorpName = '공급받는자 상호';

    // [역발행시 필수] 공급받는자 문서관리번호, 최대 24자리 숫자, 영문, '-', '_' 조합으로 사업자별로 중복되지 않도록 구성
    $Taxinvoice->invoiceeMgtKey = '';

    // [필수] 공급받는자 대표자성명
    $Taxinvoice->invoiceeCEOName = '공급받는자 대표자성명';

    // 공급받는자 주소
    $Taxinvoice->invoiceeAddr = '공급받는자 주소';

    // 공급받는자 업태
    $Taxinvoice->invoiceeBizType = '공급받는자 업태';

    // 공급받는자 종목
    $Taxinvoice->invoiceeBizClass = '공급받는자 종목';

    // 공급받는자 담당자 성명
    $Taxinvoice->invoiceeContactName1 = '공급받는자 담당자성명';

    // 공급받는자 담당자 메일주소
    $Taxinvoice->invoiceeEmail1 = 'test@test.com';

    // 공급받는자 담당자 연락처
    $Taxinvoice->invoiceeTEL1 = '070-111-222';

    // 공급받는자 담당자 휴대폰 번호
    $Taxinvoice->invoiceeHP1 = '010-111-222';

    /************************************************************
     *                       세금계산서 기재정보
     ************************************************************/
    // [필수] 공급가액 합계
    $Taxinvoice->supplyCostTotal = '200000';

    // [필수] 세액 합계
    $Taxinvoice->taxTotal = '20000';

    // [필수] 합계금액, (공급가액 합계 + 세액 합계)
    $Taxinvoice->totalAmount = '220000';

    // 기재상 '일련번호'항목
    $Taxinvoice->serialNum = '123';

    // 기재상 '현금'항목
    $Taxinvoice->cash = '';

    // 기재상 '수표'항목
    $Taxinvoice->chkBill = '';

    // 기재상 '어음'항목
    $Taxinvoice->note = '';

    // 기재상 '외상'항목
    $Taxinvoice->credit = '';

    // 기재상 '비고' 항목
    $Taxinvoice->remark1 = '비고1';
    $Taxinvoice->remark2 = '비고2';
    $Taxinvoice->remark3 = '비고3';

    // 기재상 '권' 항목, 최대값 32767
    // 미기재시 $Taxinvoice->kwon = 'null';
    $Taxinvoice->kwon = '1';

    // 기재상 '호' 항목, 최대값 32767
    // 미기재시 $Taxinvoice->ho = 'null';
    $Taxinvoice->ho = '1';

    // 사업자등록증 이미지파일 첨부여부
    $Taxinvoice->businessLicenseYN = false;

    // 통장사본 이미지파일 첨부여부
    $Taxinvoice->bankBookYN = false;

    /************************************************************
     *                     수정 세금계산서 기재정보
     * - 수정세금계산서 관련 정보는 연동매뉴얼 또는 개발가이드 링크 참조
     * - [참고] 수정세금계산서 작성방법 안내 - http://blog.linkhub.co.kr/650
     ************************************************************/

    // [수정세금계산서 작성시 필수] 수정사유코드, 수정사유에 따라 1~6중 선택기재
    //$Taxinvoice->modifyCode = '';

    // [수정세금계산서 작성시 필수] 원본세금계산서 ItemKey 기재, 문서확인 (GetInfo API)의 응답결과(ItemKey 항목) 확인
    //$Taxinvoice->originalTaxinvoiceKey = '';

    /************************************************************
     *                       상세항목(품목) 정보
     ************************************************************/
    $Taxinvoice->detailList = array();
    $Taxinvoice->detailList[] = new TaxinvoiceDetail();
    $Taxinvoice->detailList[0]->serialNum = 1;			// 일련번호 1~99까지 순차기재,
    $Taxinvoice->detailList[0]->purchaseDT = '20190101';	// 거래일자
    $Taxinvoice->detailList[0]->itemName = '품목명1번';	  	// 품명
    $Taxinvoice->detailList[0]->spec = '';			// 규격
    $Taxinvoice->detailList[0]->qty = '';			// 수량
    $Taxinvoice->detailList[0]->unitCost = '';		        // 단가
    $Taxinvoice->detailList[0]->supplyCost = '100000';		// 공급가액
    $Taxinvoice->detailList[0]->tax = '10000';			// 세액
    $Taxinvoice->detailList[0]->remark = '';		        // 비고

    $Taxinvoice->detailList[] = new TaxinvoiceDetail();
    $Taxinvoice->detailList[1]->serialNum = 2;			// 일련번호 1~99까지 순차기재,
    $Taxinvoice->detailList[1]->purchaseDT = '20190101';	// 거래일자
    $Taxinvoice->detailList[1]->itemName = '품목명2번';	  	// 품명
    $Taxinvoice->detailList[1]->spec = '';			// 규격
    $Taxinvoice->detailList[1]->qty = '';			// 수량
    $Taxinvoice->detailList[1]->unitCost = '';		        // 단가
    $Taxinvoice->detailList[1]->supplyCost = '100000';		// 공급가액
    $Taxinvoice->detailList[1]->tax = '10000';			// 세액
    $Taxinvoice->detailList[1]->remark = '';		        // 비고

    /************************************************************
     *                      추가담당자 정보
     * - 세금계산서 발행안내 메일을 수신받을 공급받는자 담당자가 다수인 경우
     * 추가 담당자 정보를 등록하여 발행안내메일을 다수에게 전송할 수 있습니다. (최대 5명)
     ************************************************************/
    $Taxinvoice->addContactList = array();
    $Taxinvoice->addContactList[] = new TaxinvoiceAddContact();
    $Taxinvoice->addContactList[0]->serialNum = 1;	        // 일련번호 1부터 순차기재
    $Taxinvoice->addContactList[0]->email = 'test@test.com';	// 이메일주소
    $Taxinvoice->addContactList[0]->contactName	= '팝빌담당자';	// 담당자명

    $Taxinvoice->addContactList[] = new TaxinvoiceAddContact();
    $Taxinvoice->addContactList[1]->serialNum = 2;		// 일련번호 1부터 순차기재
    $Taxinvoice->addContactList[1]->email = 'test@test.com';	// 이메일주소
    $Taxinvoice->addContactList[1]->contactName	= '링크허브';	// 담당자명

    try {
        $result = $this->PopbillTaxinvoice->RegistIssue($testCorpNum, $Taxinvoice, $testUserID,
            $writeSpecification, $forceIssue, $memo, $emailSubject, $dealInvoiceMgtKey);
        $code = $result->code;
        $message = $result->message;
    }
    catch(PopbillException | LinkhubException $pe) {
        $code = $pe->getCode();
        $message = $pe->getMessage();
    }

    return $code.' '.$message

  }

※ 전자세금계산서 발행(전자서명)을 위해서는 사전에 공급자의 인증서가 팝빌 개발용(https://test.popbill.com) 사이트에 등록되어 있어야 합니다.

[참고] 전자세금계산서 발행을 위한 공인인증서 등록방법 안내 - https://linkhub.tistory.com/95

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('/Taxinvoice','TaskController@RegistIssue');

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

예) 함수호출 성공처리

예) 함수호출 실패처리

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

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

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

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

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

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

저작자표시 동일조건

'가치를 연결하다 > 튜토리얼' 카테고리의 다른 글

[PHP - Laravel] 팝빌 전자명세서 API 연동 가이드 (0)	2019.02.19
[PHP - Laravel] 팝빌 현금영수증 API 연동 가이드 (0)	2019.02.19
[ASP.NET Core] 팝빌 전자세금계산서 API 연동 가이드 (0)	2018.12.13
[Python - Django] 팝빌 휴폐업조회 API 연동 가이드 (0)	2018.12.06

1. 서버환경 구성

2. 전자세금계산서 SDK Composer 설치 & Config 추가

3. API 구현

'가치를 연결하다 > 튜토리얼' 카테고리의 다른 글

티스토리툴바