QRコードAPIとWebhook

APIとWebhookの機能

REST APIは/api/v1のパスにあり、応答はJSONです。コードの一覧（検索、タグ絞り込み、最大100件ずつのページ分け）、1件の読み取り、作成、更新、削除、プレーンなSVGの取得、直近30日間のスキャン集計ができます。キーはqrk_で始まるBearerトークンで、1つのワークスペースに属します。

Webhookは、受け取るイベントを登録するHTTPSのアドレスです。対象のイベントが起きるたびに、アプリはJSONのメッセージを送ります。テスト操作はpingイベントを送るので、本番の前に受信側を確認できます。各配信は、シークレットを使いHMAC-SHA256で署名されます。

このAPIは連携を構築する人のためのもので、コードの見た目は変えません。SVGは白黒のプレーンな画像で、ロゴや色はエディタで作成します。APIにはTeamプランが必要で、キーはプランを下げても残りますが、戻るまでは機能しません。

APIの利用を始める手順

1. 01

   オーナーとしてキーを作成する

   オーナーとしてAPIページを開き、サーバーなど用途が分かる名前でキーを作成します。トークンは1度だけ表示されるので、すぐにシークレットの保管先へコピーしてください。以後は名前、プレフィックス、作成日、最終利用日だけが見えます。

2. 02

   各リクエストにキーを付けて送る

   Authorizationヘッダーの値は、Bearerという語、半角スペース、トークンの順です。最初にアカウント確認の呼び出しを行うと、ワークスペース名、キー、残りのクレジットが返るので、設定を確かめられます。キーがないか誤っていると認証エラーになります。

3. 03

   コードの作成、更新、読み取り

   名前、種類（既定値はウェブリンク）、内容、任意の項目（ダイナミック、スラッグ、有効期限、パスワード、認証済みドメイン、タグ、スタイル）を送ります。作成には1クレジット、読み取りと更新は無料です。検証に失敗すると理由が返り、クレジットは戻ります。

APIが役立つ場面

• チケットと予約

  予約システムが座席を確定すると、そのチケット用のダイナミックコードを作成し、短縮リンクとSVGを購入者へ送ります。メールやウォレットのパスにも同じコードが入るため、手作業のコピーは不要です。

• 在庫と備品のタグ

  倉庫のシステムは、品目ごとにコードを1つ作り、品番をタグとして付けられます。各スキャンが記録されるので、任意の品目の30日間の集計から、最近確認されたタグが分かります。

• スプレッドシートからのメニュー更新

  スクリプトがメニューリンクのスプレッドシートを読み込み、APIで各ダイナミックコードの内容を更新できます。印刷されたコードはそのままで、更新は次回のスキャンから反映されます。

• イベントの受付とアンケート

  イベント運営チームは、フォーム付きのランディングページを公開し、回答ごとにWebhookを受け取れます。別のシステムがそれに反応するため、回答を定期的に取りに行く必要はありません。

• 監視とアラート

  Webhookの受信側は、国やデバイス別のスキャンを保存し、コードのスキャンが止まったら通知できます。何を問題とみなすかは、アプリではなくお客様のシステムが判断します。

安定した連携のためのヒント

キーはパスワードと同じように保管する

キーは1度だけ表示され、ダイジェストとしてのみ保存されるため、アプリが再表示することはできません。キーが漏えいした場合は、APIページで無効にして新しいキーを作成してください。無効にすると、古いトークンを使うリクエストはすぐにすべて止まります。

レート制限とクレジットを守る

キーごとに1分間120件までリクエストを送れ、超えるとリクエスト過多の応答が返ります。クレジットが尽きると、作成は支払いが必要であることを示す応答になります。購入機能はまだないので、バッチ処理は残高を見て計画してください。

署名とタイムスタンプを検証する

シークレットを使い、タイムスタンプ、ドット（.）、生の本文を連結した値のHMAC-SHA256を計算して、署名ヘッダーと比べてください。古すぎるタイムスタンプは拒否して再送を防ぎ、配信IDで重複を無視してください。

自分で管理するエンドポイントを使う

Webhookのアドレスは、HTTPSで認証情報を含まず、公開アドレスに解決される必要があります。ローカルホストやプライベートネットワークは拒否され、リダイレクトはたどられません。失敗した配信は最大5回まで再試行されます。

APIとWebhookに関するよくある質問