跳至主要内容

公司行動事件

接收公司行動事件通知，包括：

  • 標識符變更（代碼、CUSIP、ISIN 變更）
  • 股息（現金股息、股票股息）
  • 股票拆分和反向拆分
  • 併購
  • 供股
  • 其他公司行動事件

公司行動事件​

當公司行動公告或更新時觸發此事件。

事件結構​

{
  "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
  "event_type": "INSTRUMENT",
  "position": "CJO1fxACGAAgADAB",
  "timestamp": "2025-03-29T07:02:33.200Z",
  "payload": {
    "event_id": "925299289_1569116747",
    "event_type": "DIVIDEND",
    "event_version": "1768542619139",
    "instrument_id": "925299289",
    "category": "US_STOCK",
    "record_date": "2026-01-14",
    "ex_date": "2026-01-13",
    "payment_date": "2026-01-15",
    "final_pay_date": "2026-01-15",
    "country_code": "US",
    "listing_country_of_code": "US",
    "issuer_country_code": "CA",
    "from": {
      "symbol": "AFRRF",
      "cusip": "00111F102",
      "isin": "CA00111F1027",
      "name": "AFR NUVENTURE RESOURCES INC",
      "exchange": "PSGM"
    },
    "to": [
      {
        "option_number": "2",
        "description": "Cash",
        "default_option_flag": "true",
        "payouts": [
          {
            "type": "DV",
            "pay_type": "CASH",
            "payout_number": 1,
            "adr_fee_rate": "0.003",
            "fraction_share_rule": "NONE",
            "cancellation_fee": "0",
            "issuance_fee": "0",
            "currency": "USD",
            "amount": "0.176885",
            "withholding_tax_rate": "0.011"
          }
        ]
      }
    ],
    "biz_type": "CA_EVENT"
  }
}

響應欄位​

欄位類型描述
idstring唯一事件標識符
positionstring游標用於事件重播；重新推送當前業務類型後續事件。
event_typestring事件類型，固定為 INSTRUMENT
event_versionstring事件版本號，隨更新遞增。數字越大代表越新的版本
timestampstring事件時間戳，ISO 8601 格式
payloadobject事件負載數據

Payload 欄位​

欄位類型描述
eventIdstring唯一公司行動事件標識符
event_typestring公司行動類型（例如 IDENTIFIER_CHANGE、DIVIDEND、SPLIT）
event_versionstring事件版本號，隨更新遞增。數字越大代表越新的版本
instrument_idstring受公司行動影響的標的標識符
categorystring標的類別（例如 US_STOCK）
record_datestring公司行動的登記日期
ex_datestring除息日或除權日
payment_datestring付款日期
final_pay_datestring最終付款日期
country_codestring國家代碼
listing_country_of_codestring上市國家代碼
issuer_country_codestring發行人國家代碼
fromobject原始標的信息
toarray目標付款選項（可能存在多個選項）
biz_typestring業務類型，固定為 CA_EVENT

From 對象欄位​

欄位類型描述
symbolstring原始標的代碼
cusipstring原始 CUSIP 標識符
isinstring原始 ISIN 標識符
namestring原始標的名稱
exchangestring原始交易所代碼

To 陣列 - 選項欄位​

每個選項代表股東可選擇的付款方式：

欄位類型描述
option_numberstring選項編號標識符
descriptionstring選項描述
default_option_flagstring是否為預設選項：1（是）/ 0（否）
payoutsarray此選項的付款詳情陣列
資訊
  • 可能存在多個付款選項，其中一個標記為預設選項
  • 目前，事件中僅提供預設選項

Payout 欄位​

每個 payout 代表選項內的特定付款類型。單個選項可能包含多個 payout（例如現金 + 證券）。

通用欄位（所有付款類型）​

這些欄位適用於所有付款類型（CASH、SECURITY、SCRIP）：

欄位類型描述
typestring付款類別代碼（例如 DV、FR、IN）
pay_typestring付款類型：CASH、SECURITY 或 SCRIP
payout_numberstring選項內的付款編號
adr_fee_ratestringADR 費率
fraction_share_rulestring碎股處理方式：ROUND_DOWN、ROUND_UP、CASH_IN_LIEU
cancellation_feestring取消費率
issuance_feestring發行費率
tax_statusstringIRS 收入類型代碼

現金付款特定欄位（pay_type：CASH）​

現金付款的額外欄位：

欄位類型描述
currencystring付款幣別
amountstring每股付款金額
withholding_tax_ratestring預扣稅率

證券/SCRIP 通用欄位（pay_type：SECURITY 或 SCRIP）​

這些欄位由證券和 SCRIP 付款共享：

欄位類型描述
symbolstring付款標的代碼
cusipstring付款標的 CUSIP
isinstring付款標的 ISIN
namestring付款標的名稱
exchangestring付款標的交易所
from_ratiostring原始股份比率
to_ratiostring目標股份比率
cash_in_lieu_pricestring碎股的現金替代價格
currencystring付款幣別

證券付款特定欄位（pay_type：SECURITY）​

除通用證券/SCRIP 欄位外，沒有額外的證券特定欄位。

SCRIP 付款特定欄位（pay_type：SCRIP）​

SCRIP 股息（股息再投資）主要適用於港股。

欄位類型描述
reinvest_pricestring每股再投資價格
amountstring每股付款金額

Payout 類型範例​

範例 1：現金股息​

{
    "type": "DV",
    "pay_type": "CASH",
    "payout_number": "1",
    "currency": "USD",
    "amount": "0.25",
    "withholding_tax_rate": "0.15"
}

範例 2：股票股息（10 股 → 1 股）​

{
    "type": "DV",
    "pay_type": "SECURITY",
    "payout_number": "1",
    "symbol": "AAPL",
    "from_ratio": "10",
    "to_ratio": "1",
    "fraction_share_rule": "CASH_IN_LIEU",
    "cash_in_lieu_price": "150.00"
}

範例 3：SCRIP 股息（再投資）​

{
    "type": "DV",
    "pay_type": "SCRIP",
    "payout_number": "1",
    "symbol": "0700.HK",
    "reinvest_price": "350.00",
    "from_ratio": "1",
    "to_ratio": "1"
}

範例 4：混合付款（現金 + 證券）​

一個選項可能包含多個 payout：

{
    "option_number": "1",
    "description": "Cash and Stock",
    "default_option_flag": "1",
    "payouts": [
        {
            "type": "DV",
            "pay_type": "CASH",
            "payout_number": "1",
            "currency": "USD",
            "amount": "0.10"
        },
        {
            "type": "DV",
            "pay_type": "SECURITY",
            "payout_number": "2",
            "symbol": "AAPL",
            "from_ratio": "20",
            "to_ratio": "1"
        }
    ]
}

使用場景​

監聽此事件可用於：

  1. 公司行動追蹤：監控影響持倉的所有公司行動
  2. 股息處理：自動處理股息付款和再投資
  3. 持倉調整：根據股票拆分、併購或轉換更新持倉
  4. 客戶通知：提醒客戶注意需要採取行動的即將到來的公司行動
  5. 稅務報告：追蹤預扣稅和應稅事件以進行報告
  6. 代碼變更：當代碼、CUSIP 或 ISIN 變更時更新標的標識符