虾皮 Open Platform 与经典程序流程图

不管是在哪开始学习写程序，都一定会看到最经典的流程图:

至今，流程图的正确画法也不是那麽容易被在乎，反正只要看起来能解读成正确的意思就好； 但总的来说，以前的我只知道 if else 条件控制要用菱形，现在大概也只知道菱形的涵义。

既然这麽经典，那我就不多 Survey 这个流程图的细节了，像这样的标准流程图应该可以参考 Wiki，我们直接来看看有趣的部份。

有一大阵子前，我去申请了 Shopee Open Platform 的 API 串接，那真的是个噩梦，虾皮的文件 Definition 有些栏位告诉你是 float 或数值，但是在他没有给定的时候，value 会直接送你一个 "" 空字串 (哈哈，想不到吧)，然後程序就爆炸了 (抱怨结束)；

详情可以看看这个 Golang Open Platform API Wrapper 的描述:
https://github.com/teacat/shopeego

进入本题，虾皮的文件 (V1, V2) 中特别注记了 API Call Flows 的流程，而且把它们画成流程图:

V1: https://open.shopee.com/documents?module=63&type=2&id=54&version=1
V2: https://open.shopee.com/documents?module=87&type=2&id=60&version=2

之所以 Shopee Open Platform 要把它们画成 API，是因为开发者也必须知道店商流程是怎麽跑的，不能乱叫 API，作为范例，提供两个重点的流程图:

这张图告诉你，一个买家买完商品之後，一开始捞到的资料会是 UNPAID 状态，如果他付完款 (含货到付款，等一下之後)，就会进入 READY_TO_SHIP 这个状态，这个时候卖家後台应该就可以取得物流编号去超商寄件，只要被寄出之後，物流公司就会更新虾皮状态，状态变成 SHIPPED。

了解状态流之後，接下来要看订单要如何改变状态，则需要参考第二个流程: Arrange Shipment & Get TrackingNo & Print AirwayBill

这上面大致上告诉你，如果你有一个很酷的应用程序，你可以用 get_shipment_list 或是 get_order_list 拿到订单列表，然後你还需要 call 一个必要的 get_order_detail 这个函数，取得订单详细资料，也许是要呼叫这个，你才能拿到订单是否需要拆开 (split_order) 这个资料栏位。

然後，不管怎样你还需要呼叫 get_shipping_parameter 取得这个人的运送方式，於是，流程图分支出现了 !!!，他居然写 select one，意思是跟开发者说，请你选择一个物流方式，这个应该不是叫你选一种，打天下，你可能会需要一些判断，看资料有没有某些参数，至少我在处理这个选择时，程序是这麽写的:

// 看看 NonIntegrated, Pickup, Dropoff 是不是空的，假设了虾皮给资讯也是三责一给，不会超过 1 个。
if orderShipmentDetail.InfoNeeded.NonIntegrated != nil {
    nonIntegrated = &shopeego.InitRequestNonIntegrated{
        TrackingNo: "卖家自选物流 " + order.ID,
    }
}
if orderShipmentDetail.InfoNeeded.Pickup != nil {
    // TODO: 实作 Pickup (没实作，因为在台湾没有用到)
}
if orderShipmentDetail.InfoNeeded.Dropoff != nil {
    dropoff = &shopeego.InitRequestDropoff{
        SenderRealName: p.SenderRealName,
    }
}

此时，看看 API 文件说了什麽?

从文件上看来，NonIntegrated 是自选物流，比方说 XX 物流、 XX 邮政，而且是卖家自己选的，不会有物流追踪；

Pickup 很玄，大概是登门跟卖家取货，至少之前在台湾我没有遇过任何一个这样的订单，不过 2021 年 09 月虾皮多了一个店到店的物流，也许跟这个有关；

DropOff 是目前处理过的大部分订单都是给这个，这个才是最重要的，甚至里面要放卖家寄件的名字，而且名称不能乱填，否则退货你卖家就无法领，通通拿去烧毁。

总之，他告诉你 Select one 意思就是请你选一个带出直就好，不要三个 value 一起送，如果你这样送:

{
    "order_sn": "F020D20S2F0DS20F",
    "non_integrated": { …略 },
    "pickup": { …略 },
    "dropoff": { …略 },
}

这将是一个 big no no。

请你送出一个就好:

{
    "order_sn": "DS5F4S4DF54DS", 
    "dropoff": { …略 },
}

当你组合好必要的参数之後，就使用 logistics.ship_order 送出，此时你的订单应该会进入产生物流的状态，接着你就要不断 update ，要用 update_shipping_order 去检查这个订单产生好了没，因为有时候物流家的系统会自杀，全台物流大爆炸，卖家无法寄件，这时候你的系统就要等他。

总之如果他产生好了，对开发者来说还有两个选择可以进行 (self-design airway bill?) ，你要自己设计物流单吗?

要的话，只需要呼叫 get_shipping_document_info 自己产生条码，如果不是，你可以按照 No 那排的流程依序呼叫，你就会拿到物流单的影像档，像是全家是给你 Image，7-11 是丢给你网页(现在应该是 pdf)，莱尔富跟 OK 都是 pdf，对於 pdf 的处理要小心就是，如果你用太旧的 pdf engine 处理，你的字体会直接爆炸。

过来人建议: 以调动成本考量，虾皮或超商一天到晚在那边变动，自己产生条码似乎是降低维护成本的方法。

对於流程图的范例，可以看到虾皮用了经典的 【档案】 流程图来描述更多讯息:

对於这个符号的使用情境，似乎会让人有点好奇，为什麽不直接写文字注解框起来就好，而是用档案符号，所以啦，除了菱形是条件 (condition) 之外，其实你要怎麽画，反正可以表达清楚就好。

额外补充

下面是一个初始化订单的范例的程序码 (框架基於 shopeego)，不过这是 for V1 的 api。

// 初始化一个 Shopee 客户端。client:=shopeego.NewClient(&shopeego.ClientOptions{
	Secret: "0c2c7b3bd597fcf49dc985df2e44",
})
// 取得指定商店的资料。shop, _:=client.GetShopInfo(&shopeego.GetShopInfoRequest{
	PartnerID: 1234567,
	ShopID:    1234567,
	Timestamp: int(time.Now().Unix()),
})

// v1 code 建立出货单
_, err = client.Init(&shopeego.InitRequest{
        OrderSN:   orderID,
        PartnerID: p.PartnerID,
        ShopID:    p.ShopID,
        Timestamp: int(time.Now().Unix()),
        Dropoff:       dropoff,  // 如果没有，这个应该要是 nil
        Pickup:        pickup,  // 如果没有，这个应该要是 nil
        NonIntegrated: nonIntegrated, //如果没有，这个应该要是 nil
    })

if err != nil {
        panic("gg")
    }

随题附上可以绘制流程图的工具参考: Visio、Visual Paradigm，也可以使用 Cacoo、Figma 或是用 HackMD 内建的 flowcharts 语法，用 code 来绘制流程图，看起来就很潮。