README

一个包含 Laravel 与台湾电子发票处理的套件。
本套件包含三个部分：
pay2go电子发票(或称ezPay电子发票)的对接。
通过对接，可以利用pay2go进行发票的“开立”、“折让”、“作废”、“查询”，并将结果以数组形式返回。
注：原先还计划开发查询“捐赠码”以及“手机载具条码”的功能，但pay2go端功能尚未完善，因此功能待开发。

财政部电子发票营业人应用API的部分功能对接
可以执行“捐赠码”以及“手机载具条码”的检查，判断该条码是否存在于电子发票整合服务平台。注：此功能需向财政部提出申请

经济部商工行政资料开放平台API的部分功能对接
可以利用统编查询公司名称、商号。注：此功能需向商工行政资料开放平台提出申请

关于处理 Laravel 和台湾电子发票的包。
本包包含三个部分：
pay2go(or ezPay)
通过它，我们可以创建、撤销、作废发票，并在pay2go上查询发票。结果将通过数组返回。

财政部电子发票
用于检查携带和爱心码是否存在。注：此功能需申请

政府通讯与信息系统(GCIS)开放数据 用于通过税号查找公司名称。注：此功能需申请

安装

从composer安装

composer require treerful/pay2go-invoice

复制配置文件(两种方法)

(a) 在 config/app.php 中，

    'providers' => [
        /*
         * Laravel Framework Service Providers...
         */
        Illuminate\Auth\AuthServiceProvider::class,
        Illuminate\Broadcasting\BroadcastServiceProvider::class,
        ...
        ...
        Treerful\Invoice\Pay2goInvoiceServiceProvider::class,

添加 ServiceProvider 之后，发布配置文件。

php artisan vendor:publish

(b) 因为提供者是仅用于发布配置，所以您也可以在不添加提供者的情况下手动复制它。

cp vendor/treerful/pay2go-einvoice/config/pay2goinv.php config/pay2goinv.php
cp vendor/treerful/pay2go-einvoice/config/mof-invoice.php config/mof-invoice.php

请记住，文件名 pay2goinv.php 和 mof-invoice.php 不应更改！

Pay2go 引用、初始化类：

use Treerful\Invoice\Pay2goInvoice\Invoice;

开立发票：

开立发票共有三种模式，分别为B2C、捐赠、B2B。本包使用字段 BuyerType （非智付宝官方提供字段）进行区分，此字段为必填。

若需要开立多品项发票，则 ItemName, 'ItemPrice', 'ItemUnit', 'ItemCount 需为数组形式，且每个 ItemPrice 为含税价，在计算时会使用总额直接计算税额

B2C (BuyerType = 0)

$data = [
 'BuyerType' => '0', // B2C
 'MerchantOrderNo' => <自訂商品編號>,
 'BuyerName' => <買受人姓名>,
 'CarrierType' => <載具類別>, // 0:手機條碼, 1:自然人憑證條碼載具 2:智付寶載具
 'CarrierNum' => <載具編號>,
 'ItemName' => <商品名稱> | [商品1, 商品2],
 'ItemCount' => <商品數量> | [商品1數量, 商品2數量],
 'ItemPrice' => <商品單價> | [商品1單價, 商品2單價],
 'ItemUnit' => <商品單位> | [商品1單位, 商品2單位],
];

捐赠 (BuyerType = 1)

// 捐贈
$data = [
 'BuyerType' => '1',
 'MerchantOrderNo' => <自訂商品編號>,
 'BuyerName' => <買受人姓名>,
 'LoveCode' => <愛心碼>,
 'ItemName' => <商品名稱> | [商品1, 商品2],
 'ItemCount' => <商品數量> | [商品1數量, 商品2數量],
 'ItemPrice' => <商品單價> | [商品1單價, 商品2單價],
 'ItemUnit' => <商品單位> | [商品1單位, 商品2單位],
];

B2B（BuyerType = 2）

// B2B
$data = [
 'BuyerType' => '2', // B2B
 'MerchantOrderNo' => <自訂商品編號>,
 'BuyerName' => <買受人姓名>,
 'BuyerUBN' => <買受人統一編號>,
 'ItemName' => <商品名稱> | [商品1, 商品2],
 'ItemCount' => <商品數量> | [商品1數量, 商品2數量],
 'ItemPrice' => <商品單價> | [商品1單價, 商品2單價],
 'ItemUnit' => <商品單位> | [商品1單位, 商品2單位],
];

调用函数

$invoice = new Invoice();
$result = $invoice->create(data);

[补充]

除了上述字段外，可参考官方API提供其他需要的字段，例如：BuyerAddress(买受人地址), BuyerEmail(买受人信箱), Comment(发票备注)。
商品数量默认为 1。
商品单位若不设置，默认为“个”。

折让发票：

$data = [
    'InvoiceNo' => <發票號碼>,
    'MerchantOrderNo' => <自訂商品編號>,
    'ItemName' => <商品名稱> | [商品1, 商品2],
    'ItemCount' => <商品數量> | [商品1數量, 商品2數量],
    'ItemPrice' => <商品單價> | [商品1單價, 商品2單價],
    'ItemUnit' => <商品單位> | [商品1單位, 商品2單位],
    'BuyerEmail' => <買受人信箱>, // 可不填，若填寫則智付寶將寄信通知買受人。
    'BuyerType' => 2 // 2 for B2B，國稅局規定 B2B, B2C 稅額計算方式不同。
    'MaxTax' => <商品最大折稅額> (!不必須),
];

$invoice = new Invoice();
$result = $invoice->allow($data);

[补充]

商品数量默认为 1。
商品单位若不设置，默认为“个”。
商品税额检查，若为多品项且需要调整时，将直接使用最后一项进行调整

作废发票：

$data = [
    'InvoiceNumber' => <發票號碼>,
    'InvalidReason' => <作廢理由>,
];
$invoice = new Invoice();
$result = $invoice->void($data);

查询发票：

查询发票的返回结果有两种显示方式，一为直接返回数据，二为以Post Form的方式导向智付宝发票页面，可在 config/pay2goinv.php 中设置 DisplayFlag 的值。

// 直接回傳資料
// 'DisplayFlag' => '',

// 導向智付寶發票頁面
// 'DisplayFlag' => '1',

查询发票的查询方式也有两种，一为发票金额＆随机码，二为自定义商品编号与总金额，可在 config/pay2goinv.php 中设置 SearchType 的值。

// 發票金額&隨機碼
// 'SearchType' => '0'
// 商品編號&總金額
// 'SearchType' => '1'

根据上述两种方式：

// When SearchType is 0

$data = [

'InvoiceNumber' => <發票號碼>,
'RandomNum' => <隨機碼>,

];

// When SearchType is 1
$data = [
    'MerchantOrderNo' => <自訂商品編號>,
    'TotalAmt' => <商品總金額>,
];

$invoice = new Invoice();
$result = $invoice->search($data);

备注

上述 $data 可接受 Object 或 Array 两种类型。
除了上述字段外，其他字段请参考智付宝API，并自行在$data中添加参数即可

其他用法

在调用四个函数中的任何一个后，除了原本返回的结果外，也可以使用 getPostData() 获取类中实际发送的数据。
```
// Example: (This will get nothing.)
$invoice = new Invoice();
$result = $invoice->getPostData();
```

// 示例: (Cont. 这将获取您发送给Pay2go的原始数据。) $invoice = new Invoice(); $invoice->create($data); $postData = $invoice->getPostData();


- 當呼叫過四個函式其中一個後，除了原本回傳的結果外，亦可使用 `getRawResult()` 取得API呼叫結果後的原始資料。

// 示例: (这将获取无数据。) $invoice = new Invoice(); $result = $invoice->getRawResult();

// 示例: (这将获取从Pay2go获取的原始数据。) $invoice = new Invoice(); $invoice->create($data); $rawResult = $invoice->getRawResult();


### 財政部電子發票營業人應用 API 引用、初始化類別：

use Treerful\Invoice\MofInvoice\Invoice;


<a id="check-bar-code"></a>

### 查詢手機條碼

$invoice = new Invoice(); $response = $invoice->checkBarCode($barCode);

$response['IsExist'] == 'Y' or 'N' // 'Y' 表示此条码存在于财政婦，'N' 表示此条码查无资料


<a id="check-love-code"></a>

### 查詢捐贈碼

$invoice = new Invoice(); $response = $invoice->checkLoveCode($loveCode);

$response['IsExist'] == 'Y' or 'N' // 'Y' 表示此捐赠码存在于财政婦，'N' 表示此捐赠码查无资料


### 濟部商工行政資料開放平臺 API 引用、初始化類別：

use Treerful\Invoice\GCIS\Invoice;


<a id="get-company-name"></a>

### 查詢公司名稱

$invoice = new Invoice(); $response = $invoice->getCompanyName($companyNum);

// 返回示例: string type of: [{"Business_Accounting_NO":"20828393","Company_Name":"宏碁股份有限公司"}]


<a id="get-business-name"></a>

### 查詢商號名稱

$invoice = new Invoice(); $response = $invoice->getBusinessName($companyNum);

// 返回示例: string type of: [{"Business_Name":"宏碁股份有限公司"}]


## Authors

* **Yifan Wu** - *Initial work* - [Github](https://github.com/yfancc20)
* **Treerful** - [Github](https://github.com/treerful)

## Official Reference
[Pay2go E-Invoice API](https://inv.pay2go.com/Invoice_index/download)
[Pay2go 手機條碼與捐贈碼驗證技術串接手冊](https://inv.ezpay.com.tw/dw_files/info_api/BDV_1_0_0.pdf)
[財政部電子發票營業人應用](https://www.einvoice.nat.gov.tw/home/DownLoad?fileName=1468833776540_0.pdf)
[經濟部商工行政資料開放平臺開發指引](https://data.gcis.nat.gov.tw/od/rule)

treerful / pay2go-invoice

维护者

详细信息