Labspace SMS

API 文件

RESTful API，JSON 格式，Bearer Token 認證

提示：可用瀏覽器的「列印 → 儲存為 PDF」取得可歸檔的文件版本（互動測試區不會列印）。

快速開始

1. Base URL

https://sms-api.labspace.com.tw

2. 認證方式

Authorization: Bearer {your_api_key}
Content-Type: application/json

3. 發送簡訊範例

cURL

curl -X POST /api/v2/send \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dstaddr": "0912345678, 8613912345678",
    "smbody": "您的驗證碼為 123456"
  }'

回應

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

4. 號碼格式

dstaddr 僅允許數字、+、逗號、空格；多筆號碼用逗號或空格分隔。

類型格式範例
台灣手機（推薦）09xxxxxxxx0912345678
台灣國際8869xxxxxxxx886912345678
中國手機1[3-9]xxxxxxxxx / 8613xxxxxxxxx13912345678
其他海外必須含國碼（不含 +），符合 E.16414155552671

海外號碼必須含國碼，否則無法送達

常見國碼：886（台灣）、86（中國）、1（美/加）、81（日本）、82（韓國）、65（新加坡）、66（泰國）、84（越南）、852（香港）、44（英國）

ERR_INVALID_NUMBER：號碼通過格式檢查但實際無效（缺一碼、開頭 1 但非 11 碼、開頭 0 但非 09 等），send_log 標示此錯誤、status=0、不扣點。

Postman Collection

匯入後即可直接測試所有 API v2 端點。使用前請於 Variables 填入您在會員中心建立的 API Key。

下載 Collection

API Playground

輸入 API Key，選擇端點，即時測試 API 回應

POST/api/v2/send
cURL 指令
curl -X POST "https://sms-api.labspace.com.tw/api/v2/send" \
  -H "Authorization: Bearer {your_api_key}" \
  -H "Content-Type: application/json" \
  -d '{ "dstaddr": "0912345678, 8613912345678", "smbody": "您的驗證碼為 123456"}'

API 端點總覽

認證

POST
/api/v2/auth/login

登入取得 JWT Token

POST
/api/v2/auth/refresh

續約 Token（httpOnly cookie）

POST
/api/v2/auth/logout

登出

發送簡訊

POST
/api/v2/send

發送簡訊

選填 scheduled_at 即為排程發送（格式 YYYY-MM-DD HH:MM:SS、台灣時區、須為 5 分鐘後至 30 天內）。不帶此欄位即立即送出；排程只預留點數，取消後全額退回。

POST
/api/v2/send/estimate

預估費用（不實際發送）

POST
/api/v2/send/bulk-upload

上傳 CSV 批次發送

multipart/form-data

POST
/api/v2/send/bulk-preview

預覽批次發送結果

POST
/api/v2/send/bulk

確認批次發送

選填 scheduled_at 即為排程發送（格式 YYYY-MM-DD HH:MM:SS、台灣時區、須為 5 分鐘後至 30 天內）。不帶此欄位即立即送出；排程只預留點數，取消後全額退回。

GET
/api/v2/realname/whitelist

查詢本帳號可用的實名 tag（登記名稱 + 已核可品牌）

GET
/api/v2/realname/whitelist/check?smbody=<訊息>

檢核簡訊是否會被實名 gate 擋（送整則訊息，系統自動抽出開頭 tag）

POST
/api/v2/realname/applications

申請新的實名品牌 tag（可附證明圖片 JPG／PNG 3MB 內）

multipart/form-data

GET
/api/v2/sms/scheduled

查詢排程佇列（待送 / 已送出 / 已取消 / 觸發失敗）

GET
/api/v2/sms/scheduled/{batch_id}

查詢單一排程批次的完整內容與收件人清單

DELETE
/api/v2/sms/scheduled/{batch_id}

取消排程（僅待送狀態可取消，點數立即退回）

GET
/api/v2/sms/available-points

查詢可用點數（總點數 / 已排程預留 / 可用）

批次發送的 CSV 範本（含台灣 / 海外國碼示範與變數欄位）： CSV / XLSX

發送記錄

GET
/api/v2/logs?page=1&per_page=20&status=&start_date=&end_date=

發送記錄列表（分頁）

GET
/api/v2/logs/{id}

單筆記錄詳情

GET
/api/v2/logs/export

匯出 CSV

帳號

GET
/api/v2/me

個人資料 + 餘額

PUT
/api/v2/me/password

修改密碼

GET
/api/v2/dashboard

儀表板統計

GET
/api/v2/dashboard/stats?range=7d

圖表統計

API Key

GET
/api/v2/api-keys

API Key 列表

POST
/api/v2/api-keys

建立 API Key

DELETE
/api/v2/api-keys/{id}

撤銷 API Key

通訊錄

GET
/api/v2/contacts?page=1&search=&group_id=

聯絡人列表

POST
/api/v2/contacts

新增聯絡人

PUT
/api/v2/contacts/{id}

編輯聯絡人

DELETE
/api/v2/contacts/{id}

刪除聯絡人

GET
/api/v2/contact-groups

群組列表

POST
/api/v2/contact-groups

建立群組

訊息範本

GET
/api/v2/templates

範本列表（含系統預設）

POST
/api/v2/templates

新增範本

PUT
/api/v2/templates/{id}

編輯範本

DELETE
/api/v2/templates/{id}

刪除範本

儲值

GET
/api/v2/topup/packages

點數方案列表

POST
/api/v2/topup/order

建立儲值訂單

GET
/api/v2/topup/history?page=1

儲值訂單

GET
/api/v2/topup/export

儲值訂單 CSV 匯出

HTTP 狀態碼

Code說明
200成功
201建立成功
401未認證 / Token 無效或過期
403帳號待審核 / 已停用
404資源不存在
422驗證錯誤（欄位格式不正確）
429請求過於頻繁
500伺服器錯誤

業務錯誤碼

除 HTTP 狀態碼外，發送類 API 失敗時會在 response 帶 code 欄位標示原因，部分錯誤另附 data 供前端處理：

{
  "result": 0,
  "code": "REALNAME_TAG_VIOLATION",
  "error": "簡訊開頭 tag「【xxx】」未通過實名檢查...",
  "data": { "tag": "xxx" }
}
CodeHTTP說明
REALNAME_TAG_VIOLATION422簡訊開頭品牌 tag 未通過實名檢查（依電信業者實名制規範，tag 需與登記公司名稱相符）。data.tag 為被擋下的 tag。
FORBIDDEN_DOMAIN422訊息含免費短網址服務網域，依規範一律禁止。
DOMAIN_NOT_WHITELISTED422訊息含尚未申請白名單的網域。
SUB_ACCOUNT_SUSPENDED422子帳號已被停用（母帳號點數不足或遭停權）。
SUB_ACCOUNT_QUOTA_EXCEEDED422子帳號本月發送量已達配額上限。
INSUFFICIENT_BALANCE422帳戶點數不足以支付本次發送。

遇到業務錯誤時簡訊不會送出、也不會扣點。建議在串接端針對 code 做分支處理，而非只讀 error 文字。

實名 tag 預先檢核

呼叫費用預估 API 時，若簡訊開頭 tag 未通過實名比對，data 會帶 realname_tag_shadow_warning 欄位（值為該 tag，通過時為 null）。可用來在實際送出前提示使用者，避免送出後才被擋。

POST /api/v2/send/estimate
{
  "result": 1,
  "data": {
    "parts": 1,
    "realname_tag_shadow_warning": "xxx"   // null = 通過
  }
}

速率限制

API 請求限制為每分鐘 60 次。超過限制將回傳 HTTP 429。 回應 Header 包含：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58

需要更詳細的 API 文件或串接協助？請聯絡我們