> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API の概要

> QR コード、テンプレート、分析、レポートを自分のコードから管理できます。

> [!NOTE]
>
> GetQR API はベータ版で、一部のワークスペースでのみご利用いただけます。正式リリースまでに内容が変更される場合があります。

GetQR API は、ダッシュボードで行う操作のための REST API です。QR コードの作成と更新、画像のダウンロード、スキャン分析の取得、レポートのエクスポートができます。アカウントの API キーで認証し、`/api/v1` 配下のバージョン付きエンドポイントを呼び出します。

## できること

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)
>
> QR コードの作成、一覧表示、更新、一時停止、複製、削除、ダウンロードができます。

> [card] [分析](https://docs.getqr.com/ja/api/endpoints/analytics.md)
>
> 1 つの QR コードまたはワークスペース全体のスキャン合計と内訳を取得できます。

> [card] [レポート](https://docs.getqr.com/ja/api/endpoints/reports.md)
>
> 単発のレポートをエクスポートしたり、定期的なレポートメールを予約したりできます。

> [card] [テンプレート](https://docs.getqr.com/ja/api/endpoints/templates.md)
>
> デザインを保存し、新しい QR コードに適用できます。

> [card] [QR コードの一括作成](https://docs.getqr.com/ja/api/endpoints/bulk-qr-creations.md)
>
> JSON または CSV ファイルから、最大 100 個の QR コードを一度に作成できます。

> [card] [ファイル](https://docs.getqr.com/ja/api/endpoints/files.md)
>
> QR コードで使う PDF、画像、動画、ロゴをアップロードできます。

> [card] [ヘルスチェック](https://docs.getqr.com/ja/api/endpoints/health.md)
>
> API が稼働しているかを確認できます。API キーは不要です。

## ガイド

> [card] [QR コードの種類](https://docs.getqr.com/ja/api/guides/qr-types.md)
>
> 16 種類の QR コードそれぞれのデータ形式。

> [card] [カスタマイズ](https://docs.getqr.com/ja/api/guides/customization.md)
>
> ドットのスタイル、コーナー、色、フレーム、ロゴ。

> [card] [アクセスルール](https://docs.getqr.com/ja/api/guides/access-rules.md)
>
> スケジュール、スキャン上限、パスワード、一時停止、削除。

## ベース URL

すべてのエンドポイントは 1 つのベース URL の下にあります。

```text theme={null}
https://getqr.com/api/v1
```

## バージョン管理

API のバージョンはパスに含まれます。すべてのエンドポイントは `/api/v1/` の下にあります。

* 互換性のない変更は、`/api/v2/` のような新しいバージョンのプレフィックスで公開されます。`/api/v1/` はそのまま使い続けられます。
* 新しい任意フィールドや新しいエンドポイントなどの追加的な変更は、v1 の中で行われることがあります。コードが認識しないレスポンスフィールドは無視してください。

## クイックスタート

**1. API キーを取得する**

アカウント設定でキーを生成または表示します。[認証](https://docs.getqr.com/ja/api/authentication.md) をご覧ください。

**2. API に接続できるか確認する**

```bash theme={null}
curl https://getqr.com/api/v1/health
```

レスポンスは `{ "status": "ok", "version": "v1" }` です。

**3. 最初の QR コードを作成する**

```bash theme={null}
curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'
```

API は `201` で新しい QR コードを返します。`id` と `shortLink` も含まれます。

**4. 画像をダウンロードする**

```bash theme={null}
curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png
```

## リクエストとレスポンス

* **形式。** リクエストボディは `Content-Type: application/json` を付けて JSON で送ります。例外は [一括作成](https://docs.getqr.com/ja/api/endpoints/bulk-qr-creations.md) の CSV アップロードで、`multipart/form-data` を使います。
* **レスポンス。** レスポンスは JSON です。QR コードの画像や一括作成の ZIP アーカイブなどのダウンロードでは、ファイルそのものが返ります。
* **日時。** 日時は UTC の ISO 8601 文字列です。例：`2026-08-01T10:00:00.000Z`。
* **クエリパラメータ。** ブール値のパラメータには文字列 `true` または `false` を指定します。
* **部分更新。** `PATCH` エンドポイントは、送ったフィールドだけを変更します。
* **機密情報。** レスポンスにパスワードや内部 ID が含まれることはありません。パスワード保護された QR コードは `passwordProtected: true` だけを返します。
* **ワークスペース。** すべてのリクエストは、API キーが属するワークスペースで実行されます。ワークスペース ID を渡す必要はありません。[アクセスと役割](https://docs.getqr.com/ja/api/authentication.md#アクセスと役割) をご覧ください。
* **エラー。** 失敗したリクエストは、安定した `code` を持つ `error` オブジェクトを返します。[エラー](https://docs.getqr.com/ja/api/errors.md) をご覧ください。

## ページネーション

一覧を返すエンドポイント（QR コード、テンプレート、定期レポート）は、2 つのクエリパラメータを受け付けます。

| パラメータ | 説明 |
| - | - |
| `page` | 返すページ。既定値は `1` です。 |
| `pageSize` | 1 ページあたりの件数。最大 `100`。既定値は `100` です。 |

レスポンスは `data` 配列と `pagination` オブジェクトです。

```json theme={null}
{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}
```

| フィールド | 説明 |
| - | - |
| `page` | 受け取ったページ。 |
| `pageSize` | 受け取ったページのサイズ。 |
| `total` | 全ページを合わせた件数。 |
| `hasMore` | 次のページがある間は `true`。 |

`hasMore` が `true` の間は、次のページをリクエストしてください。`pageSize` が `100` を超えると [`422`](https://docs.getqr.com/ja/api/errors#バリデーションエラー) が返ります。

## 冪等性

ネットワークエラーが起きると、リクエストが処理されたかどうかわからなくなることがあります。[QR コードの作成](https://docs.getqr.com/ja/api/endpoints/qr-codes.md#qr-コードを作成する) を安全に再試行するには、任意の一意な値を付けた `Idempotency-Key` ヘッダーを送ります。

```bash theme={null}
-H "Idempotency-Key: order-4821-qr"
```

* 24 時間以内に同じキーでリクエストを繰り返すと、2 つ目の QR コードは作成されず、最初のレスポンスが返ります。
* レスポンスヘッダー `x-idempotent-replay` は、再送されたレスポンスでは `true`、新しいレスポンスでは `false` になります。
* そのキーの最初のリクエストがまだ処理中の場合、API は `409 conflict` を返します。処理が終わってから再試行してください。
* 同じキーを別のリクエストボディで使うと `422 unprocessable_entity` が返ります。
* ヘッダーがない場合、30 秒以内に送られた同一のリクエストボディは重複として扱われます。

一括作成では、代わりにリクエストボディの `idempotencyKey` フィールドを使います。[QR コードの一括作成](https://docs.getqr.com/ja/api/endpoints/bulk-qr-creations.md) をご覧ください。

## レート制限

API キーごとに、1 分あたり最大 600 件のリクエストを送れます。[レート制限](https://docs.getqr.com/ja/api/rate-limits.md) をご覧ください。

## 今後追加予定

印刷用パックは今後のリリースで提供予定です。

## 次のステップ

> [card] [認証](https://docs.getqr.com/ja/api/authentication.md)

> [card] [QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.