API v1 (Alpha)

  • 發布時間：
  • 最後更新：
  • 分類： API
API為企業方案功能，如需使用請聯繫1shop客服。

1shop API v1

1shop API 目前處於 Alpha 階段，這意味著可能正式發布時，會稍微調整API參數或端點。如有任何建議、反饋和問題，請私訊LINE客服或發送Email至hi@1shop.tw。

如何開始

1shop API 是一個 RESTful 接口，並在其所有請求時，返回 JSON 內容格式。請求和響應都只支持 UTF-8 字符編碼。

驗證方式

在所有端點，URL後方帶入以下參數

  1. appid
  2. secret
https://api.1shop.tw/v1/order?appid=xxxxx&secret=xxxxx

速率限制

目前限制是每個appid，每 10 秒 10 個請求，但這不能保證，它可能會隨著服務器負載而變化。如果超出速率限制，您將收到 429 HTTP 響應( JSON 回傳通常為 {“success”:-9999} )。Retry-After響應標頭將回應可以發出另一個請求的間隔秒數。

無超出速率限制，會取得 200 HTTP 響應。

回應方式

每個端點回應JSON具有三部分

  1. success: 0代表執行完成，其餘代表失敗
  2. data: 執行完成時，資料會放置於此
  3. msg: 執行失敗時，顯示錯誤訊息

訂單

取得訂單列表

[GET] https://api.1shop.tw/v1/order
可使用參數
  1. progress_status: 訂單狀態 / string / 必填 / 輸入以下單個值
    全部: all
    等待確認: pending
    確認中: confirming
    已確認: confirmed
    處理中: processing
    已完成: completed
    已取消: cancelled
    暫存: temporary
    其他: other
  2. payment_status: 付款狀態 / string / 必填 / 輸入以下單個值
    全部: all
    等待付款: pending
    待確認付款: need_confirm
    已付款: paid
    貨到付款: cod
    已退款: refunded
  3. logistic_status: 付款狀態 / string / 必填 / 輸入以下單個值
    全部: all
    等待出貨: pending
    備貨中: prepare
    已出貨: send
    配送中: shipped
    送達取貨點: delivered
    已取貨: received
    異常: abnormal
    退貨/換貨中: returning
    延遲出貨: delay
    已退貨: returned
  4. create_date_start: 訂單建立日期開始 / date / 非必填
    例如填入 2022-01-01，會返回2022-01-01 00:00:00 之後的訂單
  5. create_date_end: 訂單建立日期結束 / date / 非必填
    例如填入 2022-01-01，會返回2022-01-01 23:59:59 之前的訂單
  6. page: 頁碼 / number / 必填
    例如填入 1，將顯示第一頁的訂單
回應
{
  "success": 0, //0代表成功，0以外為失敗
  "data": {
    "order": {
      "order_number": "QI2041900127", //訂單號碼
      "order_ip": "59.127.116.43", //建立訂單IP
      "name": "測試", //訂購人
      "gender": "male", //性別 (none:未填寫, male:男, female:女)
      "total_price": 40, //訂單金額
      "payment": "code", //付款方式 (atm:ATM轉帳, cod:貨到付款, credit:信用卡, credit3:信用卡(分3期), credit6:信用卡(分6期), credit12:信用卡(分12期), credit24:信用卡(分24期), regular:定期定額, paypal:PayPal, code:超商代碼, vacc:虛擬帳戶, c2c:超商取貨時付款, linepay:LINE Pay, icash:icash Pay, applepay:Apple Pay, nocard3:無卡分期(分3期), nocard6:無卡分期(分6期), nocard12:無卡分期(分12期), nocard24:無卡分期(分24期), nopay:不需付款)
      "logistic": "home", //運送方式 (home:宅配, home_refrige:宅配(冷藏), home_freeze:宅配(冷凍), mailing:郵寄, uni:7-11超商取貨, uni_freeze:7-11超商取貨(冷凍), fami:全家超商取貨, fami_freeze:全家超商取貨(冷凍), hilife:萊爾富超商取貨, hilife_freeze:萊爾富超商取貨(冷凍), ezship:ezship超商取貨, virtual:不需運送, local_pickup:門市自取, island:宅配(台灣離島), island_refrige:宅配(台灣離島冷藏), island_freeze:宅配(台灣離島冷凍), oversea:宅配(海外), oversea_other:其他(海外))
      "create_date": "2022-04-19 18:47:35", //建立日期 UTC+8
      "progress_status": "pending", //訂單狀態
      "payment_status": "pending", //付款狀態
      "logistic_status": "pending", //運送狀態
      "payment_date": "2022-04-19 18:47:35", //付款日期
      "tag": "fb20210101", //自訂標籤
      "note": "", //顧客備註
      "shop_note": "", //商家備註
      "email": "test@gmail.com", //Email
      "country": "TW", //國家 ISO 3166-1 二字母碼
      "phone": "0900000000", //電話
      "zip_code": "208", //郵遞區號
      "county_and_city": "新北市", //縣市
      "area": "金山區", //區域
      "address": "", //地址
      "address_oversea": "", //海外地址專用，給顧客自行填寫
      "cvs_store_id": "154644", //超商ID
      "cvs_store_name": "7-11益風門市", //超商門市名稱
      "cvs_store_address": "台中市西區精誠路107號", //超商地址
      "regular_time": 1, //定期定額期數
    },
    "page": {
      "total_page": 10, //總頁數，預設一頁50筆
      "correct_page": 1, //目前在第一頁
      "page_order": 50, //本頁比數
      "total_order": 490, //總訂單數
    },
  },
  "msg": "success"
}

取得詳細訂單

[GET] https://api.1shop.tw/v1/order/{order_number}
回應
{
  "success": 0, //0代表成功，0以外為失敗
  "data": {
    "order": {
      "order_number": "QI2041900127", //訂單號碼
      "order_ip": "59.127.116.43", //建立訂單IP
      "name": "測試", //訂購人
      "gender": "male", //性別 (none:未填寫, male:男, female:女)
      "total_price": 40, //訂單金額
      "payment": "code", //付款方式 (atm:ATM轉帳, cod:貨到付款, credit:信用卡, credit3:信用卡(分3期), credit6:信用卡(分6期), credit12:信用卡(分12期), credit24:信用卡(分24期), regular:定期定額, paypal:PayPal, code:超商代碼, vacc:虛擬帳戶, c2c:超商取貨時付款, linepay:LINE Pay, icash:icash Pay, applepay:Apple Pay, nocard3:無卡分期(分3期), nocard6:無卡分期(分6期), nocard12:無卡分期(分12期), nocard24:無卡分期(分24期), nopay:不需付款)
      "logistic": "home", //運送方式 (home:宅配, home_refrige:宅配(冷藏), home_freeze:宅配(冷凍), mailing:郵寄, uni:7-11超商取貨, uni_freeze:7-11超商取貨(冷凍), fami:全家超商取貨, fami_freeze:全家超商取貨(冷凍), hilife:萊爾富超商取貨, hilife_freeze:萊爾富超商取貨(冷凍), ezship:ezship超商取貨, virtual:不需運送, local_pickup:門市自取, island:宅配(台灣離島), island_refrige:宅配(台灣離島冷藏), island_freeze:宅配(台灣離島冷凍), oversea:宅配(海外), oversea_other:其他(海外))
      "create_date": "2022-04-19 18:47:35", //建立日期 UTC+8
      "progress_status": "pending", //訂單狀態
      "payment_status": "pending", //付款狀態
      "logistic_status": "pending", //運送狀態
      "payment_date": "2022-04-19 18:47:35", //付款日期
      "tag": "fb20210101", //自訂標籤
      "page_title": "測試第一個銷售頁", //訂單歸屬的銷售業或官網名稱
      "page_prefix": "AB", //訂單歸屬的銷售業或官網前綴
      "note": "", //顧客備註
      "shop_note": "", //商家備註
      "email": "test@gmail.com", //Email
      "country": "TW", //國家 ISO 3166-1 二字母碼
      "phone": "0900000000", //電話
      "zip_code": "208", //郵遞區號
      "county_and_city": "新北市", //縣市
      "area": "金山區", //區域
      "address": "", //地址
      "address_oversea": "", //海外地址專用，給顧客自行填寫
      "cvs_store_id": "154644", //超商ID
      "cvs_store_name": "7-11益風門市", //超商門市名稱
      "cvs_store_address": "台中市西區精誠路107號", //超商地址
      "payment_third_party": "ECPay", //付款成功的第三方 
      "payment_third_party_no": "1902949", //付款成功第三方單號，例如綠界號碼
      "logistics_third_party": "ECPay", //物流拋單到的第三方 
      "logistics_third_party_no": "1902949", //第三方單號，例如綠界號碼
      "logistics_shipping_no": "E18771111", //超商查詢號碼
      "shop_url": "https:\/\/test.1shop.tw\/", //商店或銷售頁網址
      "order_url": "https:\/\/tinyurl.com\/y8jauy12", //訂單網址
      "regular_time": 1, //定期定額期數
      "custom_fields": [ //自訂欄位
        {
          "label": "身高",
          "value": "180cm"
        }
      ]
    },
    "cart": {
      "sub_total": 100, //購物車小計，包含所有 single 單個產品 bundle 組合 charge 費用
      "logistic_fee": 60, //物流費用 
      "payment_fee": 60, //金流費用
      "refund": 0, //退款金額
      "total_price": 1000, //總金額 
      "products": [{
        "product_type": "single", //single 單個產品 bundle 組合 charge 費用
        "quantity": 1, //數量
        "per_cost": 10, //單個價格
        "line_total": 10, //quantity * per_cost
        "name": "蘋果", //產品名稱
        "sku": "306041", //貨號
        "label": "滿額贈", //產品名稱說明
        "inventory_status": 0, //0現貨 1預購
      }, {
        "product_type": "charge", //single 單個產品 bundle 組合 charge 費用
        "quantity": 1, //數量
        "per_cost": 10, //單個價格
        "line_total": 10, //quantity * per_cost
        "name": "蘋果", //產品名稱
        "label": "", //產品名稱說明
      }, {
        "product_type": "bundle", //single 單個產品 bundle 組合
        "quantity": 1, //數量
        "per_cost": 10, //單個價格
        "line_total": 10, //quantity * per_cost
        "name": "ABC任選優惠", //產品名稱
        "label": "滿額贈", //產品名稱說明
        "bundle" [{
            "name": "蘋果",
            "sku": "306041",
            "quantity": 2,
            "label": "",
            "inventory_status": 0, //0現貨 1預購
          },
          {
            "name": "香蕉",
            "sku": "306042",
            "quantity": 1,
            "label": "",
            "inventory_status": 0, //0現貨 1預購
          }
        ],
      }],
    },
    "receipt": [{
      "third_party": "ECPay", //開立發票的第三方
      "status": 0, //0等待處理 1已開立 2已作廢
      "type": 1, //0個人 1捐贈 2公司
      "carruer_type": 0, //個人時有此值，0會員載具 1手機條碼 2自然人憑證
      "carruer_num": "", //手機條碼或自然人憑證
      "love_code": "2911811", //愛心碼
      "tax_type": 1, //1應稅 2零稅率 3免稅 4混合應稅與免稅
      "email": "",
      "sales_amount": 0, //銷售總額
      "invoice_number": "", //發票號碼
      "invoice_date": "", //發票日期
      "random_number": "", //隨機碼
      "invoice_remark": "", //發票備註
      "create_date": "2022-04-25 19:18:03", //建立時間
      "receipt_title": "", //發票抬頭
      "tax_num": "", //統編
      "address": "", //地址
      "invoice_date": "", //開立日期
      "phone": "09712222222", //電話號碼
    }],
    "shipping_tracking": [{
      "provider": "黑貓宅急便", //物流供應商
      "url": "http:\/\/www.t-cat.com.tw\/Inquire\/Trace.aspx", //追蹤網址
      "tracking_number": "2222", //追蹤號碼
      "shipping_date": "2022-04-25 19:18:00", //出貨日期
      "create_date": "2022-04-25 19:18:16", //建立日期
      "store_arrived_date": "", //抵達超商日期
    }],
  },
  "msg": "success"
}