[Notice] 即將發生的 API / Webhook 異動 (Breaking Changes)
🚧 即將上線 - Upcoming
Aug 1, 2024 Order & Return Order Enhancement relevant API (訂單&退貨單優化) potential breaking change notification
此 breaking change 受「訂單&退貨單優化」項目的店家試用安排影響。當功能陸續開放給相關店家後, 部份API 將新增一些驗證邏輯及限制,App 的 API 請求或受阻擋。詳情會在下方說明。
功能和對應API 異動的上線和生效時間:
店家試用測試第一階段日期 : 2024年6月19日 - 7月31日
試用安排(第一階段)會排除以下店家:
- 已安裝「有使用受影響API」的App
- 因此預期貴司的 app 於此階段不會受 breaking change 影響
預計 Breaking Change 生效日期: 2024年8月1日
建議: App 在2024年7月31日前評估及上線 (如有需要)
通知公告日期 :Jun 11, 2024
影響範圍:
OA cancel order & OA Update Order Status
Update Return Order | Return Order Entity
Update Order Delivery
Update Order Delivery Status
Update Order
異動情況:
當功能陸續開放給相關店家後, 部份API 將新增一些驗證邏輯及限制,APP 的 API 請求或受阻擋。
OA cancel order & OA Update Order Status
- 所有訂單
- 如果送貨狀態為「已發貨」、「已到達」或「已取貨」,訂單不可更新為「取消」。
- 如果訂單狀態為「已完成」,則不允許再進行更新。
對於包含任何舊版本退貨單的訂單,店家無論是否已開通試用相關新功能,這些訂單都可以自由更改。
- 包含任何 “新版本退貨單” 的訂單 :
- 訂單狀態如要更新為「已完成」,所有 “新版本退貨單” 必須處於「已取消」或「已完成」狀態。
如果存在 “新版本退貨單” ,其狀態必須為「已取消」,才能「取消」原訂單並回補庫存。 - Update Order Delivery Status /Update Order Delivery /Update Order
- 一旦訂單標記為「已完成」,則不允許再進行更新
- 訂單狀態如要更新為「已完成」,所有 “新版本退貨單” 必須處於「已取消」或「已完成」狀態。
建議 : 審查並更新Application & API 調用邏輯(如適用):
因應新增限制,建議審視App 邏輯是否需要優化處理如新增錯誤處理邏輯,並建議不晚於7月31日或之前將優化發佈到線上。以下例子僅供參考
OA cancel order & OA Update Order Status
- 確保您的應用程式在限期後可以處理新版退貨單時的新增限制。
- 檢查「送貨狀態」和「訂單狀態」以確認「訂單」是否允許取消或修改。如API 受限,則進行相應錯誤處理和引導
- 對於包含新版本退貨單的訂單,請檢查退貨單狀態。如API 受限,則進行相應錯誤處理和引導。
- Update Order Delivery Status/Update Order Delivery/Update Order
修改您的應用程式邏輯,以符合訂單完成後不允許更新的規則
如貴司希望在此功能店家試用期間針對新、老版本進行不同處理,則需要依籟相關查詢店家的rollout key 來判定,詳情可進一步諮詢我們的partnership 團隊。
English version
This breaking change is influenced by the release and trial schedule of the "Order & Return Order Optimization" feature. As the functionality gradually becomes available to merchants, some APIs will add new validation logic and restrictions, which may block the API requests of your App. Details are explained below.
Timeline for Features and Corresponding API Changes:
Phase 1 of Store Trial Testing: June 19, 2024 - July 31, 2024
- Note: Stores that have installed Apps using affected APIs will be excluded from Phase 1.
- Therefore, it is expected that your App will not be affected by the breaking change during this phase.
Expected Breaking Change Effective Date: August 1, 2024
- Recommendation: Evaluate and arrange optimization to be on production by July 31, 2024, if needed.
Notification Date: June 11, 2024
Scope of impact
- OA cancel order & OA Update Order Status
- Update Return Order | Return Order Entity
- Update Order Delivery
- Update Order Delivery Status
- Update Order
Changes :
As the functionality gradually becomes available to merchants, some APIs will add new validation logic and restrictions, which may block the API requests of your App.
OA cancel order & OA Update Order Status
- All Orders
- If the delivery status is shipped, arrived, or collected, the order cannot be canceled.
- If the order status is completed, no further updates are allowed.
- For orders containing any old version return orders, these orders can be changed freely regardless of whether the store has access to the new trial functionality.
- Orders with Any "New Version Return Orders":
- To update the order status to "completed," all "new version return orders" must be in "canceled" or "completed" status.
- If there are "new version return orders," they must be "canceled" before the original order can be canceled and restocked.
- Update Order Delivery Status / Update Order Delivery / Update Order
Once an order is marked as completed, no further updates are allowed.
Suggestion: Review and Update Application & API Call Logic (if applicable):
Due to the new restrictions, it is recommended to review your App logic to determine if optimizations such as new error handling logic are needed. It is recommended to complete and deploy these optimizations online by July 31, 2024. The following examples are for reference only:
OA cancel order & OA Update Order Status
- Ensure your application can handle the new restrictions for new return orders after the deadline.
- Check the "delivery status" and "order status" to confirm whether the "order" can be canceled or modified. If the API is restricted, implement appropriate error handling and guidance.
- For orders with new version return orders, check the return order status. If the API is restricted, implement appropriate error handling and guidance.
- Update Order Delivery Status/Update Order Delivery/Update Order
- Modify your application logic to comply with the rule that no updates are allowed once an order is completed.
If your company wishes to handle different versions during the store trial period, it will need to rely on querying the merchant's rollout key. For more details, please consult our partnership team.
TBD, 2024 Webhook topics transition - webhook topic 名稱改動
Target Release Date : TBD, 2024 (通知公告日期 : Feb 5, 2024)
改動原因:加強底層架構優化與 customer webhook 標準化的必要改動
影響範圍: (只影響透過 Developer Center 訂閱的 APP webhook ,不影響透過 staff Open API token 訂閱的 webhook)
user/new_member
webhookuser/send_info_reward
webhook
異動情況:
- 預計停止發送 user/new_member webhook 和 user/send_info_reward webhook
建議修改:
user/new_member
webhook --> 請改訂閱customer/new_member
webhook (即日起已開放訂閱)user/send_info_reward
webhook --> 請改訂閱customer/send_info_reward
webhook (即日起已開放訂閱)- 請修改 APP 程式碼裡面解析 topic 的部分,由
user/
改成認customer/
☑️ 已上線 - Released
Sept.18, 2024 訂單資料更新 - 訂單封存 (Order Data Update - Order Archiving)
預計上線時間 Target Release Date
- 預計上線時間 Target Release Date : Sept. 18, 2024
- 通知公告日期 Announce Date : Aug. 19, 2024
影響範圍 Scope of Impact
異動情況 Description of Changes
因應訂單封存機制上線,原有的 Get Order 與 Get Orders 將僅能取得未被封存訂單之資訊,為幫助判別訂單是否已被封存,既有 API 有以下改動: - Get Order: 新增 response code - Get Orders: 新增 response field error | To accommodate the implementation of the order archiving mechanism, the existing Get Order and Get Orders APIs will only retrieve information on orders that have not been archived. To help determine whether an order has been archived, the following changes will be made to the current APIs: - Get Order: New response code added. - Get Orders: New response field error added. |
訂單封存機制:SHOPLINE 將依據訂單狀態封存超過一定期限的訂單資料,因此當使用 Get Order 或 Get Orders 抓取訂單資料,訂單資料標示如下時,則表示該訂單已封存 - Get Order: 收到 410 response (請參閱 Get Order ) - Get Orders: response 中標註已封存訂單 (請參閱 Get Orders ) | Order archiving mechanism: SHOPLINE will archive order data based on order status after a certain period. If the order data was archived, the response of Get Order and Get Orders will be shown the corresponding message: - Get Order: You will receive a HTTP 410 response (please refer to the Get Order documentation). - Get Orders: The response will indicate archived orders (please refer to the Get Orders documentation) |
建議修改 Suggestions for Modification
一般情況下,多數應用只需存取較新的訂單資料,您可以評估您的應用是否需要取得封存訂單資料,若有,才需進行以下改動: - 如有使用到 Get Order 拿取訂單資料,當收到 410 response 時,透過 Get Archived Orders 取得封存訂單資料 - 如有使用到 Get Orders 拿取訂單資料,當回傳欄位中 error 標註訂單已封存時,可透過 Get Archived Orders 取得封存訂單資料 | In most cases, applications only require access to recent order data. Please evaluate whether your application needs access to archived order data. If so, you may need to implement the following changes: - If you use the Get Order endpoint to retrieve order data, and receive a 410 response, please use the Get Archived Orders endpoint to retrieve the archived order data instead. - If you use the Get Orders endpoint to retrieve order data, and the returned field error indicates that the orders were archived, please use the Get Archived Orders endpoint to retrieve the archived order data instead. |
Sept. 11, 2024 領取優惠券 API 與參數異動 (Claim Coupon API & Parameters’ Breaking Change)
預計上線時間 Target Release Date
- 預計上線時間 Target Release Date : Sept. 11, 2024
- 通知公告日期 Announce Date : Sept. 2, 2024
影響範圍 Scope of Impact
異動情況 Description of Changes
- API endpoint 名稱與 request 參數欄位調整。
Adjustments to API endpoint names and request parameter fields.
Old | New | |
---|---|---|
API endpoint | POST <<api_domain>>/v1/user_coupons/singleMultiCoupon | POST <<api_domain>>/v1/user_coupons/{coupon_code}/claim |
Path parameters | N/A | coupon_code |
Body parameters | couponCode userId locale | customer_id : rename from userId locale |
建議修改 Suggestions for Modification
- 確認程式是否有使用上述 API endpoint ,如有使用請依照新的 request 方式做對應修改。
Please check if the above endpoint is being used in your code. If it is, make the necessary updates to align with the new request format.
July 10 & 26, 2024 SHOPLINE Open API & Developer Center 維護通知 (Open API & Developer Center System Maintenance Notification)
July 10 & 26, 2024 SHOPLINE 全站 Open API 維護通知
通知公告日期 : June 3, 2024
影響日期 :
(1) July 10, 2024, 2:00 AM ~ 6:00 AM
(2) July 26, 2024, 2:00 AM ~ 6:00 AM
影響範圍:
所有 SHOPLINE Open API 皆暫停使用,webhook 也不會被觸發。
APP 開發者使用的 Developer Center & Developer OAuth (https://developers.shoplineapp.com/) 也將暫停使用。
預期情況:
維護期間打 SHOPLINE Open API 時都會回應 HTTP status code 503 (Service Unavailable) ,並且 SHOPLINE 不會保留停機期間的 request log 。
維護期間您不會收到 SHOPLINE 發出的 webhook ,因為此段期間店家或顧客皆無法進行任何操作,所以不會觸發事件。
如果您的擴充功能在使用過程中需要使用 Developer OAuth (訪問developers.shoplineapp.com 域名),預期中途會跳轉到維護頁面。
建議注意事項:
留意您的程式是否有 retry 機制,若有,請限制 retry 次數避免無限 retry。
建議您的程式記錄下打 API 不成功的 log ,方便系統恢復後手動補打,造成不便敬請見諒。
SHOPLINE 系統即時狀態請以 https://status.shoplineapp.com/ 此頁面資訊為準 。
July 10 & 26, 2024 Open API System Maintenance Notification
Notification Date: June 3, 2024
Affected Dates:
(1) July 10, 2024, 2:00 AM ~ 6:00 AM
(2) July 26, 2024, 2:00 AM ~ 6:00 AM
Affected Scope:
All SHOPLINE Open API and webhook services will be temporarily suspended.
Developer Center & Developer OAuth for APP developers (https://developers.shoplineapp.com/) will also be temporarily suspended.
Expected Conditions:
During the maintenance, any API calls to SHOPLINE will result in an HTTP status code 503 (Service Unavailable), and SHOPLINE will not retain request logs during the downtime.
During maintenance, you will not receive webhooks from SHOPLINE as neither the staffs nor the customers can perform any actions during this period, hence no events will be triggered.
If your app needs to use Developer OAuth (accessing developers.shoplineapp.com domain), it is expected to redirect to the maintenance page.
Recommendations:
Please check if your program has a retry mechanism. If so, please limit the retry times to avoid unlimited retries.
It is recommended to log unsuccessful API calls, so that you can manually re-execute after the SHOPLINE system is recovered. We apologize for any inconvenience caused.
Please refer to https://status.shoplineapp.com/ for real-time status updates of the SHOPLINE system.
July 31, 2024 停止支援 Open API 舊 domain https://open.shoplineapp.com (Cancel support for old Open API domain)
Announce Date 通知公告日期 : March 17, 2024
【重要公告】
為提升資訊安全,SHOPLINE 團隊將於 2024 年 7 月 31 日 23:59 起取消對 OpenAPI 舊有網址的支援,建議您務必詳閱下方調整說明,並確認是否仍在使用 OpenAPI 舊有網址 (https://open.shoplineapp.com) 。若有的話,請務必更改為 OpenAPI 新網址 (https://open.shopline.io) ,以避免服務中斷,謝謝。
- 調整原因:
- 升級加密通訊協定至 TLS 1.2 ,並停止支援 TLS 1.1 及以下版本
- 提供更完整的 Open API 適用性
- 調整內容:
OpenAPI 網址從 https://open.shoplineapp.com 永久轉移為 https://open.shopline.io 。
提醒:如您已更新 OpenAPI 網址,並通過您團隊的相關測試,即表示所使用的 OpenAPI 已完成加密通訊協定升級。 - 舊有網址 https://open.shoplineapp.com 將於 2024 年 7 月 31 日 23:59 起失效。
(English Version)
【important Notice】
- In order to improve information security, SHOPLINE team will cancel support for the old Open API URL starting from
23:59 on July 31, 2024
. - It is recommended that you confirm whether you are still using the old OpenAPI URL ([https: //open.shoplineapp.com](https: //open.shoplineapp.com)). If so, please be sure to change to the new OpenAPI URL (https://open.shopline.io) to avoid service interruption, thank you.
- Reason for adjustment:
- Upgrade the encrypted communication protocol to TLS 1.2 and stop supporting TLS 1.1 and below versions
- Adjustments:
The OpenAPI URL is permanently moved from https://open.shoplineapp.com to https://open.shopline.io . - Reminder: If you have updated the OpenAPI URL and passed the relevant tests of your team, it means that the OpenAPI you are using has completed the encryption protocol upgrade.
- The old URL https://open.shoplineapp.com will expire at 23:59 on July 31, 2024.
Mar 20, 2024 Category 系列 API 更新 (Category Related API Enhancement) OA-2435
Target Release Date 預計上線時間 : Mar 20, 2024
Announce Date 通知公告日期 : Feb 27, 2024
Scope of Impact 影響範圍:
Description on changed 異動情況:
- Response:
Field | Old | New |
---|---|---|
banner_media.images.original.width | 600.0 | 600 |
children | null | [] |
- Error Response
Field | Old | New |
---|---|---|
updated_after 格式不為 UTC 格式 | { "error": "updated_after is invalid", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["updated_after" must be in ISO 8601 date format]" } |
updated_before 格式不為 UTC 格式 | { "error": "updated_before is invalid", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["updated_before" must be in ISO 8601 date format]" } |
created_by_filter 不是 admin or pos | { "error": "created_by_filter does not have a valid value", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["created_by_filter" must be one of [admin, pos]]" } |
- children:原先沒有子分類的情況,返回的 field 會沒有 children ,改為有 field 值為空 array
-
Old New {
"created_by": "admin"
}{
"children": [],
"created_by": "admin"
}
Create Category & Update Category
- Error Response
Field | Old | New |
---|---|---|
name_translations 全為空{ "category": { "name_translations": {"zh-hant": "", "en": ""} } } | { "error": "name_translations: en or zh-hant can't be blank.", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.name_translations" contains an invalid value]" } |
name_translations 字數超過40字 | { "error": "name_translations[zh-hant]: max length 40 characters", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.name_translations.zh-hant" length must be less than or equal to 40 characters long]" } |
seo_title_translations 字數超過55字 | { "error": "seo_title_translations[en]: max length 55 characters", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.seo_title_translations.en" length must be less than or equal to 55 characters long]" } |
seo_keywords 字數超過160字 | { "error": "seo_keywords: max length 160 characters", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.seo_keywords" length must be less than or equal to 160 characters long]" } |
seo_description_translations 字數超過230字 | { "error": "seo_description_translations[zh-hant]: max length 230 characters", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.seo_description_translations.zh-hant" length must be less than or equal to 230 characters long]" } |
banner_url url格式不正確 | { "error": "{:code=>"MEDIA_UPLOAD_ERROR", :url=>"banner_url", :message=>"Media: Image upload error: url should start with \"http\", with given url: banner_url"}", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.banner_url" must be a valid uri]" } |
priority 格式不正確 | { "error": "category[priority] is invalid", "code": "UnprocessableEntityError" } | { "message": "Unable to process the changes ["category.priority" must be one of [number]]" } |
parent_id parent_id 不能是第三層分類 | { "error": "This category can’t be under a third-level category, please use another parent_id", "code": "UnprocessableEntityError" } | { "message": "Unprocessable Entity", "code": "UNPROCESSABLE_ENTITY", "extras": { "parent_id": [ "This category can’t be under the parent category, please use another parent_id" ] } } |
parent_id parent_id 不能與要更新的 category id 一樣 | { "error": "parent_id: category with given parent_id is exactly the category we are going to update", "code": "UnprocessableEntityError" } | { "message": "Unprocessable Entity", "code": "UNPROCESSABLE_ENTITY", "extras": { "parent_id": [ "category with given parent_id is exactly the category we are going to update" ] } } |
- Error Response - When the category can't be found
-
Old New {
"message": "Not Found"
}{
"message": "Not found.",
"code": "NotFoundError",
"extras": {}
}
Suggestions to Modify 建議修改:
- 確認程式是否有使用上述 error response 做對應處理 ,如果有,請依照新的 response 內容做對應修改。
Feb 15, 2024 Return Order Enhancement - 退貨單更新
Target Release Date : Feb 15, 2024 (通知公告日期 : Jan 16, 2024)
影響範圍:
異動情況:
- Create Return Order
subtotal_items
欄位不可為 empty array - Create Return Order 不再接受傳入
status
欄位 (之後傳入不會有作用) - Create Return Order 不再接受傳入
recipient_address
欄位 (之後傳入不會有作用) - Get Return Orders 的
pagination
.total_count
資料修正成正確數字
建議修改:
- 若您目前有使用 Create Return Order 的 subtotal_items ,請再次確認不會在任何情況下傳入 empty array 。
- 若您目前有使用 Create Return Order 傳入 status 和 recipient_address ,請將這兩個 request parameter 從您的程式中移除,因為 SHOPLINE 系統會自動填相關資料,上線後將不再接受指定傳入這兩個參數。
Dec 13, 2023 Update Product Variation Price - Error Message Breaking Change (OA-2270)
Target Release Date : Dec 13, 2023 (通知公告日期 : Nov 22, 2023)
影響範圍:
- Update Product Variation Price
PUT https://open.shopline.io/v1/products/:product_id/variations/:id/update_price
異動情況:
- product_price_tiers(會員分級價)輸入“null” 會轉為 “0”,而 price(原價)、price_sale(特價)、cost(成本價)、member_price(會員價)、retail_price(實體店價)輸入 “null” 會更新失敗,若要清空請使用"0"。
- Error response 內容格式有些微不同,請參考下方表格:
Old | New |
---|---|
# 不能修改已經設定 ”同主商品價格(same price)“ 的 variation 價格{`"error": "This Product sets the same price, please go to update the main product price","code": "InvalidProductSamePriceError","caused_by": null`} | # 不能修改已經設定 ”同主商品價格(same price)“ 的 variation 價格{"message": "Not found.","code": "NotFoundError","extras": {}} |
# 價格驗證{`"error": "ProductPriceTiers[63313070b0f6aa00372d3232] can not be less than zero or more than 999999999.9","code": "InvalidProductPriceError","caused_by": "product_price_tiers[63313070b0f6aa00372d3232]"`} | # 價格驗證 -> 最大值跟最小值被拆成兩種訊息{`"message": "Unable to process the changes ["product_price_tiers.63313070b0f6aa00372d3232" must be less than or equal to 999999999.9]","message": "Unable to process the changes ["product_price_tiers.63313070b0f6aa00372d3232" must be larger than or equal to 0]"`} |
# 至少必須填寫一個欄位{`"error": "price, price_sale, cost, member_price, retail_price, product_price_tiers are missing, at least one parameter must be provided","code": "UnprocessableEntityError"`} | # 至少必須填寫一個欄位{"message": "Unable to process the changes [price, price_sale, cost, member_price, retail_price, product_price_tiers are missing, at least one parameter must be provided]" } |
# Variation not Found{`"error": "Not found.","code": "NotFoundError","caused_by": null`} | # Variation not Found{`"message": "Unable to find given resources","code": "NOT_FOUND","extras": {}`} |
# Product Not Found{`"error": "Not found.","code": "NotFoundError","caused_by": null`} | # Product Not Found{`"message": "Unable to find given resources","code": "NOT_FOUND"`} |
# 除了 product_price_tiers 之外,所有欄位不能為 null{`"error": "price_sale is empty","code": "UnprocessableEntityError"`} | # 除了 product_price_tiers 之外,所有欄位不能為 null{"message": "Unable to process the changes [\"price_sale\" must be a number]" } |
建議修改:
- 不要將規格品(variation) 的價格更新成 null ,如果要清空就放 0。
- 若有使用 error message 進行後續處理,請留意對應的改動。
Nov 15, 2023 Update Addon Product/Gift Quantity 異動通知 (OA-1929, OA-1927)
Target Release Date : Nov 15, 2023 (通知公告日期 : Oct 25, 2023)
影響範圍:
- Update AddonProduct Quantity
PUT https://open.shopline.io/v1/addon_products/:id/update_quantity - Update Gift Quantity
PUT https://open.shopline.io/v1/gifts/:id/update_quantity
異動情況:
- quantity 原先可接受參數為 null,現在會直接擋掉。
- 找不到對應 addon product/gift → status 維持 404,但內容格式有些微不同。
Old | New |
---|---|
{ "error": "Not found." } | { "message": "Not found.", "code": "NotFoundError", "extras": {} } |
- 若加購品/贈品已經設定成 unlimited_quantity ,這時候無法透過 Open API 將加購品/贈品更新成某數量 → status 維持 403,但內容格式有些微不同。
Old | New |
---|---|
{ "error": "Do not allow to update quantity of the product which contains one or multiple products or has unlimited quantity.", "code": "QuantityUpdateNotAllowedError", "caused_by": null } | { "message": "Do not allow to update quantity of the product which contains one or multiple products or has unlimited quantity.", "code": "QuantityUpdateNotAllowedError", "extras": {} } |
建議修改:
- 不要將加購品/贈品的數量更新成 null 。
- 若有使用 error message 進行後續處理,請留意對應的改動。
[English Version] Nov 15, 2023
📢 Breaking Change - Update Addon Product/Gift Quantity (OA-1929, OA-1927)
Target Release Date : Nov 15, 2023 (Announce date : Oct 25, 2023)
Impact scope:
- Update AddonProduct Quantity
PUT https://open.shopline.io/v1/addon_products/:id/update_quantity - Update Gift Quantity
PUT https://open.shopline.io/v1/gifts/:id/update_quantity
Description on changed:
- For request parameter, the quantity can't be "null".
- If the system can't find corresponding add-on product/gift → status remains 404, but there is some difference on the response content.
Old | New |
---|---|
{ "error": "Not found." } | { "message": "Not found.", "code": "NotFoundError", "extras": {} } |
- If the quantity of add-on product/gift already set to "unlimited_quantity", you can't update their quantity via Open API. → status remains 403, but there is some difference on the response content.
Old | New |
---|---|
{ "error": "Do not allow to update quantity of the product which contains one or multiple products or has unlimited quantity.", "code": "QuantityUpdateNotAllowedError", "caused_by": null } | { "message": "Do not allow to update quantity of the product which contains one or multiple products or has unlimited quantity.", "code": "QuantityUpdateNotAllowedError", "extras": {} } |
Suggestion:
- Please don't update the quantity of add-on product/gift to "null".
- If you are using the error message, please pay attention to the response change.
Oct 26, 2023 Open API Rate Limit 調整成 20次/秒
📢 異動通知 Open API Breaking Change Notification
預計上線日期 : October 26, 2023 (通知公告日期 : October 2, 2023)
影響範圍:
- 整體 Open API 使用。
異動情況:
- 因應提升雙十一系統穩定度與用量升級,預計從原本 1000次/5分鐘 的 Open API 流量限制提升成 20次/秒 ( by IP 計算),調整上線後使用者可呼叫的 Open API 總量將提升,也能避免單一使用者瞬間佔用過高流量。
- 注意 : SHOPLINE 保有未來調降每秒鐘流量限制的權利以確保穩定性。
範例說明:
- 若您現在程式實作方式會在一秒內打超過 20 次 Open API ,有可能會在第 21 次以後呼叫 Open API 時遭遇 429 error ,但再過 1 秒就會重新計算並自動恢復,不需要等待 SHOPLINE 人工恢復。
建議修改:
- 請控制打 SHOPLINE Open API 的速度在 20次/秒以內,如果打 Open API 失敗 ,建議間隔一段時間後進行 retry ,如果 retry 三次都失敗則另外紀錄並人工查詢確認問題原因,謝謝。
- 其他開發建議參考以下 Best Practice Guideline
- If you're making a large number of POST, PATCH, PUT, or DELETE requests for a single user, please wait at least one second between each request.
- Please wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. Do not retry indefinitely.
- It’s important to record the log of request curl and also the API response for future issue diagnoses.
- SHOPLINE reserves the right to change these guidelines and rate limits as needed to ensure availability in the future.
[English Version]
Oct 26, 2023 Open API Rate Limit will change to 20 requests per second
📢 Open API Breaking Change Notification
Target Release Date : October 26, 2023 (Announce date : October 2, 2023)
Impact scope:
- All Open API usage
Description on changed:
- To improve system stability and accommodate increased usage during the Double Eleven event, we will raise the Open API traffic limit from the original “1000 requests every 5 minutes” to “20 requests per second (calculated by IP)”. This adjustment will increase the total Open API calls available to users and prevent any single user from consuming excessive traffic at once.
- Please note that SHOPLINE reserves the right to change rate limits as needed to ensure availability in the future.
Example:
- If your current program will make more than 20 Open API calls within one second, it's possible that you may encounter a 429 error on the 21st call and beyond. However, it will automatically recover after waiting for 1 second so you don’t need to notify SHOPLINE to recover it.
Suggestion:
- Please keep the rate of calling SHOPLINE Open API to within 20 times per second. If calling the Open API results in a failure, we recommend waiting for a period of time before attempting a retry. If retrying three times also fails, please manually investigate to confirm the root cause of the issue.
- Other suggestion please refer to this Best Practice Guideline
- If you're making a large number of POST, PATCH, PUT, or DELETE requests for a single user, please wait at least one second between each request.
- Please wait for an exponentially increasing amount of time between retries, and throw an error after a specific number of retries. Do not retry indefinitely.
- It’s important to record the log of request curl and also the API response for future issue diagnoses.
- SHOPLINE reserves the right to change these guidelines and rate limits as needed to ensure availability in the future.
Sep 27, 2023 Update Quantity by SKU 系列 API 調整成僅回覆數量相關欄位 (OA-1925, OA-1928, OA-1930)
📢 異動通知 Open API Breaking Change Notification
Target Release Date : Sep 27, 2023 --> Oct 18, 2023 (通知公告日期 : Sep 5, 2023)
影響範圍:呼叫下列 Open API 更新數量時
- Update Product, Product Variation Quantity by SKU
( PUT https: //open.shopline.io/v1/products/update_quantity) - Update Gifts Quantity by SKU
( PUT https: //open.shopline.io/v1/gifts/update_quantity) - Update AddonProduct Quantity by SKU
( PUT https: //open.shopline.io/v1/addon_products/update_quantity
異動情況:
- 為最佳化系統效能,使用 Update AddonProduct Quantity by SKU 更新加購品數量時,進版後將不會再回傳與加購品庫存數量無關的資訊。
- 目前使用上述三隻 API 時 request parameters 帶入 sku, quantity, replace 不會驗證型別,也可以帶空值;進版後如果帶入不對的型別/空值就會出現錯誤訊息,驗證較嚴格。
範例說明:
- 異動前 :
Update AddonProduct Quantity by SKU API response 提供以下欄位 (status, title_translations, price, weight, unlimited_quantity, medias, created_at, tax_type, oversea_tax_type) ,當相同 SKU 對應到多個不同加購品時,只會回傳其中一個 mapping 到的加購品資料。 - 異動後 :
Update AddonProduct Quantity by SKU API response 僅回傳加購品庫存數量相關欄位,請參考下方範例。
建議修改:
- 使用 Update AddonProduct Quantity by SKU 時,不要取用 response 中與加購品數量無關的欄位進行其他動作,如果有需要可以另外呼叫 Get AddonProducts API 取得。
- 檢查使用上述三隻 API 時 request parameters 帶入 sku, quantity, replace 是否有按照文件指示的型別帶入,避免意外被擋下,並請留意 error 的異動。
Aug 23, 2023 有帶 previous_id 調整成不 response page (OA-2115)
📢 異動通知 Open API Breaking Change Notification
-
Target Release Date : Aug 24, 2023 (通知公告日期 : Aug 10, 2023)
-
影響範圍:(呼叫下列 Open API 使用 previous_id 拿取分頁資料時 )
- Get Orders / Get Products / Get Customers
- 為最佳化系統效能,若使用 previous_id 拿取分頁資料時,不應該再回傳 total_pages 和 total_count 等另一種 pagination 的相關資訊,因此修正這三隻 API 。
-
異動情況:
- 異動前 :
- 參數帶入 previous_id 時 total_pages 和 total_count 不為 0
- 參數沒帶入 previous_id 時 total_pages 和 total_count 不為 0
- 異動後 :
- 參數帶入 previous_id 時 total_pages 和 total_count 為 0 (第一次呼叫 API 時因為還沒帶入 previous_id ,還是可以拿到 total_count )
- 參數沒帶入 previous_id 時 total_pages 和 total_count 不為 0
- 異動前 :
-
範例說明:
異動前 - 參數帶入 previous_id | 異動後 - 參數帶入 previous_id |
---|---|
"pagination": { "current_page": 1, "per_page": 24, "total_pages": 3, "total_count": 50 } | "pagination": { "current_page": 1, "per_page": 24, "total_pages": 0, "total_count": 0 } |
- 建議修改:
建議第一次呼叫此三隻 API 時如果有需要 total_count 就先把數字存下來,之後開始帶入 previous_id 進行呼叫後就不要再取用 response 中的 "total_pages" 和 "total_count" 參數。
May 24, 2023 顧客生日格式支援年月日 or 年月 or 月日 功能
📢 異動通知 Open API Breaking Change Notification
- Target Release Date : May 24, 2023 (通知公告日期 : May 11, 2023)
- 影響範圍:(當店家開啟 顧客生日格式支援年月日 or 年月 or 月日 功能 )
- Get Customer / Get Customers / Search Customers / Create Customer / Update Customers API
- “user/create” & “user/update” webhook
- Order 系列裡面的 customer_info
- 異動情況:
- 新增
birth_year
、birth_month
、birth_day
三個欄位分別紀錄顧客生日的年、月、日。 - 原本的 birthday 欄位為了兼容現有格式
- 如果 birth_year 為 null, 則 API 預設會 response 1904 年
- 如果 birth_month 為 null, 則 API 預設會 response 1 月
- 如果 birth_day 為 null, 則API 預設會 response 1 日
- 如果 birth_year, birth_month, birth_day 都為 null, 則回傳原本的 birthday 資料。
- 新增
- 範例說明:
如果店家設定顧客只需要填寫月和日,顧客填寫了 3 月 16 日,API 將回覆以下資料:
"birth_year": null, "birth_month": 3, "birth_day": 16, "birthday": 1904-03-16
- 建議修改:
建議此功能上線後將程式修改成拿取 birth_year、birth_month、birth_day 三個新欄位,不管店家是否開啟此功能都會拿到最正確的資料。
Apr 19, 2023 Get Conversations 欄位異動修正
📢 異動通知 Open API Breaking Change Notification
- Target Release Date : Apr 19, 2023 (通知公告日期 : Apr 05, 2023)
- 影響範圍:Get Conversations
- 異動情況:
- receiver_id --> 這個欄位一定是customer ID,但是之前欄位命名 receiver_id 不太正確。我們預計把欄位改成比較正確的 customer_id 。
- last_message.sender_id --> 這邊原本回傳的value一定是customer_id (和上面 receiver_id 一模一樣),但customer_id 不一定是 sender。這次修正這個 value,並且新增 last_message.sender_type 讓使用者分辨此訊息是誰送出的。
- 參考範例:
客戶送訊息給商店:
last_message.sender_type = {User}, last_message.sender_id = customer_id
商店送訊息給客戶:
last_message.sender_type = {Merchant}, last_message.sender_id = merchant_id
Updated about 2 months ago