開發人員

HTTP API

基礎網址 https://osim.live/api/v1 — 簡訊驗證與旅行 eSIM。在控制台建立金鑰，再用 Bearer 呼叫。

驗證

每個私有請求都要帶上 API 金鑰。金鑰以 osim_ 開頭，在帳戶頁建立。

Authorization: Bearer osim_…

切勿把金鑰嵌進公開的前端。請優先使用伺服器端或後端代理。

開啟控制台金鑰

回應格式

每個端點都回傳帶 success 旗標的 JSON。錯誤使用同一結構，並帶 error 字串。

// Success
{ "success": true, "data": { … } }

// Error
{ "success": false, "error": "message" }

基礎 URL: https://osim.live/api/v1
Content-Type: application/json
已為瀏覽器用戶端啟用 CORS (OPTIONS 已支援)
金額以 USD cents 為單位，除非另有說明 (balanceCents, sellCents)

GET/api/v1

API 索引 — 版本與可用資源路徑。無需金鑰。

公開

curl https://osim.live/api/v1

GET/api/v1/me

綁定此 API 金鑰的目前帳戶：id、email、name 與錢包餘額。

需要 Bearer

curl https://osim.live/api/v1/me \
  -H "Authorization: Bearer osim_…"

// data
{
  "id": "…",
  "email": "[email protected]",
  "name": "…",
  "balanceCents": 2500,
  "balance": "$25.00"
}

簡訊驗證

GET/api/v1/sms?catalog=1

服務、國家、USD 價格與允許租用時長的公開目錄。

公開

curl "https://osim.live/api/v1/sms?catalog=1"

// data
{
  "services": [
    {
      "slug": "whatsapp",
      "service": "WhatsApp",
      "category": "…",
      "countries": [
        { "code": "TR", "name": "Turkey", "countryId": 12, "priceUsd": 0.35, "successRate": 92 }
      ]
    }
  ],
  "rentHours": [4, 12, 24, 72, 168]
}

GET/api/v1/sms

列出你最近的簡訊訂單。

需要 Bearer

預設：金鑰擁有者最近 50 筆簡訊訂單

curl https://osim.live/api/v1/sms \
  -H "Authorization: Bearer osim_…"

POST/api/v1/sms

購買、租用、查詢狀態、取消、完成或重送。不提供 call-verify。

需要 Bearer

通用請求本文

欄位	類型	必填	說明
`action`	string	是	purchase \| activation \| rent \| status \| refresh \| cancel \| complete \| resend
`service / serviceSlug`	string	是	目錄 slug，例如 whatsapp
`countryId / country`	number	否	目錄中的供應商國家 id（購買和租用時必填）
`priceId`	string	否	可選，鎖定到某一價格列
`maxPrice`	number	否	可選的美元上限
`operator`	string	否	可選的網路偏好
`hours / time`	number	否	僅租用：4 \| 12 \| 24 \| 72 \| 168
`id / activationId`	string	否	用於查詢狀態、取消、完成和重發的訂單 id

purchase / activation

一次性簡訊驗證號碼（約 20 分鐘）。不提供來電驗證。

curl -X POST https://osim.live/api/v1/sms \
  -H "Authorization: Bearer osim_…" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "purchase",
    "service": "whatsapp",
    "countryId": 12
  }'

rent

較長租用。允許的小時數：4、12、24、72、168。

{
  "action": "rent",
  "service": "telegram",
  "countryId": 16,
  "hours": 24
}

status / refresh

{ "action": "status", "id": "cm…" }

cancel · complete · resend

{ "action": "cancel", "id": "cm…" }
{ "action": "complete", "id": "cm…" }
{ "action": "resend", "id": "cm…" }  // 僅在支援時的租用線路

旅行 eSIM

GET/api/v1/esim?catalog=1

公開方案目錄（slug / packageCode、data、天數、售價）。

公開

curl "https://osim.live/api/v1/esim?catalog=1"

GET/api/v1/esim

列出你的 eSIM 訂單，或用 id 取得一筆（可能時會更新用量）。

需要 Bearer

預設：最近 50 筆 eSIM 訂單
單筆訂單並重新整理用量： ?id=cm…

curl "https://osim.live/api/v1/esim?id=cm…" \
  -H "Authorization: Bearer osim_…"

POST/api/v1/esim

購買方案、重新整理設定檔、重新命名、列出加值選項或套用加值。

需要 Bearer

欄位	類型	必填	說明
`action`	string	是	purchase \| refresh \| rename \| topup-options \| topup
`slug / packageCode`	string	否	用於購買和加值的目錄方案
`id`	string	否	用於重新整理、重新命名和加值的訂單 id
`label`	string	否	重新命名時的新顯示名稱

// Purchase
{
  "action": "purchase",
  "packageCode": "turkey-5gb-30d"
}

// Refresh profile / usage
{ "action": "refresh", "id": "cm…" }

// Rename
{ "action": "rename", "id": "cm…", "label": "Trip TR" }

// Top-up options + apply
{ "action": "topup-options", "id": "cm…" }
{ "action": "topup", "id": "cm…", "packageCode": "…" }

購買回應在可用時包含 LPA 啟用字串與 QR 圖片 URL。

錯誤

HTTP	何時
`200`	`success: true`
`400`	驗證或業務錯誤（餘額不足、未知操作……）
`401`	缺少或無效的 API 金鑰
`404`	此帳戶下找不到訂單

說明

購買時以 USD 美分扣餘額。供應商購買失敗會退款。
一次性簡訊號碼通常約 20 分鐘。租用時長以目錄中的小時數為準。
可能適用速率限制與濫用控管。更高用量請聯絡支援。
OpenAPI/Swagger 匯出尚未發布 — 本頁為權威說明。