Send Ticket

Description

配發票劵，依 send_data 元素中是否帶入 quantity 分為兩種模式，兩者行為完全不同：

非同步（send_data 元素中不帶 quantity）：收到 request 後立刻回應 204，配發於背景進行，完成後以 WEBHOOK 通知 event ticket.complete。一次最多可配發 1000 筆，用戶端無法從回應得知配發結果。
同步（send_data 元素中帶入 quantity）：票券全數配發完成後才回應，用戶端可直接取得成功與失敗清單。為避免久候，建議單次配發總張數在 20 張以下。

注意：模式判定與配發張數僅依 send_data 元素內的 quantity。將 quantity 放在 request body 最外層不會生效，該請求會以非同步模式處理，且每位會員僅配發 1 張。

Resource

POST /v2/ticket/send

Authorization

採用 OAuth 2.0 Bearer Token，詳細使用流程請參考 Auth Login。

Request Body Parameters

Name	Type	Description
id	string	任務編號，不可重複（若需要銷毀票券時會以此任務編號進行）注意：配發失敗後重送時，請改用新的任務編號
send_data	SendData[]	配送資訊
quantity	int	保留欄位，不影響配發行為此欄位不會被採用，模式判定與配發張數請一律使用 `send_data[].quantity` (optional)

Request Body Parameters - SendData

Name	Type	Description
ticket_no	string	活動票劵編號必須為可轉換成整數的字串（例如 `"12"`），帶入含英文字母或符號的值會導致該筆配發失敗
vip_id_list	List[string]	會員編號列表注意：本欄位不檢核會員是否存在，請由既有會員清單帶入
quantity	int	每位會員配發的票券張數（非總張數）實際配發張數 = `vip_id_list` 筆數 × `quantity` 帶入本欄位即為同步模式 (optional)

Request Example

同步模式（send_data 元素帶 quantity），本例實際配發 2 × 2 + 3 × 1 = 7 張：

{
  "id": "A0001",
  "send_data": [
    {
      "ticket_no": "12",
      "vip_id_list": [
        "APP000000001",
        "APP000000002"
      ],
      "quantity": 2
    },
    {
      "ticket_no": "13",
      "vip_id_list": [
        "APP000000001",
        "APP000000002",
        "APP000000003"
      ],
      "quantity": 1
    }
  ]
}

Request Example - 非同步模式

send_data 元素不帶 quantity，每位會員各配發 1 張，立即回應 204：

{
  "id": "A0002",
  "send_data": [
    {
      "ticket_no": "12",
      "vip_id_list": [
        "APP000000001",
        "APP000000002"
      ]
    }
  ]
}

Response

Status-Code: 204 No Content

同步模式：全部票券配發成功。
非同步模式：請求已受理，配發結果後續以 WEBHOOK event ticket.complete 通知。

兩者皆無 response body。

Status-Code: 400（票券配發未全部完成，僅同步模式會回傳）

send_data 帶入兩筆以上時，先處理完成的會列入 send_successful_data，其餘列入 send_failed_data；僅帶一筆時不會出現部分成功，send_successful_data 為空陣列。

{
  "message": "活動票券不足以配發",
  "send_successful_data": [
    {
      "ticket_no": "13",
      "vip_id_list": [
        "APP000000001",
        "APP000000002",
        "APP000000003"
      ],
      "quantity": 1
    }
  ],
  "send_failed_data": [
    {
      "quantity": 2,
      "ticket_no": "12",
      "vip_id_list": [
        "APP000000001",
        "APP000000002"
      ]
    }
  ]
}

Response Body Parameters

Name	Type	Description
message	string	失敗原因，內容為 Response Error Cases 所列的訊息之一
send_successful_data	SendData[]	配送成功票劵列表
send_failed_data	SendData[]	配送失敗票劵列表

注意：message 為整個請求的失敗原因，並非逐筆 send_data 的原因。多筆同時失敗時，內容為最先發生的錯誤。需進一步追查時請提供 id 與呼叫時間，並建議每次請求帶入 X-Request-ID header。

Response Error Cases

以下任一情形發生在某筆 send_data 上，該筆即列入 send_failed_data，整個請求回應 400。

發生原因	`message` 內容	說明	用戶端可事先避免
`ticket_no` 非純數字	配發票券發生錯誤	活動票劵編號必須可轉換成整數	是
`ticket_no` 為空值	配發票券發生錯誤	未帶入或帶入空字串	是
`vip_id_list` 為空陣列	配發票券發生錯誤	無配發對象	是
查無此活動票劵	配發票券發生錯誤	編號格式正確，但查無對應的活動票劵，或該活動尚無可配發的票券	否
票券數量不足	活動票券不足以配發	該活動可配發的剩餘數量小於本次需求張數（`vip_id_list` 筆數 × `quantity`）	否
未完成票券服務設定	沒有設定票券服務網址或總店	該公司尚未設定票券服務位址或總店資訊	否
票券轉銷售失敗	票券轉銷售失敗，請稍後再試	呼叫票券服務時對方回報錯誤，屬外部服務異常，重試有機會成功	否
配發紀錄寫入失敗	寫入票券歷程失敗	配發紀錄寫入過程發生錯誤	否
票券號碼產生失敗	票券資料寫入失敗	票券號碼產生過程發生錯誤	否

注意：message 僅用於問題追查與顯示，請勿以字串比對作為程式流程的判斷依據；訊息內容可能隨版本調整。

Notes

send_failed_data 代表「該筆未完整處理完成」，不代表該筆完全未配發。 配發過程中若發生錯誤，該筆 send_data 已處理完成的票券不會被回收，但整筆仍會列入 send_failed_data。因此 send_failed_data 中的 quantity 是原始請求值，並非尚未配發的張數。

收到 400 後請勿直接重送 send_failed_data。 由於上述原因，直接重送會對已配發成功的會員造成重複配發。請先確認該活動票劵的實際配發結果後，再針對確實未取得票券的會員以新的 id 重新配發；無法自行確認時，請提供 id 與呼叫時間由後端協助查核。send_successful_data 中的票券則已確定全數配發完成。

vip_id 不檢核會員是否存在。 帶入不存在或格式錯誤的會員編號時 API 仍會回應 204，票券將配發至該編號且不會自動回收。

同一個 ticket_no 可拆成多筆 send_data。 成功與失敗以「筆」為單位判定，同一 ticket_no 出現多筆時各筆獨立計算，不會互相影響。