簡訊 API 串接教學

一句話：建立 API Key → 呼叫 POST /api/v2/send → 讀 result 與每個門號的狀態。單筆、多號碼、排程都是同一支 API；內容每人不同才需要批次 API。以下用 cURL 示範，任何語言（PHP、Node.js、Python、Java…）照同樣的 HTTP 請求即可。

1. 準備：開通帳號、建立 API Key

• 註冊帳號並完成開通（審核通過後以 Email 通知）。
• 登入會員中心，到「API Key」頁建立金鑰，格式為 sk_live_…。金鑰只會完整顯示一次，請立刻存進伺服器的環境變數或密鑰管理工具。
• 建議同時設定 IP 白名單，只允許自家伺服器的 IP 使用這把金鑰。

2. 發出第一則測試簡訊

把簡訊發到自己的手機，是最直接的「簡訊測試」：

curl -X POST https://sms-api.labspace.com.tw/api/v2/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dstaddr": "0912345678",
    "smbody": "【貴公司名稱】這是一則 API 測試簡訊"
  }'

• dstaddr：手機號碼。台灣可用 09 開頭；海外要帶國碼（例如 8613…）。多個門號以逗號分隔。
• smbody：簡訊內容。開頭的【品牌】需與登記公司名稱相符，不加【】則不受此限。

只想看則數與扣點、不要真的發？把網址換成 /api/v2/send/estimate，回應會有 parts（則數）、points_required（需要點數）、points_available（目前可用點數）。

3. 讀懂回應

成功受理時 result 為 1。帶多個門號時，data.results[] 會逐一列出每個門號的狀態：

{
  "result": 1,
  "text": "群發完成：成功 2，失敗 0",
  "data": {
    "total": 2,
    "sent": 2,
    "failed": 0,
    "points_remaining": 98,
    "results": [
      { "phone": "0912345678", "status": "success" },
      { "phone": "0922345678", "status": "success" }
    ]
  }
}

• success：已送出。failed：送出失敗，可以重送。skipped：略過（例如在拒收名單內，或短時間內同內容已發過），不扣點，不要重送。
• 失敗時 result 為 0，看 code 判斷原因（見下一節），不要只讀錯誤文字。
• 「已送出」不等於「已送達手機」。關鍵訊息請用發送記錄 API（GET /api/v2/logs/{id}）或 Webhook（send.success／send.failed）追蹤每則的結果。

4. 常見錯誤碼與處理

這些業務錯誤發生時簡訊不會送出、也不會扣點。

5. 大量發送：一次請求、別一個門號打一次

最常見的串接錯誤是「名單有 2,000 人，就呼叫 2,000 次 API」。每個來源 IP 每分鐘上限 60 次請求，這樣寫一定會撞到 429；如果撞到後又把整批重送，已經送成功的人會收到好幾則。正確做法：

• 內容相同：一次請求、dstaddr 以逗號分隔多個門號（建議每次 200 個以內、逾時設 90 秒以上），多個門號只算 1 次請求。
• 內容不同（例如帶姓名）：用 /api/v2/send/bulk-upload 上傳名單，再呼叫 /api/v2/send/bulk。
• 只重送失敗的：看 data.results[]，只把 failed 的門號重送。
• 防重送保護：透過 API Key 串接時，同門號＋同內容預設 10 分鐘內只發一次，重複的回 data.duplicate=true、不扣點。這是保險，不是重試策略。

6. 上線前檢查清單

完整端點（發送記錄、排程、通訊錄、範本、儲值）見 API 文件，可直接在頁面上測試或下載 Postman Collection。要做手機驗證碼，另見簡訊驗證碼（OTP）怎麼發；費用與則數規則見簡訊費用怎麼算。

7. 常見問題