Skip to content

Create Short URL Batch

Description

一次將多個長網址縮短為短網址。與 Create Short URL 的差別只有「一次處理多筆」，去重與冪等規則完全相同。

  • 相同的原始網址重複建立時，會回傳同一個短網址（不會重複產生）。與單筆端點共用同一份資料，兩邊互通。
  • 同一批內重複的網址（含僅前後空白不同者）共用同一個短網址，只建立一次。
  • 產生的短網址永久有效。
  • 單筆失敗不影響其他筆：該筆回傳 error、其餘照常回傳短網址。
  • 回傳順序與請求的 urls 相同，且每筆帶回呼叫端送來的原始字串，可直接對應。

適用情境：一次要為大量項目產生 QR Code，例如一家門市數百張桌牌。逐筆呼叫單筆端點會累積成數分鐘的往返時間。

Resource

POST /v1/shorturl/batch

Authorization

此 API 為公開端點，無需授權。

Request Body Parameters

Name Type Description
urls array 欲縮短的原始網址清單；至少 1 筆、最多 1000 筆。每筆須為合法的 http/https 網址，長度上限 2048

超過 1000 筆時整批回 400，不會截斷處理。請自行分批送出。

Request Example

{
    "urls": [
        "https://example.com/entry?data=eyJhdXRoa2V5IjogIjdrYW14...",
        "https://example.com/entry?data=eyJhdXRoa2V5IjogIjhsYm55..."
    ]
}

Response Body Parameters

Name Type Description
results array 逐筆結果，順序同請求

results 內每一筆：

Name Type Description
url string 呼叫端送來的原始網址，原字串回傳
code string 產生的短碼（7 碼）；該筆失敗時不會出現此欄位
short_url string 完整短網址；該筆失敗時不會出現此欄位
error string 該筆的失敗原因；該筆成功時不會出現此欄位

同一筆不會同時出現 code 與 error，請以 code 是否存在判斷該筆成功與否。

Response

HTTP-Status-Code: 200 

{
    "results": [
        {
            "url": "https://example.com/entry?data=eyJhdXRoa2V5IjogIjdrYW14...",
            "code": "AbC12xZ",
            "short_url": "https://<api-domain>/s/AbC12xZ"
        },
        {
            "url": "ftp://example.com/file",
            "error": "參數格式錯誤"
        }
    ]
}

HTTP-Status-Code: 400 

{
    "message": "缺少必填欄位 原始網址清單"
}

HTTP-Status-Code: 400 

{
    "message": "參數格式錯誤"
}

整批回 400 的情況：未帶 urls、urls 不是陣列、urls 為空陣列、urls 筆數超過 1000。