Add Items
Description
掃碼下單後結建立新訂單。
Resource
POST /v1/items
Authorization
採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。
Request Body Parameters
| Name | Type | Description |
|---|---|---|
| id | string | 訂單編號 |
| cart | Cart[] | 購物車中的商品資訊 |
| type | string (enum) |
銷售方式 ALLOWED VALUES:
|
| unique_code | string | 訂單唯一碼 WiXGo 掃碼後結單必帶；每次送出產生新的，重送沿用同一個 (optional) |
| participant_id | integer | 點餐人的參與者編號（加入同桌取得） WiXGo 掃碼後結單必帶 (optional) |
WiXGo 掃碼後結單： - 訂單必須已由 POS 開桌，本 API 不會自動建立訂單。 - 單價以前端傳入的
unit_price為準，且必須已包含加值金額，後端不會再加上加值。 - POS 預結後不可再加點。 - 點餐截止時間由前端控制，後端不檢查。
Request Body Parameters - Cart
| Name | Type | Description |
|---|---|---|
| items | Item[] | 品項資料 |
Request Body Parameters - Item
| Name | Type | Description |
|---|---|---|
| id | string | 編號 |
| title | string | 名稱 |
| quantity | int | 數量 |
| special_instructions | string | 特殊要求 (optional) |
| price | ItemPrice | 售價 |
| selected_modifier_groups | ModifierGroup[] | 可選群組 (optional) |
Request Body Parameters - ItemPrice
| Name | Type | Description |
|---|---|---|
| unit_price | Money | 單價 |
| total_price | Money | 合計售價 |
Request Body Parameters - Money
| Name | Type | Description |
|---|---|---|
| amount | integer | 最小單位金額 |
| currency_code | string | 貨幣代碼 ISO 4217 code |
| formatted_amount | string | 顯示用金額 |
Request Body Parameters - ModifierGroup
| Name | Type | Description |
|---|---|---|
| type | string | 類型 ALLOWED VALUES:
(optional) |
| id | string | 編號 |
| title | string | 名稱 |
| pack_suit_id | string | 系列組合編號 (optional) 當類型為PACK，為必填 |
| selected_items | Item[] | 被選擇的品項 |
| removed_items | Item[] | 原本為預設選取，但被消費者移除的品項 |
| combo_taste | bool | 是否為套餐加值 (optional) |
Request Example
{
"id": "STORE2005010001",
"type": "DINE_IN",
"cart": {
"items": [
{
"id": "P001",
"title": "番茄泡菜炒豆包",
"quantity": 2,
"price": {
"unit_price": {
"amount": 40000,
"currency_code": "TWD",
"formatted_amount": "400"
},
"total_price": {
"amount": 80000,
"currency_code": "TWD",
"formatted_amount": "800"
}
},
"selected_modifier_groups": [
{
"id": "1",
"title": "辣度",
"selected_items": [
{
"id": "1",
"title": "小辣",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null
}
],
"removed_items": null
}
]
},
{
"id": "P002",
"title": "紫蘇籽油腐乳炒飯",
"special_instructions": "不要洋蔥",
"quantity": 1,
"price": {
"unit_price": {
"amount": 20000,
"currency_code": "TWD",
"formatted_amount": "200"
},
"total_price": {
"amount": 20000,
"currency_code": "TWD",
"formatted_amount": "200"
}
},
"selected_modifier_groups": [
{
"id": "2",
"title": "加飯",
"selected_items": [
{
"id": "1",
"title": "白飯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null
}
],
"removed_items": null
},
{
"id": "3",
"title": "加胡椒",
"selected_items": [
{
"id": "1",
"title": "胡椒",
"quantity": 0,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null
}
],
"removed_items": null
}
]
}
]
}
}
Combo Request Example
{
"id" : "B010-202008280996",
"type": "DINE_IN",
"cart" : {
"items" : [
{
"id": "UC10000001",
"title": "A餐-炸雞腿飯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 165,
"currency_code": "TWD",
"formatted_amount": "165"
},
"total_price": {
"amount": 245,
"currency_code": "TWD",
"formatted_amount": "245"
}
},
"selected_modifier_groups": [
{
"title": "主食選擇",
"selected_items": [
{
"id": "UC06000002",
"title": "炸雞腿飯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": [{
"id": "3",
"title": "飯類選擇",
"selected_items": [
{
"id": "6",
"title": "飯多",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
]
},
{
"id": "4",
"title": "切塊選擇",
"selected_items": [
{
"id": "2",
"title": "切小塊",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
]
}
],
"default_quantity": 0
}
]
},
{
"title": "選擇配菜",
"selected_items": [
{
"id": "UC03000004",
"title": "竹筍湯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": [
{
"id": "6",
"title": "湯選擇",
"selected_items": [
{
"id": "1",
"title": "不加蔥",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
]
}
],
"default_quantity": 0
},
{
"id": "UC02300001",
"title": "香滷鴨蛋",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
},
{
"id": "UC04100002",
"title": "香滷油豆腐",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
},
{
"id": "UC05000005",
"title": "蜂蜜香檸茶",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
]
}
]
}
]
}
}
Combo Taste Request Example
{
"id": "B033-202010230014",
"type": "DINE_IN",
"cart": {
"items": [
{
"id": "Pack001",
"quantity": 1,
"price": {
"unit_price": {
"amount": 330,
"currency_code": "TWD",
"formatted_amount": "330"
},
"total_price": {
"amount": 330,
"currency_code": "TWD",
"formatted_amount": "330"
}
},
"selected_modifier_groups": [
{
"combo_taste": false,
"title": "湯品",
"selected_items": [
{
"id": "AA010300001",
"title": "鍋料-壽喜湯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": [
{
"combo_taste": false,
"id": "1",
"title": "辣度",
"selected_items": [
{
"id": "3",
"title": "小辣",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"id": "2",
"title": "外帶煮",
"selected_items": [
{
"id": "2",
"title": "不煮",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"id": "3",
"title": "加醬",
"selected_items": [
{
"id": "2",
"title": "二匙醬",
"quantity": 1,
"price": {
"unit_price": {
"amount": 20,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 20,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
}
],
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"title": "肉品",
"selected_items": [
{
"id": "AA02010013",
"title": "和風嫩肩牛5盎司",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"title": "肉品",
"selected_items": [
{
"id": "AA020103002",
"title": "紐西蘭經典牛舌11盎司",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": true,
"id": "1",
"title": "辣度",
"selected_items": [
{
"id": "3",
"title": "小辣",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": true,
"id": "2",
"title": "外帶煮",
"selected_items": [
{
"id": "2",
"title": "不煮",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"title": "鍋料雜糧",
"selected_items": [
{
"id": "AA050200008",
"title": "外帶白飯",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
},
{
"combo_taste": false,
"title": "飲品",
"selected_items": [
{
"id": "AC050101005",
"title": "10公升橘子汽水",
"quantity": 1,
"price": {
"unit_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
},
"total_price": {
"amount": 0,
"currency_code": "TWD",
"formatted_amount": "0"
}
},
"selected_modifier_groups": null,
"default_quantity": 0
}
],
"removed_items": null
}
],
"default_quantity": 0
}
]
}
}
Response
Status-Code: 204 No Content
Error Response
訂單已結束，QR CODE 已失效
訂單已進入結束狀態（如已取消、已結帳、已作廢、已取餐等），該 QR CODE 不再受理加點，請引導消費者重新取號。
message 內會帶出當前訂單狀態名稱與訂單編號。
{
"code": "1487",
"message": "1487：訂單已結束，此QR CODE已失效，狀態：已取消，單號：35-202608170006"
}
400 Bad Request
訂單已結束並合併至其他訂單
訂單已被合併至另一筆訂單，原訂單的 QR CODE 不再受理加點。
message 內會帶出合併後的訂單編號。
{
"code": "1488",
"message": "1488：訂單已結束，此QA CODE已失效，訂單已合併於：35-202608170001單號"
}
400 Bad Request
訂單唯一碼已存在
unique_code 已被受理過，代表此請求為重複送出，本次不再重複建立項目。
{
"code": "1122",
"message": "此筆訂單唯一碼已存在"
}
400 Bad Request
WiXGo 掃碼後結：訂單不存在或尚未開桌
type 為 POST_PAY，但訂單不存在或不是由 POS 開桌建立的掃碼後結單，不寫入任何資料。
{
"code": "1489",
"message": "1489：訂單不存在或尚未開桌"
}
400 Bad Request
WiXGo 掃碼後結：已預結
POS 已送出預結帳單（促銷與服務費已計算），客人不可再加點，請洽服務人員。
{
"code": "1490",
"message": "1490：已送出結帳，如需加點請洽服務人員"
}
400 Bad Request
WiXGo 掃碼後結：缺少必要參數
缺少 unique_code 或 participant_id，或格式錯誤。
{
"code": "1491",
"message": "1491：欄位 participant_id 錯誤 Field required"
}
400 Bad Request
WiXGo 掃碼後結：點餐人不屬於這張訂單
participant_id 不是這張訂單的參與者（例如併桌後仍帶舊單的參與者編號），請重新加入同桌。
{
"code": "1492",
"message": "1492：點餐人不屬於這張訂單，請重新加入點餐"
}
400 Bad Request
Add Items API Workflow
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
sequenceDiagram
autonumber
participant C as Client
participant O as Omniplatform
C->>O: Call Add Items API
activate O
NOTE OVER O: 中間處理流程
O->>O: Call sync_order_by_add_items()
O->>C: Return Response(204 or other)
deactivate OSync Order By Add Items Function Workflow
%%{init: {'securityLevel': 'loose', 'theme':'base'}}%%
sequenceDiagram
autonumber
participant O as Object
participant SOBAI as sync_order_by_add_items()
O->>SOBAI: Call sync_order_by_add_items()
activate SOBAI
SOBAI->>SOBAI: Call get_external_pos_data()
alt if not external_pos_data.empty:
SOBAI->>SOBAI: Call sync_order_by_external_pos_url()
alt status_code != 204
SOBAI->>SOBAI: Call del_failure_data()
end
SOBAI->>O: Return Response(204 or other)
end
SOBAI->>SOBAI: Call sync_order_by_order_sync_url()
alt status_code != 204
SOBAI->>SOBAI: Call del_failure_data()
end
SOBAI->>O: Return Response(204 or other)