連携レシピ

4つのパターンで、私たちが目にするほぼすべての連携をカバーできます。それぞれ数回の呼び出しで済み、組み合わせて使えます。

印刷済みコードのリンク先を変更する

ほとんどのチームがそもそも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のレコードにQRを添付する

レコード自身の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 を保存してください。以降のすべての操作 — リンク先変更、アーカイブ、アナリティクス — の入口になります。

コードを一括発行する

製品ごと、テーブルごと、資産ごとに1つのコードを。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ジェネレーターで型付きクライアントを生成できます。

守るべき2つのルール

• 公開URLではなく `qrId` を保存すること。 URLは変わりませんが、以降のすべての呼び出しが必要とするのはIDです。
• 削除ではなくアーカイブすること。 削除は取り消せず、印刷済みのすべてのコピーが使えなくなります。アーカイブはコードをオフラインにするだけで、元に戻せます。

エンドポイントの詳細はAPIリファレンスにあります。