虾皮串接实作笔记-串接 API 虾皮订单

前言

目标：串接虾皮订单、标籤资讯，目前串接虾皮 OpenAPI 2.0 版本，串接手册
串接步骤：

Create App：建立串接的帐号Authorize Shop：商店授权Access Token：取得串接用需要的 access token串接 API

前面几篇已经取得 access token，接下来就可以来尝试串接虾皮资料了
这次会尝试虾皮订单，在取得订单资料之前，可以先参考一下虾皮的 API Call Flows
看过 API Call Flows 会更了解虾皮资料处理的顺序跟逻辑

---

API Call Flows 的 Order Status Flow

橘色底是订单的状态，每个订单状态产生的原因都有在旁边加以说明
其中几个步骤的内容

1.订单在确认付款后订单状态会由 UNPAID 转成 READY_TO_SHIP
2.卖家或消费者删除订单后订单状态会变成 CANCELED; 消费者可以在订单状态变成 SHIPPED 之前取消订单
4.在卖家安排物流后订单状态会变成 PROCESSED
5.物流单(託运单)被扫瞄后订单状态变成 SHIPPED
6.消费者要求退货后订单状态变成 TO_RETURN

然后正常流程会是经过 1、4、5 这几步骤，其他的话则是不一定

---

取得订单清单 get_order_list

这个 API 可以让你带入需要的参数后取得你想要的订单单号

格式HTTP/JSONURL• 正式区：https://partner.shopeemobile.com/api/v2/order/get_order_list• 测试区：https://partner.test-stable.shopeemobile.com/api/v2/order/get_order_list请求方式GET

ps：

V2 大部分的 API 如果是取资料的话就会用 GET 的方式正式区跟测试区的 api path 其实都一样，有差别的是前面的 base url

公共参数：

参数类型说明signstringpartner_id、api path、timestamp HMAC-SHA256 编码，并用 partner key 当作加密 Key (可参授权商店那一篇)partner_idintCreate App 产生的 partner_id (可参Create App 那一篇)timestampint时间戳，期限 5 minaccess_tokenstring期限 4 小时(可参取得 access token 那一篇)shop_idint商店 ID(可参授权商店那一篇)

业务参数：(因为是 GET，所以要带到 url 的 query)

参数类型说明time_range_fieldstring时间类别：create_time 或 update_time.time_fromint起始时间，起始到结束不能超过 15 天time_toint结束时间，起始到结束不能超过 15 天page_sizeint一次 response 的笔数，最多 100cursorstring超过 1 页的，下一页的数order_statusstring订单状态：UNPAID/READY_TO_SHIP/PROCESSED/SHIPPED/COMPLETED/IN_CANCEL/CANCELLED/INVOICE_PENDINGresponse_optional_fieldsstring回应的栏位，不填的话只会回应主要的栏位，其余的栏位就不会有

以 PHP 为範例

// 取得订单清单function getOrderList($host,$partnerId,$partnerKey,$timestamp,$access_token,$shop_id,$cursor,$page_size,$order_status){$path='/api/v2/order/get_order_list'; $base_string=strval($partnerId.$path.$timestamp.$access_token.$shop_id);$sign=hash_hmac('sha256',$base_string,$partnerKey,false);$time_from=strtotime('2022-05-01 11:00:00');$time_to=strtotime('2022-05-12 23:00:00');$paremeter='&time_range_field=create_time&time_from='.$time_from.'&time_to='.$time_to.'&page_size='.$page_size.'&order_status='.$order_status;$url=$host.$path.'?partner_id='.$partnerId.'&timestamp='.$timestamp.'&sign='.$sign.'&access_token='.$access_token.'&shop_id='.$shop_id.$paremeter;$ch = curl_init();curl_setopt($ch, CURLOPT_URL, $url);curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);$res = curl_exec($ch);return $res;}

串接完后会有清单的 order_sn，这样就可以进一步去打 get_order_detail 来取得订单详细资料

小提醒：如果 response_optional_fields 没有带 order_status 就不会有喔
一开始想说怎么不给完整的资料，但后来串接 get_order_detail 的时候，发现蛮不错的耶，只会给你必要的资讯，需要的资讯再自己取得就好，不需要的就可以不用给，就不用接收一大坨的资料

---

小小心得：

经过前面商店授权、 access token 后就这次串接就相对简单了，另外我觉得很棒的是虾皮有提供 API Call Flows 这我觉得蛮不错的，让开发者可以很清楚知道实际操作跟 api 之间的关联性！

---

参考资料：
API Call Flows
get_order_list