從 API 請求到 DLR Webhook 的關聯識別碼追蹤實作指南

請求追蹤簡介

高流量的通訊基礎設施部署需要在非同步邊界之間保持嚴格的可稽核性。當發送大規模的訊息批次時，標準的 HTTP 狀態碼僅能確認初步的接收狀態，例如由 API 閘道或訊息佇列的初步確認。為了驗證最終的傳遞狀態，工程師必須將決定性的追蹤識別碼從出站 API 酬載一直傳遞到入站的傳遞收據（Delivery Receipt, DLR）。IOSOR 提供原生支援，可透過電信商交接攜帶自訂追蹤標頭，讓您能在內部可觀測性堆疊中進行即時對帳，而無需猜測訊息狀態。此機制對於除錯、監控和財務對帳至關重要，確保每個訊息的生命週期都有清晰的記錄。

預付錢包與餘額控管

確保高吞吐量分派作業順暢運作的關鍵，在於維持足夠的帳戶資金額度。您的預付錢包必須隨時持有至少 USD 20 的低標水位，以防止 API 請求在關鍵時刻遭到阻斷，同時系統會精確記錄預付錢包持有的每筆資金分配。此預付錢包會嚴格控管每次扣款的餘額狀態以維持系統穩定性，當帳戶達到較高的流量規模時，系統會自動啟用預付錢包扣款檢核，確保每筆訊息傳遞都能即時從總帳中扣除對應成本。若您的每月分派規模接近或超過 USD 1,000，請提早完成相關的流量審查與容量規劃，以避免在尖峰時段面臨自動化節流限制。系統會監控錢包餘額，並在低於預設閾值時觸發通知，以便及時補充，避免服務中斷。每次成功的訊息分派都會從預付錢包中扣除相應的費用，並在交易記錄中留下詳細的條目，包括時間戳、訊息 ID、目標號碼及扣款金額。

在分派時注入識別碼

請在 SMS 或 OTP 分派請求的 JSON 本文中插入唯一的追蹤權杖來啟動追蹤。IOSOR 在請求結構描述內接受自訂後設資料字串，並在整個內部路由管線中保留這些值。這確保了透過 Webhook 傳回的每個傳遞收據都包含您原始的追蹤參照。請確保在分派酬載中嚴格遵守資料結構規範，讓後續的資料流轉與剖析作業能夠在各個微服務節點之間保持一致，並在傳送過程中保留完整的稽核軌跡。您可以將此識別碼命名為 `correlation_id` 或任何您選擇的名稱，只要它在您的系統中是唯一的且一致的。此欄位應為字串類型，長度限制請參考 API 文件。在 API 請求的頂層 JSON 物件中添加此欄位，例如：`{"to": "+1234567890", "message": "Hello!", "correlation_id": "unique-request-12345"}`。

處理非同步 Webhook 與狀態真相

傳遞收據會以非同步方式作為 JSON 酬載發送到您設定的 Webhook 端點，此即為 DLR 與 Webhook 互動的唯一真實真相來源。由於電信商以波動的叢集處理流量，DLR 結果可能會亂序到達或經歷網路層級的重試。您的入站工作者必須解析入站的 JSON，擷取嵌入的追蹤參照，並將終端狀態與您的主要交易總帳進行關聯。務必驗證入站 Webhook 上的密碼學簽章，以防止針對您的記錄基礎設施發動偽造與資料注入攻擊，同時確保所有事件處理程序具備容錯與防重放能力。Webhook 酬載通常包含 `message_id`, `status` (e.g., `DELIVERED`, `FAILED`, `UNDELIVERABLE`), `error_code`, `timestamp`, 以及您注入的 `correlation_id`。請確保您的 Webhook 端點能夠處理高併發請求，並實作適當的錯誤處理和重試機制，以應對潛在的網路問題或伺服器故障。建議在處理 DLR 時，將 `correlation_id` 作為查詢您內部資料庫以查找原始請求記錄的主要鍵。

靜默時段與退訂機制同步

為了維護法規遵循並提供良好的終端使用者體驗，系統內建了嚴格的靜默時段控管，可自動阻斷深夜時段的干擾。您可以針對特定專案設定靜默時段，確保行銷性質或非緊急的通知不會在深夜時段觸發，以免造成客戶干擾。此外，平台會自動將使用者的 opt-out 退訂狀態同步到全域拒收名單中，確保所有 opt-out 同步作業在多個節點之間完全一致。當任何號碼被標記為退訂後，系統會在邊緣節點直接攔截後續的發送請求，並立即回傳拒絕回應，確保您的通訊活動完全符合當地法規與使用者意願。靜默時段的設定通常以時區為基礎，並可自訂開始與結束時間。退訂狀態的同步是透過一個中央化的拒收名單服務實現，確保所有訊息路由節點都能即時獲取最新的退訂資訊。這對於遵守 GDPR、TCPA 等法規至關重要。

總帳對帳與實作建議

先挑一封外送 SMS 或 OTP。在 accept 之前把 correlation ID 打進 API 請求，再讓同一字串走過派送中繼資料與 DLR webhook 本體。匯出跳躍清單：請求 id、受理時刻、回呼抵達、終態。別在 HTTP 200 停手，也別把這條路徑叫做扣款列對帳——那份契約在兄弟文。在您的 API 請求中，務必包含一個唯一的 `correlation_id`。當 API 成功接收請求後，記錄下請求的時間戳。當您收到來自 IOSOR 的 DLR Webhook 回調時，解析其中的 `correlation_id`，並將其與接收到的狀態（例如 `DELIVERED`, `FAILED`）和回調的時間戳進行匹配。將這些資訊與您最初的請求記錄進行關聯，以驗證訊息的最終狀態。此過程應在您的後端系統中自動化，以實現高效的對帳。請注意，HTTP 200 僅表示 API 成功接收了請求，並不代表訊息已成功送達終端使用者。最終的送達狀態必須依賴於 DLR Webhook。

相關: 冪等、重試與資金安全 回呼簽章與重放時窗 扣款與 DLR 之間的關聯識別碼.

IOSOR 要點

從請求追到 DLR 是跳躍鏈。受理不等於送達。

要做：從第一份 API 本體到最後一則簽名回呼，只留一個不可改的 ID。

不要：用 HTTP 200 結案，或在回執掉落後用業者時戳拼回路徑。