給開發者的 Mosaqo API
一套 REST API，操作的就是您在 App 裡使用的那個工作區。以下所有內容只需要一把 API 金鑰和任何 HTTP 用戶端就能完成。
您可以做什麼
- 從您自己的記錄建立 QR 碼——一次一個，或是從一份 CSV 一次一萬個。
- 改變已印製的碼指向何處，一次呼叫就好，不必重印任何東西。
- 將完成的卡片下載成 PNG、SVG 或 PDF，附加到 CRM 記錄上。
- 讀取掃描記錄與彙總分析資料，並依工作區的隱私規則篩選。
- 在碼被建立、發布、變更或封存時接收帶簽章的 webhook。
快速上手
在工作區的 Bulk & API 中建立一把金鑰，勾選 qr:write 與 qr:read 權限範圍，然後複製 secret——它只會顯示一次。
檢查金鑰，確認它開啟的是哪一個工作區：
curl https://api.mosaqo.app/v1/public-api/me \
-H "Authorization: Bearer $MOSAQO_KEY"建立一個動態 QR 碼：
curl -X POST https://api.mosaqo.app/v1/public-api/qr \
-H "Authorization: Bearer $MOSAQO_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Autumn campaign",
"mode": "dynamic",
"contentType": "url",
"content": { "targetUrl": "https://example.com/autumn" }
}'發布它——轉址要發布之後才會生效——接著取得可以拿去列印的圖片：
curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
-H "Authorization: Bearer $MOSAQO_KEY"
curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
-H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png幾個月後活動換了去處，不必重印，直接把同一個已印製的碼指向新目標：
curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
-H "Authorization: Bearer $MOSAQO_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/winter" }'身分驗證
兩種方式都可以送出您的 secret，整個 v1 期間都會支援。
Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx一把金鑰只屬於一個工作區，所以路徑不需要工作區 id：/v1/public-api/qr 就夠了。較舊的 /v1/public-api/workspaces/{workspaceId}/qr 形式仍然可用。
| 權限範圍 | 授予的權限 |
|---|---|
qr:read | 列出並讀取 QR 碼、資料夾與範本 |
qr:write | 建立、更新、重新指定目標、發布、封存與刪除 |
exports:read | 下載產生好的卡片 |
analytics:read | 彙總分析資料與個別掃描記錄 |
bulk:write | 建立與讀取批次工作 |
webhooks:write | 管理 webhook 訂閱 |
金鑰可以撤銷、設定到期日，也可以限制在 IP 允許清單內。被允許清單擋下的金鑰會收到明確的說明，而不是看起來像是無效金鑰。
分頁
清單採用 keyset 分頁。把 pagination.nextCursor 原樣傳回即可；不會因為同步途中有東西被編輯就重複或漏掉資料列——這對整夜執行的同步作業特別重要。
curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
-H "Authorization: Bearer $MOSAQO_KEY"若只想輪詢變更而不是走完全部資料，加上 updatedSince=2026-08-05T00:00:00Z。
錯誤
每個失敗回應都帶有可用來分支判斷的穩定 code、給人看的 message，以及聯絡支援時值得一併提供的 requestId。
{
"error": "This API key does not have the qr:write scope.",
"message": "This API key does not have the qr:write scope.",
"code": "insufficient_scope",
"details": { "required": "qr:write", "granted": ["qr:read"] },
"requestId": "req-42"
}| 狀態碼 | 錯誤碼 | 該怎麼做 |
|---|---|---|
| 401 | invalid_api_key | 金鑰不存在、已撤銷或已過期。請使用者重新連接。 |
| 403 | insufficient_scope, ip_not_allowed, workspace_mismatch, quota_exceeded | 金鑰有效，但沒有權限做這件事。重新連接也沒有用。 |
| 404 | not_found | 這個工作區裡沒有這筆記錄。 |
| 409 | idempotency_conflict, idempotency_in_progress | 重複使用同一個鍵卻帶了不同的輸入，或第一次嘗試仍在執行中。 |
| 422 | validation_failed, invalid_cursor, approval_required, contrast_check_failed | 修正輸入。切勿原樣重試。 |
| 429 | rate_limited | 等待 Retry-After 指定的秒數。 |
速率限制
每個回應都會帶上您目前的額度，不只是被拒絕的那些：
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718這個限制是防濫用機制，不是方案：它不牽涉配額、計費或升級管道。
冪等性
Idempotency-Key 是選用的。帶上一個——任何唯一字串都行——24 小時內重試完全相同的請求會重播原本的回應，而不會執行兩次。同一個鍵配上不同的輸入會回傳 409。不帶這個標頭時請求就照常執行，沒有重播保護。