集成范例

四种做法几乎覆盖了我们见过的所有集成。每一种都只是几个调用，而且可以互相组合。

给已印刷的码换目标

这正是多数团队开始用 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 还是仍处于草稿状态。

把二维码附到 CRM 记录上

用记录自身的 URL 创建码，发布它，然后把图片直接拉进文件字段。图片端点会内联返回字节流，所以多数 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，可以在不写入任何数据的情况下校验每一行。

用 URL 嵌入图片

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`，不要存公开 URL。 URL 是稳定的，但之后每一次调用需要的都是这个 id。
• 归档，而不是删除。 删除是永久性的，会让每一份印出来的副本失效；归档只是让码下线，而且可以撤销。

完整的端点细节见 API 参考。