Day03 - [丰收款] 分析技术文件後，开始做个Nonce开胃菜吧！

接下来就从两大主题丰收款消费支付API与Shioaji证券API之间，挑一个来进行，既然证券开盘时间在上班有点难研究Shioaji，不要把事情搞的太复杂，就顺着感觉走，就先来研究丰收款消费支付API这个题目。

API开发规格书写的方式是把这整套API能做的功能依应用场景来说明，以罗列与解释达成目标的作法为目的，这固然对於想要着手开发的人而言是正确的，不过如果我们就只是纯粹照着作，然後在这里把规格书的东西复诵一遍，好像也没什麽意思，那就直接看文件就好了，毕竟写的还算蛮详细的。

所以撰写技术blog的用意与真谛，就是设法身处和你一样情境与的人的位置，用更贴近新手视角的方式来诠释「同一件事」，除了自己懂，也设法让别人也会同理解。因此除了一起试着动手作之外，也会多出一些废话来解释我的看法与理解。同步好这些观点後，就可以开始了！

我从永丰那收到的东西

首先，报名铁人赛以及填妥要和永丰金索取的资料後，会收到Email，取得一些资料，接下来就是解释一下这些资料是干麻的，以及为什麽会需要这些资料。

Email内容如下

感谢参加2021年之iThome铁人赛，永丰银行以「消费支付API」为参考题目，提供给参赛者的试用资料请点连结下载，档案包括：

API串接手册
Sample code
测试金钥

另提供您开发重要串接资料如下：
(1) 商店代号 (Shop No )：NA0249_001 。
(2) Hash值 (四组)：产出运算值 (Hash ID) 以计算出安全签章及讯息加密用 。
A1 : 86D50DEF3EB7400E
A2 : 01FD27C09E5549E5
B1 : 9E004965F4244953
B2 : 7FB3385F414E4F91

1. 商店资讯，Who am I?

如果不是参加铁人赛，那谁会去和永丰申请消费支付API？ 难不成是消费者因为想要用线上支付所以自己去申请API来串接吗 (应该没有这种苦命事)？

因此，当然是卖方角色。

如果你只是一个独立小店家(例如仅有小量产品，或经销、批货商等)，且不具备网站架设与系统开发能力，多半会选择加入各大电子商城或拍卖平台等，由该平台提供的既有支付服务来达成提供顾客消费支付服务的目标。因此，我们的情境角色，多半不会是这一类型的卖家。但如果真的有小型独立店家想这麽做可以吗，当然可以。

因此，以较合理方式来看，这个卖方的角色会是具备网站系统开发能力，想发展一个电商平台的业者，但希望自己聚焦在购物系统的设计本身，而将金流处理的部份直接和既有的银行服务作串接(就是透过API)，以提供给顾客有多元的消费支付服务，这样的设想会较为合理。

所以如果是这样的角色，我们才会需要和丰永银行申请消费支付API的串接。但实际的情境，正式申请时想必会需要提交更多的相关资料给银行端，经审查之後才会收到实际的商家端资料。

我们继续盘点一下我们的重要资料：

• 商店代号： NA0249_001
• Hash值(四组)：A1、A2、B1、B2

商店代号，代表我们是谁，要和银行後续进行各种API串接服务，总要让银行知道你是哪一个商家要跟他作後续资料交换。
而Hash值呢，毕竟这是高度资安等级的金流交易，因此为了要确保资料交换过程均是有在高度验证性与识别度的运作原则下进行，可以想成是银行特别为你所准备的安全识别码。(还会做一些加工手法)

2. 丰收款API能提供我做什麽

在厘清上述角色与假想後，如果我是一个电商平台，那银行提供的外部金流的服务会发生在我的电商服务流程的哪个阶段？

• 顾客在购物车商品确认後，订单成立，要让顾客进行所选定的付款流程：
  • 提供付款功能 --> 对应到「建立订单交易」
• 若顾客立即付完款後，原本停留的页面可转入下个流程：
  • 提供付款後转回店商页面 --> 对应到「建立订单交易」
• 订单成立和付款是分开来看的流程，使用者不一定要在订单成立就立即付款：
  • 能够依条件供店家查询订单付款状态 --> 对应到「订单交易查询」
• 依明确的付款代码(Token)进行付款状态之查询(有执行付款动作不一定代表成功)：
  • 依付款代码查询状态 --> 对应到「讯息查询服务」
• 若顾客在之後付款完成後，银行端可通知店家 (由店家提供URL)：
  • 付款完成回呼服务 --> 对应到「建立订单交易」
• 若收到付款完成回呼後，再主动与银行端作确认回报：
  • 店家向银行作回呼服务接收确认 --> 对应到「即时讯息通知」

3. 串接连线的准备工作

前面先说明的是交握的情境与流程，接着就是回到程序技术本身了。

以下是丰收款API的几项规定：

1. 在API的连线过程，会需要以TLS 1.2来建立HTTPS的安全机制。
   注：旧版的TLS 1.0、1.1以及SSL 2.0、3.0均因为资安风险，有潜在的弱点会藉此进行网路攻击等行为，业界几乎都设定为关闭停用。
2. 使用UTF-8编码
3. 使用JSON格式

• 其中我们能使用的仅为测试环境，其API网址如下：
  https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/Order

• 而测试环境提供的Nonce取用网址
  https://apisbx.sinopac.com/funBIZ/QPay.WebAPI/api/

什麽是Nonce?

Nonce是一个短时间即失效(60秒)的Token (由API方所提供)，其设计是为了作为API呼叫方的安全验证的一个运算要素，传送後会由API接收方进行比对。而短时间即过期的目的，是为了提高资料不幸被拦截後破解与分析的难度，让「破解」成本过高到破解者不会想要尝试，简单来说是为了防止资讯被拆解後的重送攻击。
基本上，在每次叫用API时的第一个必要的步骤，就是重新取得一次Nonce。

先拿回一个Nonce来看一看吧

打开Postman，将上述Nonce取用网址输入，文件上没特别说明Method的使用，但须使用POST方式进行呼叫。

在使用这个API时，必须於request传入必要内容：告诉API你是哪个店家！
还记得我们的商店代号叫「NA0249_001」吧。

传入格式如上述说明，均使用JSON，所以在Postman中，网址填好後，在Body区选择raw与JSON类型，即可将准备好的request一并传给API。

{
    "ShopNo":"NA0249_001"
}

於是乎，就可以看到热腾腾的Nonce从API回传回来了！

先做到这儿，确认可以运作之後，接下来再来用Python程序叫用吧。