開発者向け
API＆インテグレーションリファレンス
ビジネスAPIの呼び出し、APIキーの管理、Webhookの受信に必要なすべての情報。
認証
ビジネスAPIはすべてのリクエストでAPIキーによる認証を行います。X-Api-Keyヘッダー、またはAuthorizationヘッダーのBearerトークンとして送信してください。
キーには qrg_ プレフィックスが付いており、作成時に一度だけ表示されます。後から再確認することはできませんので安全に保管してください。
有効なキーがないリクエストは401を返します。必要な権限を持たないキーには、エラー insufficient_scope とともに403が返されます。ワークスペース外のリソースは、存在しないものとして404を返します。
ベースURL
すべてのビジネスAPIエンドポイントは /v1 プレフィックスの下に存在します。
例えば、QRコード一覧の取得は https://qr-global.com/api/v1/qr-codes にリクエストします。
- 解決されたベースURL
- https://qr-global.com
エンドポイント
すべてのエンドポイントは /api/v1 の下にあり、記載された権限を持つキーが必要です。
| メソッド | パス | 権限 | 説明 |
|---|---|---|---|
| GET | /qr-codes | qr:read | QRコード一覧（フィルター：type、search、folder_id、tag、archived） |
| POST | /qr-codes | qr:write | QRコードを作成 |
| POST | /qr-codes/bulk | qr:write | 最大100個のQRコードを一度に作成 |
| GET | /qr-codes/{id} | qr:read | QRコードを1件取得 |
| PUT | /qr-codes/{id} | qr:write | QRコードとそのフォルダー・タグを更新 |
| DELETE | /qr-codes/{id} | qr:write | QRコードを削除 |
| GET | /qr-codes/{id}/image | qr:read | 画像をレンダリング（PNGまたはSVG） |
| GET | /qr-codes/{id}/stats | analytics:read | スキャン統計 |
| GET | /qr-codes/{id}/scans | analytics:read | スキャンログ |
| GET | /folders | qr:read | フォルダー一覧 |
| GET | /tags | qr:read | タグ一覧 |
| GET | /webhooks | webhooks:manage | Webhook購読の一覧 |
| POST | /webhooks | webhooks:manage | イベントを購読 |
| DELETE | /webhooks/{id} | webhooks:manage | 購読を解除 |
Postman、コードジェネレーター、ノーコードツール向けの機械可読な仕様（OpenAPI 3.1）： openapi.json をダウンロード
APIキー
ダッシュボードのAPIキーページでキーを作成・失効させることができます。
各キーはワークスペースに属し、プランのレート制限を引き継ぎます。
キーの失効は即座に反映されます。
権限（スコープ）
キーの作成時に、フルアクセスか、連携に必要な権限だけを付与してください。権限のないキーには403が返され、レスポンスにエラー insufficient_scope と required_scope が含まれます。
qr:read— QRコードの閲覧- QRコードとその画像、フォルダー、タグの一覧表示と閲覧。
qr:write— QRコードの管理- QRコードの作成（一括作成を含む）、編集、フォルダー間の移動、タグ付け、削除。
analytics:read— 分析データの閲覧- 各QRコードのスキャン統計とスキャンログ。
webhooks:manage— Webhookの管理- エンドポイントのイベント購読と購読解除（Zapier、Make）。
権限機能の導入前に作成されたキーは、引き続きフルアクセスを持ちます。フルアクセスには、今後追加される権限も含まれます。
コード例
curlコマンドをコピー＆ペーストしてすぐに開始できます。YOUR_API_KEY をAPIキーページで取得したキーに置き換えてください。
QRコード一覧の取得
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
QRコードの作成
QRのタイプとコンテンツを送信すると、サーバーがコードを生成して保存します。
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'画像のレンダリング
作成済みのPNGまたはSVGファイルを取得します（?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Webhookのサンプルペイロード
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}スキャン分析
GET /qr-codes/{id}/stats は、合計、ユニーク訪問者、上位の国、デバイス、ブラウザー、日別スキャン数を返します。GET /qr-codes/{id}/scans は、スキャンログを新しい順に1ページ50件（per_page は最大100）で返します。
どちらも from と to（2026-10-01 のような日付、または完全なタイムスタンプ）、および timezone（デフォルトは UTC）を受け付けます。時刻のない日付は、そのタイムゾーンでの1日全体を表します。
利用できるのはプランの履歴保存期間内のデータのみで、それより古いスキャンは削除されます。訪問者のIPアドレスとユーザーエージェントが返されることはありません。
期間を指定したスキャン統計
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
スキャンログ（2ページ目）
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
フォルダーとタグ
GET /folders と GET /tags は、ワークスペースのフォルダーとタグを一覧表示します。QRコードの作成・更新時に folder_id と tags（タグのスラッグ）を渡してください。folder_id null でコードはフォルダーから外れ、tags はタグ全体を置き換えます。
QRコード一覧は ?folder_id= または ?tag= で絞り込めます。
QRコードをフォルダーに移動してタグを付ける
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'一括作成
POST /qr-codes/bulk は、1回のリクエストで最大100個のQRコードを作成します。ダッシュボードのCSVインポートと同様に一括作成を含むプランが必要で、有効なQRコードの上限が適用されます。
各項目は個別に処理されます。レスポンスには全項目が、ステータス created（新しいコードを含む）または failed（error と errors を含む）とともに返されます。バッチ全体ではなく、失敗した項目だけを再送してください。
QRコードを2つ作成
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Webhookの購読（REST hooks）
Zapier、Make、独自のサービスから、APIでイベントを購読できます。url と events を指定して POST /webhooks を送信し、購読解除には DELETE /webhooks/{id} を使用します。これらはWebhookページで使われているものと同じエンドポイントです。
POST のレスポンスには secret が含まれ、一度だけ表示されます。X-Webhook-Signature ヘッダーの検証に使用してください。独自の secret（16文字以上）を送信しない場合は、自動で生成されます。
イベント：qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted。購読にはWebhookを含むプランが必要ですが、購読解除はいつでも可能です。1つのワークスペースに登録できるエンドポイントは最大25個です。
スキャンを購読
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'購読を解除
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhook
Webhookはイベントが発生した際、リアルタイムでエンドポイントへ通知を送信するため、ポーリングは不要です。
ダッシュボードのWebhookページでエンドポイントを設定します。
各配信は署名され、失敗した場合は指数バックオフで自動再試行されます。
スキャンイベントは、作成したQRコードがスキャンされた際に発火します。
配信ログで配信試行、ペイロード、レスポンスを確認できます。
配信完了を確認するために 2xx ステータスを返してください。それ以外のステータスは失敗として扱われます。
コンバージョン計測
コンバージョンがあれば、A/Bテストはスキャン数だけでなく、どの遷移先が注文や登録につながるかを判断できます。自動最適化をオンにすると、最もコンバージョンの高いバリアントにトラフィックが移ります。
訪問者がコンバージョン後に見るページ（注文確認、サンクスページ、完了ページ）にスクリプトを追加してください。どのドメインでも動作し、APIキーは不要です。
スニペット
<script src="https://qr-global.com/c.js" async></script>
- スキャンのたびに署名付きパラメーター qrg_v が遷移先URLに追加され、コンバージョンがQRコードとバリアントに紐づきます。
- スクリプトはトークンをファーストパーティCookieに30日間保存するため、訪問者が先に別のページを見てもコンバージョンは計測されます。
- 1回のスキャンは1回だけカウントされます。サンクスページを再読み込みしてもコンバージョンは増えません。
- http(s) のページにリダイレクトするQRコードで動作します。
エクスポート
エクスポートページから、QRコード、スキャン履歴、位置情報、アクティビティをCSVとして出力できます。
エクスポート機能はAPIキーではなくダッシュボードのセッションを使用します。ログインした状態で実行してください。
ヒントとよくあるエラー
- 401 Unauthorized — APIキーが未設定または無効です。X-Api-Keyヘッダーを確認してください。
- 403 Forbidden — キーに必要な権限がない（insufficient_scope）か、プランにその機能が含まれていません（api_access_required、bulk_not_available、webhooks_not_available）。
- 404 Not Found — リソースが存在しないか、別のワークスペースに属しています。
- 429 Too Many Requests — プランの1分あたりの上限に達しました。Retry-After ヘッダーに示された秒数だけ待ってください。
- 一部の機能（Webhookなど）はプランに依存します。エンドポイントが機能エラーを返した場合はアップグレードをご検討ください。
- まだWebhookの配信がありませんか？作成したQRコードをスキャンしてテストを発生させてください。
- 失敗したWebhook配信は自動再試行されます。配信ログから手動で再試行することも可能です。
- チームメンバーはワークスペース内で操作します。キーとデータはワークスペース所有者に紐付けられます。