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

目錄

1. 如何開始？

登入

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

API終端如下:

正式API:
https://marstree.ltd/api

Sandbox API:
https://sandbox.marstree.ltd/api


如要使用火星樹 雲端系統的API，我要到開發者專頁中的我的應用程式新增一個應用程式，輸入應用程式名稱 和 選擇關聯網站，完成新增應用程式後，你可以獲取到該應用程式的 Client ID 和 Client 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 ID 和 Client Secret 記錄並放到你的代碼當中，這是應用程式永久的辦別，然後訪問登入驗證的API，而獲取Client Credentials憑證。

登入驗證API:

Endpoint: https://marstree.ltd/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
驗證狀態 		success 或 error
client_credential
客戶憑證		 Client Credential 是一個72位字元的字串，用以API 的訪問，它會有效期30天。
expired_at
客戶憑證有效期		 Client Credential 是一個72位字元的字串，用以API 的訪問，它會有效期30天。

獲取網站資訊

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

網站API:

Endpoint: https://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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://marstree.ltd/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則倉庫停用

火星樹雲端系統

MARS Tree 雲端進銷存系統 是為本澳中小企業而設計的進銷存系統，這套系統的特點是易學實用，有別於一般的系統開發商，系統是按客戶的人數和使用量去收費，客戶只需每月或每年支付維護費用，就可以使用合適中小企使用的系統。

訂閱Email

關注我們

聯繫我們

Phone: +853 28509279 / +853 66297530
Email: info@marstree.ltd
2025 © 火星樹資訊科技有限公司     v.