Abundera QR Pro API

はじめに

Abundera QR Pro API を使うと、ダイナミック QR コードをプログラムで作成・編集・分析できます。ダッシュボードで行う操作をすべて自動化可能です。チーム管理、請求、アカウントフローはダッシュボード UI で行います。この API は開発者向けのコード操作に限定されています。

ベース URL: https://pro.qr.abundera.ai/api

リクエスト形式: POST / PATCH / DELETE では JSON (Content-Type: application/json)。

レスポンス形式: JSON (application/json; charset=utf-8)。

利用条件: API アクセスは Business 以上のプランが必要です。Solo プランはダッシュボードは使えますが API は利用できません。

認証

すべてのリクエストに Bearer トークンとして API キーを付与します:

Authorization: Bearer abnd_qrpro_...

キーの作成・失効は /account/keys（Business、Team、Agency プラン）で行います。生の abnd_qrpro_... トークンは作成時に一度だけ表示されます。すぐに保存してください。保存するのは SHA-256 ハッシュのみで、紛失したキーを復元する手段はありません。

未認証リクエストは 401 { "error": "not_signed_in" } を返します。無効または失効済みのキーは 401 { "error": "invalid_api_key" } を返します。

API キーは作成したユーザーにスコープされます。そのユーザーがチームのメンバーである場合、以下のエンドポイントはチームのコードを自動的に対象にします（現在のチームコンテキストはユーザーアカウントに保存され、ダッシュボードから管理します）。

レート制限

API キーごとに適用されます。すべてのレスポンスに X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset（ウィンドウがリセットされる Unix 秒）が含まれます。

予算超過のリクエストは 429 { "error": "rate_limited", "window": "day", "retry_at": 1234567890 } と、秒単位の Retry-After ヘッダーを返します。

スキャンにはレート制限がありません, リダイレクトのホットパス（aqr.net/{shortcode}）は認証不要でスキャンごとの予算もありません。各プランには明示的な月間スキャン上限があります（10万 / 100万 / 1000万 / 3000万）。上限を超えてもリダイレクトは引き続き機能します。アップグレードするか一時的なスパイクとして対処するかを判断できるようメールでお知らせします。1日あたり約 1,000 万スキャンを超えるご予定の方は、メールで事前にキャパシティ調整をご相談ください。

エラー

すべてのエラーレスポンスは、機械可読な error コードと、該当する場合は追加情報を含む JSON です:

{ "error": "plan_limit", "plan": "business", "limit": 500, "current": 500 }

コード

ダイナミック QR コード: aqr.net/{shortcode} 経由でリダイレクトする 7 文字の Base58 ショートコード。各コードにはダッシュボードからダウンロードできる静的バックアップ QR が付属します。支払いを停止しても、静的版は私たちのリダイレクトを経由せずに直接 URL に解決します。

GET /api/codes

現在のスコープ（個人、または現在操作しているチーム）のすべてのコードを一覧表示します。コードごとに 30 日間のスキャン集計を含む配列を返します。

$ curl -H "Authorization: Bearer abnd_qrpro_..."        https://pro.qr.abundera.ai/api/codes

{
  "codes": [
    { "id": "uuid", "shortcode": "aBc123x",
      "url": "https://example.com/landing",
      "label": "Q2 campaign", "tags": "q2,print",
      "status": "active", "scans_30d": 1245,
      "created_at": 1713288000, "updated_at": 1713370000 }
  ],
  "plan": "business",
  "plan_limit": 500,
  "scope": { "type": "user" }
}

POST /api/codes

新しいダイナミックコードを作成します。挿入前にプランのアクティブ+一時停止コード上限を確認します。最小限のボディ:

{ "url": "https://example.com/landing" }

フルカスタマイズ（すべてオプション）:

{ "url":          "https://example.com/landing",
  "label":        "Spring campaign",
  "tags":         "q2,print",
  "qr_type":      "url",
  "style_json":   "{...}",
  "logo_key":     "instagram",
  "frame_style":  "scan-me",
  "frame_text":   "SCAN ME" }

201 と、生成された shortcode および印刷用 short_url を含む作成済み行を返します。

GET /api/codes/{id}

単一コードを取得します。スコープ内にない場合は 404。

PATCH /api/codes/{id}

変更可能なフィールドを更新します。最もよくある使い方: 印刷済みコードの転送先 URL を変更する。

$ curl -X PATCH        -H "Authorization: Bearer abnd_qrpro_..."        -H "Content-Type: application/json"        -d '{"url":"https://example.com/new-landing"}'        https://pro.qr.abundera.ai/api/codes/uuid

変更は数秒以内にリダイレクトに反映されます。PATCH で有効な status 値: "active"、"paused"。削除する場合は DELETE を使用してください。

DELETE /api/codes/{id}

ソフトデリート。grace_until = now + 90 days で status=grace に移行します。グレース期間中、リダイレクトは引き続き機能します, これがロックインなし価格の具体的な約束です。90 日後にコードは expired になり、リダイレクトは 410 Gone を返します。

POST /api/codes/import

配列ペイロードから一括作成します（qr.abundera.ai の「Pro に保存」フローでも使用されます）。単一コードのペイロードまたは配列を受け付けます。プラン制限はバッチ前に一度だけ確認されます。

アナリティクス

GET /api/codes/{id}/analytics

クエリパラメータ:

• range=7d|30d|90d|1y|3y, プランの保持期間上限（Solo 1年、Business 2年、Team/Agency 3年）でキャップされます。
• granularity=day|hour, 時間単位は Team と Agency のみ。時間単位の場合は最大 7 日間のウィンドウ。

{
  "range": "30d", "days": 30, "granularity": "day",
  "total": 4321,
  "timeseries": [
    { "bucket": "2026-04-01", "scans": 142 },
    { "bucket": "2026-04-02", "scans": 178 },
    ...
  ],
  "by_country": [
    { "key": "US", "total": 3012 },
    { "key": "CA", "total": 402 },
    { "key": "Other", "total": 108 }
  ],
  "by_device":  [
    { "key": "mobile",  "total": 3850 },
    { "key": "tablet",  "total": 312 },
    { "key": "desktop", "total": 159 }
  ]
}

ウィンドウ内のスキャン数が 5 未満の国は、プライバシー保護のため "Other" にまとめられます（プライバシーモデルを参照）。

API キー

キーの作成・失効は /account/keys ダッシュボードページで行います。API 経由のセルフ管理は読み取り専用です, キーの一覧表示と失効はできますが、新しいキーの作成にはダッシュボードが必要です（鶏と卵の問題: キーを作るにはキーが必要）。

GET /api/keys

API キーを一覧表示します。生のトークンは返しません, メタデータのみ。

{
  "keys": [
    { "id": "uuid", "label": "Production server",
      "created_at": 1713288000, "last_used_at": 1713370000 }
  ],
  "allowed": true,
  "plan": "business"
}

DELETE /api/keys/{id}

失効させます。キーは即座に無効化され、以降そのキーを含むリクエストはすべて 401 invalid_api_key を返します。

データエクスポート

GET /api/user/export

完全なデータセットを含む ZIP をダウンロードします, codes.csv（グレース・期限切れを含む全コード）、scans.csv（日次集計）、フォーマットを説明した README.txt。アーカイブは application/zip で返されます。ファイルにパイプしてください:

$ curl -H "Authorization: Bearer abnd_qrpro_..."        -o abundera-qr-export.zip        https://pro.qr.abundera.ai/api/user/export

どこにでも再インポートできます。データを所有するかぎりベンダーロックインは発生しません。

プライバシーモデル

スキャン集計がプライバシーの全体像です。リダイレクトホットパスでスキャンごとに保存するもの:

• code_id, どのコードがスキャンされたか
• day_bucket, UTC 日付（YYYY-MM-DD）。返される集計に日以下の精度はありません。
• country, Cloudflare の CF-IPCountry ヘッダーによる ISO-3166-1 alpha-2。都市・地域・GeoIP ルックアップなし。
• device_type, 短い User-Agent 正規表現で分類した mobile / tablet / desktop / unknown。生の UA 文字列は分類後すぐに破棄します。
• scan_count, 集計カウンター。ヒットごとにアップサートします。

保存しないもの: IP アドレス（ハッシュ化も含む）、生の User-Agent 文字列、都市レベルの位置情報、日以下のタイムスタンプ、リファラー、Cookie、リターゲティングピクセル、個人を特定できるあらゆる情報。5 件未満の小規模集計は再識別防止のためノイズフロアを設けています。

Team と Agency プランは、さらに hour_bucket（YYYY-MM-DD-HH UTC）を持つ並列時間別集計を書き込みます。同じプライバシーモデルです, 時間より細かいタイムスタンプなし、同じノイズフロア、個別スキャナーデータなし。

詳細: 無料ツールサイトの /manifesto/ と /no-lock-in/。