整合範例

四種做法幾乎涵蓋了我們見過的所有整合。每一種都只是幾個呼叫，而且可以互相組合。

替已印製的碼換目標

這正是多數團隊會用到 API 的原因。印在包裝、貼紙或海報上的碼可以一直有效，而它背後的活動隨時可以換。

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" }'

對已發布的碼，變更會立即生效——不需要再發布一次——回應也會告訴您這個碼是 live 還是仍為草稿。

把 QR 碼附到 CRM 記錄上

用記錄本身的網址建立碼，發布它，再把圖片直接拉進檔案欄位。圖片端點會直接回傳位元組內容，因此多數 CRM 不必先上傳到別處就能當成附件收下。

const headers = { Authorization: `Bearer ${process.env.MOSAQO_KEY}` };

const created = await fetch('https://api.mosaqo.app/v1/public-api/qr', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: `Deal ${deal.id}`,
    mode: 'dynamic',
    contentType: 'url',
    content: { targetUrl: `https://crm.example.com/deals/${deal.id}` },
  }),
}).then((r) => r.json());

const qrId = created.data.id;
await fetch(`https://api.mosaqo.app/v1/public-api/qr/${qrId}/publish`, { method: 'POST', headers });

const png = await fetch(
  `https://api.mosaqo.app/v1/public-api/qr/${qrId}/image?format=png&size=1024`,
  { headers },
).then((r) => r.arrayBuffer());

把 qrId 存在您的記錄上。之後的一切都靠它——換目標、封存、看分析。

大量核發碼

每個產品、每張桌子、每項資產一個碼。上傳一份 CSV，輪詢這項工作，再把結果對應回您自己的資料列——每一列都帶著它產生的 qrId。

curl -X POST https://api.mosaqo.app/v1/public-api/bulk \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "url",
    "mode": "dynamic",
    "csv": "name,destination\nTable 1,https://example.com/menu?t=1\nTable 2,https://example.com/menu?t=2"
  }'

curl "https://api.mosaqo.app/v1/public-api/bulk/$JOB_ID?limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

先送出 "dryRun": true，即可在不寫入任何資料的情況下驗證每一列。

用網址嵌入圖片

Airtable、Notion 與 Sheets 是自己去抓連結來顯示圖片，因此不會帶上您的 Authorization 標頭，也就用不了上面那個端點。請改為索取一條帶簽章的連結：

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image-url \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "size": 1024 }'

只有已發布的碼適用——已發布的碼本來就已經印出來、流傳在外，而草稿可能是還沒公開的活動。把回傳的 url 直接放進附件或圖片欄位即可。封存或刪除這個碼會讓連結立刻失效，若某條連結傳得比您預期的更遠，就用這個方式收回。

對掃描做出反應

掃描從不推送：沒有單次掃描的 webhook，我們也不會把掃描層級的分析資料送到第三方端點。如果彙總資料就夠用，請訂閱 scan.aggregate_ready；否則就按排程自行取得個別掃描記錄：

curl "https://api.mosaqo.app/v1/public-api/scans?since=$LAST_SEEN&limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

保留回傳的 pagination.nextCursor，下次原樣傳回。排序是穩定的，因此輪詢程式既不會重複讀取也不會漏掉掃描記錄。會出現哪些欄位取決於工作區的分析隱私設定——回應會列出 allowedDimensions，讓您知道能拿到什麼。

如果輪詢對您確實行不通，需要掃描一發生就送達，這可以另外申請，但並非預設提供。

無程式碼平台

Make、Zapier、n8n 與 Pipedream 現在都能用通用 HTTP 模組與 Mosaqo 溝通，它們需要的元件也都已就位：GET /me 當作連線測試、供迭代器使用的游標分頁，以及觸發器可以自行建立與移除的 webhook 訂閱。

同一份 OpenAPI 文件可以匯入 Postman 與 Insomnia，也能用 openapi-typescript 或任何 OpenAPI 產生器產生具型別的用戶端。

兩條值得遵守的原則

• 請存 `qrId`，不要存公開網址。 網址是穩定的，但之後每一次呼叫需要的都是這個 id。
• 用封存，別用刪除。 刪除是永久的，會讓每一份印出去的副本失效；封存只是讓碼下線，而且可以復原。

完整的端點細節請見 API 參考。