Callback 說明

什麼是 Callback¶

當我們透過 SDK 發送 API 至 UOF X 後，可以預期會拿到成功或失敗兩種回覆，大多數的 API 在 UOF X 接收後會即時處理，並回覆處理結果。但在部分的功能中，API 需求並不一定會馬上被 UOF X 處理，而僅是被放入背景的排程中等待執行，此時 API 只會回傳 Trace Id。當 UOF X 背景處理完成後，才會透過 Callback 告知外部系統處理結果，完整流程如下圖:

黃色區塊 是透過 SDK 發送 API 給 UOF X，可以看到雖然收到 Trace ID 回覆，但並不代表此需求已經完成，僅是已收到此需求的意思。

綠色區塊 是當 UOF X 背景處理完成後，會透過 Callback 呼叫 API 回覆處理結果，其結果可能是處理成功或失敗。

注意

發送 API 與 Callback API (即圖中黃色和綠色區塊) 並不一定需要在同一個伺服器，只要符合 Callback API 的規格需求，就可以獨立存在。

一定要callback嗎

Callback 並非強制性，預設是不會 Callback，但不管設定如何皆不會影響請求的處理。

不要callback直接處理不是很好嗎

Callback 機制可以不用等待結果，因此可以避免處理時間過長造成的異常，處理時間過長有很多可能性，例如邏輯複雜、當下系統忙碌中...等，如此可增加系統設計的彈性與效率，也可避免 TimeOut 時容易誤判而重複發送 API，造成重複的資料。

Callback API 規格¶

要實作 Callback 機制，外部系統需要提供 WebApi 站台， UOF X 會依照設定呼叫 API 回傳結果。

Callback api 必須是 POST Method。

請留意不要設定權限驗證 (例: token)、客製 header 檢查...等，還有須注意 CORS 的設定。在安全性方面，UOF X 呼叫 Callback API 皆會將 body 加密，只有擁有 金鑰 才能解開。

將加密的 API Body 解密¶

Callback API Body 會以加密的形式回傳，請使用 SDK 函式 UofxService.DecodeCallBack<T> 來解密取得正確的 Model:

//解密 api request model
var callbackModel = UofxService.DecodeCallBack<T>(requestBody);

T是泛型型別

請參考此連結了解何謂泛型型別，實作時該放入何種類別 (class) ，會在各實作章節說明。

解密的會得到的物件 Model 如下:

public class CallBackModel
{
    //追蹤代號，對應呼叫 API 時拿到的 traceid
    public string TraceId { get; set; }
    //起單結果: Success、Failure
    public CallbackType Type { get; set; }
    //成功的資訊
    public T UofxData { get; set; }
    //客製資訊
    public string CustomData { get; set; }
    //失敗的訊息
    public string ErrorMsg { get; set; }
}

可以透過 Type 屬性來確定 Callback 回覆的處理結果是成功或失敗。當失敗時，ErrorMsg 會存放錯誤訊息；當成功時，UofxData 會存放相關的資訊 (依照不同功能而有不同的類別)。

客製資訊 CustomData 做什麼?¶

CustomData 是允許客製的資訊，會在 SDK 發送 API 請求時提供，並在 Callback 時回傳，這期間 CustomData 內容並不會被加工，或影響處理結果。CustomData 是字串型別，如果希望存放物件，可以將物件轉成 json 字串存入。

應用實例1: 外部系統有兩個以上的程式透過 SDK 發送 API，可以在 CustomData 放入不同的 ID，取得 Callback 回覆時即可透過 CustomData 得知是哪個程式發送的。

應用實例2: 外部系統希望在透過 SDK 發送 API 時，紀錄當下的一些參數在 CustomData，當收到 Callback 回覆時即可透過 CustomData 取得當時的參數設定，進行後續的處理。

支援 Callback 的功能¶

在 SDK 提供的功能中，並非全部都支援 Callback，目前支援 Callback 機制的功能有:

外部起單