PDF《绿界科技股份有限公司》

绿界科技股份有限公司 Green World FinTech Service Co.

, Ltd. 电子发票 B2C 介接技术文件 V 2.2.5 文件编号:gw_i100 2019-04-18 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. I 目录 1. 电子发票简介.1 2. 前置准备事项.1 3. 开立发票.3 4. 开立折让.20 5. 作废发票.29 6. 作废折让.31 7. 查询发票明细.33 8. 查询折让明细.38 9. 查询作废发票明细.42 10. 查询作废折让明细.44 11. 发送发票通知.46 12. 手机条码验证.48 13. 捐赠码验证.51 附录 1. 检查码机制.53 附录 2. API 回传讯息代码一览表

55 附录 3. URLEncode 转换表

56 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. II Version History: Version Date Content V2.0.0 2016/08/19 Create V2.0.1 2016/10/18 目录格式调整及流程图修正 V2.0.2 2017/01/12 增加「前置准备事项」注意事项说明 V2.0.3 2017/01/26 调整 ItemName(商品名称)参数长度限制 V2.0.4 2017/02/07 文件格式调整 V2.0.5 2017/02/13 调整开立发票 API 的PayType(交易类别)参数,改为必填栏位 V2.0.6 2017/03/13 查询发票 API 增加其他栏位:[PosBarCode]、[QRCode_Left]、[QRCode_Right]. V2.0.7 2017/03/20 文件格式调整 V2.0.8 2017/04/12 相关参数调整说明、检查码机制例修正 V2.0.9 2017/05/11 调整开立折让 API 的NotifyMail、NotifyPhone 参数说明 V2.1.0 2017/05/17 调整 CustomerName(客户名称)参数长度限制 V2.1.1 2017/05/23 调整查询电子发票参数说明 ItemName,ItemWord,ItemRemark,InvoiceRemark 计算检 查码时,需将此参数排除. V2.1.2 2017/06/02 1.调整查询折让明细参数说明 ItemName,ItemWord 计算检查码时 , 需将此参数排除 . 2.优化参数[NotifyURL][CarruerNum]说明内容 V2.1.3 2017/06/29 调整 InvoiceDate 参数中的备注说明 . V2.1.4 2017/07/24 增加开立发票注意事项说明 V2.1.5 2017/07/31 1.调整开立发票 API 参数[Print]、[Donation]、[CarruerType]说明 2.增加开立电子发票设定图示例 V2.1.6 2017/08/29 调整查询发票明细 API 参数[IIS_Award_Flag]、[IIS_Award_Type]说明 V2.1.7 2017/09/27 调整会员载具及合作特店载具,统一名词为绿界科技电子发票载具 V2.1.8 2017/10/06 电子发票作废及电子发票折让作废截止日由每单月

15 日改到每单月

13 日V2.1.9 2017/11/10 调整自然人凭证载具及手机载具编码说明 V2.1.10 2017/11/16 电子发票捐赠码编码格式说明调整 调整开立折让 API 中的参数[CustomerName]、[ItemTaxType]说明 V2.1.11 2017/12/08 电子发票开立栏位捐赠注记代码调整 调整发送发票通知 API 的发票号码参数[InvoiceNo]为必填(原为:内容类型 [InvoiceTag]为I或II 时才必填) V2.1.12 2017/12/26 优化开立发票-延迟开立发票 API 的参数 [NotifyURL]说明. V2.1.13 2018/01/11 调整查询发票明细 API 参数[QRCode_Right]栏位说明 V2.1.14 2018/01/22 增加推荐捐赠码并调整检查码例 V2.1.15 2018/02/21 增加延迟开立发票(预约开立发票) 栏位 NotifyURL 注意事项说明 V2.1.16 2018/02/26 调整注意事项表格格式 增加前置准备注意事项说明,串接只支援 TLS 1.2 以上之加密通讯协定 V2.1.17 2018/03/23 调整开立发票参数[CustomerID]客户代号名称改为客户编号 调整载具编号参数说明,增加绿界科技会员载具编号的编码说明 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. III V2.1.18 2018/05/03 因应财政部修法将 「无实体电子发票」 更名 「云端发票」 , 「爱心码」 更名 「捐赠码」 , 「社福团体」更名「受捐赠机关或团体」 V2.1.19 2018/08/20 调整参数客户名称、买受人名称长度由

30 字元改为

60 字元 修正参数 TaxType、IIS_Tax_Type、ItemTaxType 商品课税别说明内容 V2.2.0 2018/08/23 增加线上折让开立 API V2.2.1 2018/09/10 修正 ClearanceMark 通关方式的参数说明 V2.2.2 2018/11/07 调整中奖种类参数说明及电子发票开立资料设定项目图形文字 V2.2.3 2018/12/22 调整信用卡交易注意事项,发票备注栏卡号末

4 码改为非必填 V2.2.4 2019/03/13 更新文件名称为电子发票 B2C 介接技术文件 调整载具编号[CarruerNum]、商品价格[ItemPrice]、商品合计[ItemAmount] 等栏位说明内容 V2.2.5 2019/04/18 更新载具编号栏位注意事项 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. 绿界科技电子发票介接技术文件

1 /

56 1. 电子发票简介 绿界科技提供合作特店透过介接方式整合电子发票作业功能,且支援

48 小时内将发票上传至财 政部.消费者若持有对应的「载具」 (如自然人凭证) ,便不需列印纸本发票可直接将发票储存於 载具中.同时也提供发票查询功能,可协助合作特店将其功能整合至网站(以下简称为合作特店 系统) , 让消费者能在线上查询发票 . 合作特店也可透过电子邮件或简讯的方式将发票通知寄出. 2. 前置准备事项 (1) 到「绿界科技厂商管理后台->

系统开发管理->

系统介接设定」设定[允许的 IP],以方便后续 API 介接. (注意事项:基於资讯安全考量,绿界科技会限制介接来源 IP 位址的存取,所以需要填写合作特店系统 Server 的 对外 IP 位址至[允许的 IP]栏位). (2) 测试环境系统介接相关资讯 请使用以下资讯在测试环境介接绿界科技电子发票服务 注意事项: (1) 以下为测试环境的资讯,请勿对正式环境做处理否则无法正常介接. (2) 更换介接正式环境时,请将以下资讯更换成正式环境中合作特店所持有的相关资讯,请参考正式环境金钥取得. 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. 绿界科技电子发票介接技术文件

2 /

56 栏位说明 栏位内容 会员编号(MerchantID)

2000132 厂商管理后台 登入帐号/密码 StageTest/test1234 厂商管理后台 测试环境 https://vendor-stage.ecpay.com.tw 此网站可提供:1.电子发票查询 2. 发票资料维护与管理 介接的 HashKey ejCk326UnaZWKisg 介接的 HashIV q9jcZX8Ib9LM8wYk 注意事项: 接收传送绿界科技 API 通知时,请合作特店系统开发人员确认下面事项,以利正常收到绿界科技发送的各项通知: (1) 请确认合作特店系统的 Server 是否有开通防火墙,以避免回传通知被防火墙阻挡. (2) 呼叫绿界科技 API 连接 port 只提供 https (443 port)连线方式,并请使用合法的 DNS(Domain Name System)进行介 接. (3) 请确认各项交易参数传送时是使用 Http POST 方式传送至绿界科技 API. (4) 请确认合作特店系统的 Server URL 连接 port 为http

80 port 与https

443 port. (5) 请勿将金钥资讯(HashKey、HashIV)存放或显示於前端网页内,如Javascript、html、Css…等,避免金钥被盗取使用 造成损失及交易资料外泄. (6) 回传网址不支援中文网址,网址参数请使用 punycode 编码后的网址,例如中文.tw 改成 xn--fiq228c.tw. (7) 若您要使用电子发票服务,需与绿界科技提出申请方可使用. (8) 为保障消费者权益与网路交易安全,绿界串接服务只支援 TLS 1.2 以上之加密通讯协定. 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. 绿界科技电子发票介接技术文件

3 /

56 3. 开立发票 (1) 一般开立发票(立即开立) ? 使用流程说明: 绿界科技系统收到营业人(卖家)传送开立发票参数后,立即开立电子发票上传财政部,并即时 通知消费者(买家)电子发票已开立.营业人可於网站购物车页面或会员资料页面,提供以下发 票资料设定项目供买受人选择(下图为参考例,营业人可自行设计): (图)一般开立发票情境流程图 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. 绿界科技电子发票介接技术文件

4 /

56 处理角色 流程名称 处理说明 营业人(合作特店) 1.发票开立参数 营业人呼叫开立发票(1)一般开立发票传送发票开立参 数. 绿界科技 2.回传开立结果 接收并解析营业人传送过来的电子发票开立资料.确 立发票开立资料无误后,於绿界科技电子发票系统产 生合作特店的电子发票资料. 绿界科技 3.上传财政部 开立成功后,绿界科技会把开立成功的发票资料上传 财政部电子发票平台. 消费者(买家) 4.发票开立通知 开立发票成功后,绿界科技会通知买家电子发票已开 立的讯息. ? 应用场景: 适用於即时开立发票,绿界科技系统收到合作特店系统传送开立发票参数后,上传开立电子发 票. ? 介接

网址: ? 测试环境:https://einvoice-stage.ecpay.com.tw/Invoice/Issue ? 正式环境:https://einvoice.ecpay.com.tw/Invoice/Issue ? 合作特店系统 Request 参数说明(名称前若有红色星号*为必填栏位): 参数 参数名称 型态 说明 备注 *TimeStamp 时间戳记 Int 绿界科技会利用此参数将当下的时间转为 UnixTimeStamp 来验证此次介接的时间区间. 注意事项: 1. 验证时间区间暂订为

5 分钟内有效 , 若超过 此验证时间则此次订单将无法建立 参考资料:http://www.epochconverter.com/. 2. 合作特店须进行主机 「时间校正」 ,避免主机 产生时差,延伸 API 无法正常运作.

1439451807 *MerchantID 合作特店编 号String(10) 1. 测试环境合作特店编号 2. 正式环境金钥取得

2000132 *RelateNumber 合作特店自 订编号 String(30) 均为唯一值不可重覆使用.

123456789 CustomerID 客户编号 String (20) 该参数有值时,仅接受『英文、数字、下底线』 等字元. CustomerIdentifier 统一编号 String(8)

53538851 绿界科技股份有限公司 Green World FinTech Service Co., Ltd. 绿界科技电子发票介接技术文件

5 /

56 参数 参数名称 型态 说明 备注 CustomerName 客户名称 String(60) 1. 当列印注记为 1(列印)时,则该参数必须有 值. 2. 该参数有值时,仅接受中、英文及数字等字 元. 3. 请将参数值做 UrlEncode , 若使用非.net 程式 语言,请参考 URL Encode 转换表更换字元. 绿界科技股份有 限公司 UrlEncode→ %e7%b6%a0%e7% 95%8c%e7%a7%9 1%e6%8a%80%e8 %82%a1%e4%bb% bd%e6%9c%89%e 9%99%90%e5%85 %ac%e5%8f%b8 CustomerAddr 客户地址 String(100) 1. 当列印注记[Print]为1(列印)时,则该参数必 须有值. 2. 将参数值做 UrlEncode,若使用非.net 程式语 言,请参考 URL Encode 转换表更换字元. 台北市南港区三 重路 19-2 号6楼-2 (D 栋) UrlEncode→ %e8%87%ba%e5% 8c%97%e5%b8%8 2%e5%8d%97%e6 %b8%af%e5%8d% 80%e4%b8%89%e 9%87%8d%e8%b7 %af19-2%e8%99% 9f56%e6%a8%93- 2+(D%e6%a3%9f) CustomerPhone 客户手机号 码String(20) 1. 当客户电子信箱[CustomerEmail]为空字串 时,则该参数必须有值. 2. 当该参数有值时,则格式为数字.

0912345678 CustomerEmail 客户电子信 箱String(80) 1. 当客户手机号码[Custome........