iDempiere REST API 完全攻略：認證、CRUD、DocAction

iDempiere REST API 讓你可以用 HTTP 方式整合外部系統，執行 CRUD 操作與觸發 DocAction。本文涵蓋認證設定、常用操作範例，以及 Python 完整程式碼。

一、REST API 簡介

REST API 不是 iDempiere 核心內建功能，而是由社群維護的外掛：

• GitHub: bxservice/idempiere-rest
• 文件: idempiere-rest-docs

二、認證方式

方式一：透過 API 取得 Token（會過期）

POST /api/v1/auth/tokens
Content-Type: application/json

{
    "userName": "admin",
    "password": "admin123",
    "parameters": {
        "clientId": 1000000,
        "roleId": 1000000,
        "organizationId": 0,
        "warehouseId": 1000000,
        "language": "zh_TW"
    }
}

回應會包含 JWT Token，有效期預設 1 小時：

{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": 3600
}

方式二：透過 UI 產生 Token（不過期）

在 iDempiere UI 中：User → API Token 產生永久 Token。

⚠️ 注意：資料庫重刷後此 Token 會失效。

使用 Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

三、CRUD 操作

查詢單筆資料

GET /api/v1/models/C_Order/1000003
GET /api/v1/models/C_Order/1b60e549-346f-4767-9c02-e92e6be5e39d  # 用 UUID

條件查詢

GET /api/v1/models/C_BPartner?$filter=IsCustomer eq 'Y'
GET /api/v1/models/C_ElementValue?$filter=startswith(Value,'4')
GET /api/v1/models/C_Order?$filter=GrandTotal gt 10000&$top=10&$skip=0

建立資料

POST /api/v1/models/C_Order
Content-Type: application/json

{
    "C_DocTypeTarget_ID": 1000016,
    "AD_Org_ID": 1000000,
    "C_BPartner_ID": 1000003,
    "M_PriceList_ID": 1000000,
    "SalesRep_ID": 1000000
}

更新資料

PUT /api/v1/models/C_Order/1000003
Content-Type: application/json

{
    "Description": "Updated via API"
}

四、執行 Process / DocAction

Step 1: 找到 Process 的 slug

GET /api/v1/processes

找到 C_Order Process 的 slug value: c_order-process

Step 2: 執行 Process

POST /api/v1/processes/c_order-process
Content-Type: application/json

{
    "table-id": 259,
    "record-id": 1000003
}

五、Python 完整範例

import requests
import json

host = "http://localhost:8080"

# 1. 取得 Token
def get_token():
    url = f"{host}/api/v1/auth/tokens"
    payload = {
        "userName": "admin",
        "password": "admin123",
        "parameters": {
            "clientId": 1000000,
            "roleId": 1000000,
            "organizationId": 1000000,
            "language": "zh_TW"
        }
    }
    response = requests.post(url, json=payload)
    return response.json()["token"]

# 2. 建立訂單
def create_order(token):
    url = f"{host}/api/v1/models/C_Order"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    payload = {
        "C_DocTypeTarget_ID": 1000016,
        "AD_Org_ID": 1000000,
        "C_BPartner_ID": 1000003,
        "M_PriceList_ID": 1000000
    }
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# 3. 完成訂單
def complete_order(token, order_id):
    url = f"{host}/api/v1/processes/c_order-process"
    headers = {
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    }
    payload = {
        "table-id": 259,
        "record-id": order_id
    }
    response = requests.post(url, headers=headers, json=payload)
    return response.json()

# 執行
token = get_token()
order = create_order(token)
print(f"Created Order ID: {order['id']}")

result = complete_order(token, order['id'])
print(f"Process Result: {result}")

六、常見問題 FAQ

Q1: Token 過期怎麼辦？

重新呼叫 /api/v1/auth/tokens 取得新 Token，或使用 UI 產生的永久 Token。

Q2: 如何處理關聯表查詢？

關聯表的主鍵是複合鍵，必須用 UUID 查詢：

GET /api/v1/models/AD_Window_Access/bf0b18da-0ead-473e-ae2d-b1a86213c3c8

Q3: Checkbox 欄位怎麼設定？

資料庫存 Y/N，但 API 用 true/false。

Q4: 如何指定 Warehouse？

在取得 Token 時的 parameters 中加入 warehouseId。

Q5: 為什麼找不到 Process 的 slug？

先執行 GET /api/v1/processes 取得完整列表，才能知道各 Process 的 slug value。