Callback url là gì? Shopee webhook và API

I. Callback URL là gì:

Khi sử dụng Shopee api hoặc các api khác, các api đều yêu cầu bạn điền thông số callback url. Vậy callback url là gì?Hãy theo dõi ví dụ sau:
POST /api.example.com/foo?callbackURL=http://my.server.com/bar
Trong ví dụ trên, chúng ta gửi 1 request đến api.example.com/foo và yêu cầu sau khi hoàn thành request, api này sẽ gửi kết quả đến url: http://my.server.com/bar

Sở dĩ khi gửi request đến api cần callback url vì có thể api sẽ cần thời gian để xử lý request và nếu không có callback url thì sau khi xử lý xong, sender có thể đã không còn connect với api & api sẽ không gửi được kết quả đến cho sender.

Ref: https://stackoverflow.com/questions/23347056/what-is-a-callback-url-in-relation-to-an-api#23347165

Note: công cụ có thể sử dụng làm callback url để test Shopee API: webhook.site

II. Sử dụng Shopee open API như thế nào

Shopee API có 2 loại: test account & live account. Test account dùng để test => tất cả các thông số đều sẽ sử dụng test account (test act buyer, test act shop…) và đối với live account cũng như vậy. 

Sau khi đăng ký developer account và được Shopee phê duyệt, ta cần tạo app để có thể bắt đầu sử dụng hệ thống API & webhook.  

Shopee API có 2 phần: 

a. Webhook với 12 code trả order json về cho callback url (ref: https://open.shopee.com/developer-guide/18)

Sample của order json trả về từ webhook: 

{
  "data": {
    "items": [],
    "ordersn": "2112132KAD867D",
    "status": "READY_TO_SHIP",
    "update_time": 1639390316
  },
  "shop_id": 30011,
  "code": 3,
  "timestamp": 1639390316
}

Sau khi có order id và các thông số cơ bản của đơn hàng từ webhook, chúng ta sử dụng những thông số này để gửi request đến Shopee API để lấy các thông tin chi tiết của đơn hàng.

Để có thể sử dụng webhook, chúng ta cần thực hiện verify Url callback theo yêu cầu của Shopee. Đối với URL callback, chúng ta có thể sử dụng google sheet kết hợp với apps script làm url callback để nhận và xử lý data trả về từ Shopee API. 

Sau khi deploy code trong Google apps script, ta sẽ copy web app url và sử dụng url này trong app đã tạo ở Shopee API. 

+ Chỉnh sửa google script để ghi data từ webhook trả về vào google sheet. 

b. Open API: 

Để sử dụng open api, Shopee yêu cầu authenticate request như sau: 

Các bước tạo token theo yêu cầu: 

1.Tạo signature base string: URL API + | + Resquest body

2. Lấy secret key từ Shopee open api (Shopee cấp cho từng account khi xét duyệt)

3. Cho vào công cụ HMAC-SHA256 generator để tạo token (ex: https://www.devglan.com/online-tools/hmac-sha256-online)

+ tạo key HMAC-SHA265 với Google apps script:

Utilities.computeHmacSha256Signature(message, secret);

ex: GetOrderAPI

https://partner.shopeemobile.com/api/v1/orders/detail|{“ordersn”:”160798865″,”shopid”:61299,”partner_id”:1,”timestamp”:1470198856}

Ref: https://banhang.shopee.vn/edu/article/8497

III. Chi tiết cách sử dụng Open API: 

1. Lấy dữ liệu đơn hàng mới: 

Để lấy dữ liệu đơn hàng mới từ Shopee API, ta cần gửi request đến API theo yêu cầu của shopee và API sẽ trả lại dữ liệu đơn hàng yêu cầu: 

1.a Địa chỉ URL của Shopee API nhận request:

+ URL test open api: https://partner.shopeemobile.com/api/v2/order/get_order_detail

+ URL live api: https://partner.shopeemobile.com/api/v1/orders/detail

1.b. Authorization (token) để xác thực request:

Làm theo hướng dẫn authenticate request ở trên để tạo token theo công thức:

URL API + | +  {“ordersn”:”160798865″,”shopid”:61299,”partner_id”:1,”timestamp”:1470198856}

Cần thay các thông số ordersn, shopid, partner_id, timestamp theo thông số cần test => tạo token qua mã hoá HMAC-SHA256

1.c. Gửi request đến API và kiểm tra json trả về

tool test api online: https://reqbin.com/

Có thể test bằng tool tích hợp của Shopee open platform: 

+ các thông số order_sn_list, shop_id lấy từ response trả về của shopee webhook

+ Chú ý:

     . order_sn_list cần theo đúng định dạng: [“ID đơn hàng”]

. timestamp: unix time => có thể convert sang dạng human readable (https://www.epochconverter.com/)

 

 

1.d Xử lý json 

 

Doc hướng dẫn của Shopee về get order detail (URL API, : https://open.shopee.com/documents?module=4&type=1&id=397&version=1

Ghi chú: Các link shopee API liên quan

Shopee Open platform portal: https://open.shopee.com
API Document: https://open.shopee.com/documents
Developer Guide: https://open.shopee.com/documents?module=63&type=2&id=51
API Call Flow: https://open.shopee.com/documents?module=63&type=2&id=54
Authenticate a request: https://open.shopee.com/documents?module=63&type=2&id=53
Data Definition: https://open.shopee.com/documents?module=63&type=2&id=50