API 文檔 火星樹 雲端系統 - 開發自己的應用,連繫著每一個業務流程

1. 如何開始?


登入

火星樹 雲端系統的API 是使用REST,API是支持Cross-Origin Resource sharing(CORS),可以cURL 或 JavaScript ajax方式訪問,所有API回覆的結果會以JSON 格式作輸出,我們是以OAuth2.0 Client Credentials Grant Flow 進行驗證,才能正常存取系統數據。

API終端如下:

正式API:
https://lemontre.es/api

Sandbox API:
https://sandbox.lemontre.es/api



如要使用火星樹 雲端系統的API,我要到開發者專頁中的我的應用程式新增一個應用程式,輸入應用程式名稱選擇關聯網站,完成新增應用程式後,你可以獲取到該應用程式的 Client IDClient Secret

Sandbox 平台登入資訊如下:

URL: https://sandbox.marstree.ltd
用戶: demo@marstree.ltd
密碼: demo

前往Sandbox

應用程式範例:

應用程式名稱: lemontree
關聯網站: Design文具精品店
Client ID: 5RwTtd
Client Secret: 2aa8ed89-b5c6-5ad7-ae2a-04ebd27e3c55



請把Client IDClient Secret 記錄並放到你的代碼當中,這是應用程式永久的辦別,然後訪問登入驗證的API,而獲取Client Credentials憑證。

登入驗證API:

Endpoint: https://lemontre.es/api/oauth/token
Method: GET
Parameters 描述
client_id
required
從應用程式中獲取的Client ID 值
client_secret
required
從應用程式中獲取的Client Secret 值

API結果:

{
  "status": "success",
  "client_credential": "d404ae8b-4552-54ca-8156-ea9fa6683a1f7fee1c9f-d345-5735-acbe-2a7e4d63ac5b",
  "expired_at": "1518329556"
}
      


Attributes 描述
status
驗證狀態
successerror
client_credential
客戶憑證
Client Credential 是一個72位字元的字串,用以API 的訪問,它會有效期30天。
expired_at
客戶憑證有效期
Client Credential 是一個72位字元的字串,用以API 的訪問,它會有效期30天。

獲取網站資訊

如果成功的獲取到Client Credentials憑證,就可以用它去訪問API 而獲取數據了!

網站API:

Endpoint: https://lemontre.es/api/website/data?X-API-KEY={CLIENT_CREDENTIAL}
Method: GET
Parameters 描述
X-API-KEY
required
Client Credentials憑證

API結果:

{
  id: "1",
  domain: "davidaasm",
  site_name: "Design文具精品店",
  description: "零售高品質主題文具及精品",
  keywords: "零售,文具,精品,Design",
  google_analystic: null,
  enable: "1",
  created_at: "1459945992",
  updated_at: "1459945992",
  s3_folder: "davidaasm",
  template_id: "1",
  paypal_client_id: "",
  paypal_secret: "",
  paypal_test_mode: "-1",
  twocheckout_account_no: "",
  twocheckout_secret_word: "",
  twocheckout_test_mode: "-1",
  is_cart: "-1",
  stripe_secret_key: "",
  stripe_test_mode: "-1",
  receipt_content: null,
  cost_mode: "fifo",
  barcode_standard: null,
  sms_gateway: "AWS",
  ctm_username: null,
  ctm_password: null,
  is_accrual: "0"
}
      


Attributes 描述
id
網站ID
網站ID,是網站在系統唯一編號
site_name
網站名稱
網站名稱 (string)
domain
網站域名
domain (string) 也是網站唯一的識別


2. 銷售管理


銷售單

搜索銷售單:

Endpoint: https://lemontre.es/api/sale_order/search
Method: GET
Parameters 描述
X-API-KEY
required
Client Credentials憑證
search
optional
關鍵字搜索
limit
optional
返回數據數量,預計是30筆數據
offset
optional
返回數據的起始位置,預計是0;透過增加offset值進行翻頁。

API結果:

{
  query: {object},
  offset: integer,
  limit: integer,
  data: [array],
  is_more: true/false
}
      


Attributes 描述
query
查詢的條件
Type: Object 返回訪問API時所採用之查詢的條件
limit
數據數量
Type: integer 返回訪問API時所要求之數據數量
offset
數據的起始位置
Type: integer 返回訪問API時所採用之數據的起始位置
is_more
有否下一頁
Type: boolean 返回此次訪問,有否下一頁
data
銷售單數據
Type: Array 陣列中每一項數據為銷售單的對象(Object), 其Attributes如下:
  • id: 銷售單系統ID
  • website_id: 網站系統ID
  • code: 銷售單編號
  • client_id: 客戶系統ID
  • warehouse_id: 倉庫系統ID (Online Sale 的ID是 -1)
  • user_id: 銷售員/用戶系統ID
  • exchange_rate_id: 銷售單貨幣系統ID
  • currency: 銷售單貨幣
  • rate: 銷售單貨幣匯率
  • subtotal: 小計
  • discount: 折扣,這個是百分比值(%)
  • discount_value: 折價
  • total_amount: 總計
  • enable: 如數值為1,該銷售單是啟用狀態;如數值不為1,則該銷售單已被刪除
  • created_at: 銷售單生成時間
  • updated_at: 銷售單更新時間
  • is_pay: 如數值為1,該銷售單已經結賬;如數值不為1,則該銷售單未完成結賬
  • prepay: 已付賬的金額
  • sale_order_item_list: Type: Array 銷售單貨品陣列, 其對象之Attributes如下:
    • item_id: 貨品系統ID
    • amount: 貨品銷售數量
    • price: 貨品該次銷售單價
    • exchange_rate_id: 貨品該次銷售貨幣系統ID
    • currency: 貨品該次銷售貨幣
    • rate: 貨品該次銷售貨幣匯率
    • enable: 如數值為1,該貨品在此銷售單是啟用狀態;如數值不為1,則該貨品在銷售單中已被刪除


新增銷售單:

Endpoint: https://lemontre.es/api/sale_order/submit2
Method: POST
Parameters 描述
X-API-KEY
required
type: String Client Credentials憑證
website_id
required
type: integer 網站系統ID
client_id
required
type: integer 客戶系統ID,如果是Walk IN客戶,請輸入-1
warehouse_id
required
type: integer 倉庫系統ID,如果是Online Sale,請輸入-1
subtotal
required
type: number 小計
total_amount
required
type: number 總計
extra
required
type: number 當extra值為負數值是,這表明是銷售單有找續出現; 當extra值為正數值,這表明銷售單有應收賬出現
exchange_rate_id
required
type: integer 銷售單貨幣系統ID
currency
required
type: String 銷售單貨幣
rate
required
type: number 銷售單貨幣匯率
list
required
type: Array 銷售單貨品,陣列中每項貨品對象(Object)可以用以下例子輸入
[
  {
    item_id: //type: integer, 貨品系統ID required
    is_stock: //type: 1 or 0, 貨品是否記錄倉存 required
    is_lot: //type: 1 or 0, 貨品是否記錄批次號
    lot_id: //type: integer, 貨品批次號系統ID
    lot_code: //type: string, 貨品批次號
    price: //type: number, 貨品單價 required
    amount: //type: integer, 貨品銷售數量 required
    exchange_rate_id: //type: integer, 貨品銷售貨幣系統ID required
    currency: //type: string, 貨品銷售貨幣 required
    rate: //type: number, 貨品銷售貨幣匯率 required
  },
  {
    item_id: //type: integer, 貨品系統ID required
    is_stock: //type: 1 or 0, 貨品是否記錄倉存 required
    is_lot: //type: 1 or 0, 貨品是否記錄批次號
    lot_id: //type: integer, 貨品批次號系統ID
    lot_code: //type: string, 貨品批次號
    price: //type: number, 貨品單價 required
    amount: //type: integer, 貨品銷售數量 required
    exchange_rate_id: //type: integer, 貨品銷售貨幣系統ID required
    currency: //type: string, 貨品銷售貨幣 required
    rate: //type: number, 貨品銷售貨幣匯率 required
  },
  ...
]

              
discount
optional
type: number 銷售單折扣, 幾多%off
discount_value
optional
type: number 銷售單折價, 正數為減幾多錢,負數為加幾多錢
memo
optional
type: longtext 備註
user_id
optional
type: integer 銷售員/用戶系統ID
is_delivered
optional
type: integer 如果銷售單客戶已取貨,請輸入1,系統會自動扣除倉存數量
payment
optional
type: Array 銷售單結賬,支持不同類型的結賬方式,以下是輸入例子
  [
    {
      payment_type: //type enum(cash|credit_card|cheque|alipay|unionpay) required
      amount: //type number, 付款金額 required
      exchange_rate_id: //type integer, 付款貨幣系統ID required
      currency: //type string, 付款貨幣 required
      rate: //type number, 付款貨幣匯率  required
    },
    {
      payment_type: //type enum(cash|credit_card|cheque|alipay|unionpay) required
      amount: //type number, 付款金額 required
      exchange_rate_id: //type integer, 付款貨幣系統ID required
      currency: //type string, 付款貨幣 required
      rate: //type number, 付款貨幣匯率  required
    },
    ...
  ]

銷售單 確認送貨:

Endpoint: https://lemontre.es/api/sale_order/deliver2
Method: POST
Parameters 描述
X-API-KEY
required
type: String Client Credentials憑證
website_id
required
type: integer 網站系統ID
sale_order_id
required
type: integer 銷售單系統ID
client_id
optional
type: integer 客戶系統ID,如果是Walk IN客戶,請輸入-1
is_delivered
required
type: integer 1 為銷售單已確認送貨
user_id
optional
type: integer 銷售員/用戶系統ID

刪除銷售單:

Endpoint: https://lemontre.es/api/sale_order/delete_submit2
Method: PUT
Parameters 描述
X-API-KEY
required
type: String Client Credentials憑證
id
required
type: integer 銷售單ID
user_id
optional
type: integer 銷售員/用戶系統ID

貨幣

搜索貨幣:

Endpoint: https://lemontre.es/api/exchange_rate/search
Method: GET
Parameters 描述
X-API-KEY
required
Client Credentials憑證
search
optional
關鍵字搜索
limit
optional
返回數據數量,預計是30筆數據
offset
optional
返回數據的起始位置,預計是0;透過增加offset值進行翻頁。
id
optional
貨幣系統ID
currency
optional
貨幣代號
rate
optional
匯率

API結果:

{
  query: {object},
  offset: integer,
  limit: integer,
  data: [array],
  is_more: true/false
}
      


Attributes 描述
query
查詢的條件
Type: Object 返回訪問API時所採用之查詢的條件
limit
數據數量
Type: integer 返回訪問API時所要求之數據數量
offset
數據的起始位置
Type: integer 返回訪問API時所採用之數據的起始位置
is_more
有否下一頁
Type: boolean 返回此次訪問,有否下一頁
data
貨幣數據
Type: Array 陣列中每一項數據為貨幣的對象(Object), 其Attributes如下:
  • id: 貨幣系統ID
  • website_id: 網站系統ID
  • code: 貨幣代號
  • rate: 貨幣匯率
  • enable: 如數值為1,該貨幣是啟用狀態;如數值不為1,則該貨幣已被刪除
  • created_at: 貨幣生成時間
  • updated_at: 貨幣更新時間




3. 倉庫管理


貨品

搜索貨品:

Endpoint: https://lemontre.es/api/stock/search
Method: GET
Parameters 描述
X-API-KEY
required
Client Credentials憑證
search
optional
關鍵字搜索
limit
optional
返回數據數量,預計是30筆數據
offset
optional
返回數據的起始位置,預計是0;透過增加offset值進行翻頁。
show_zero
optional
如果是空值或非1 的值, 結果只會顯示有庫存; 如果是1,返回結果會有0庫存的貨品
show_disabled
optional
如果是空值或非1 的值, 結果只會顯示啟用的貨品; 如果是1,返回結果會有停用的貨品
id
optional
貨品系統ID
code
optional
貨品編號
pos_code
optional
貨品Barcode
item_category_id
optional
貨品分類編號

API結果:

{
  query: {object},
  offset: integer,
  limit: integer,
  data: [array],
  is_more: true/false
}
      


Attributes 描述
query
查詢的條件
Type: Object 返回訪問API時所採用之查詢的條件
limit
數據數量
Type: integer 返回訪問API時所要求之數據數量
offset
數據的起始位置
Type: integer 返回訪問API時所採用之數據的起始位置
is_more
有否下一頁
Type: boolean 返回此次訪問,有否下一頁
data
貨品數據
Type: Array 陣列中每一項數據為貨品的對象(Object), 其Attributes如下:
  • id: 貨品系統ID
  • website_id: 網站系統ID
  • supplier_id: 供應商系統ID
  • code: 貨品編號
  • item_category_id: 貨品分類系統ID
  • name: 貨品名稱
  • pos_code: 貨品Barcode
  • weight: 貨品重量(kg)
  • price: 貨品單價
  • unit: 貨品單位系統ID
  • item_type_id: 貨品類型系統ID
  • memo: 貨品備註
  • is_pos: 1是在POS顯示, 非1則不在POS顯示
  • is_stock: 1為 貨品記錄倉存, 非1貨品記錄倉存
  • enable: 1為 貨品在啟用, 非1則貨品停用
  • warehouse_amount_amount: 貨品總庫存


倉庫

搜索倉庫:

Endpoint: https://lemontre.es/api/warehouse/search
Method: GET
Parameters 描述
X-API-KEY
required
Client Credentials憑證
search
optional
關鍵字搜索
limit
optional
返回數據數量,預計是30筆數據
offset
optional
返回數據的起始位置,預計是0;透過增加offset值進行翻頁。
id
optional
倉庫系統ID
code
optional
倉庫編號
name
optional
倉庫名稱

API結果:

{
  query: {object},
  offset: integer,
  limit: integer,
  data: [array],
  is_more: true/false
}
      


Attributes 描述
query
查詢的條件
Type: Object 返回訪問API時所採用之查詢的條件
limit
數據數量
Type: integer 返回訪問API時所要求之數據數量
offset
數據的起始位置
Type: integer 返回訪問API時所採用之數據的起始位置
is_more
有否下一頁
Type: boolean 返回此次訪問,有否下一頁
data
倉庫數據
Type: Array 陣列中每一項數據為倉庫的對象(Object), 其Attributes如下:
  • id: 倉庫系統ID
  • website_id: 網站系統ID
  • code: 倉庫編號
  • name: 倉庫名稱
  • enable: 1為 倉庫在啟用, 非1則倉庫停用


新增倉庫:

Endpoint: https://lemontre.es/api/warehouse/data
Method: POST
Parameters 描述
X-API-KEY
required
type: String Client Credentials憑證
website_id
required
type: integer 網站系統ID
code
required
type: integer 倉庫編號
name
required
type: integer 倉庫名稱
enable
required
type: integer 1為 倉庫在啟用, 非1則倉庫停用