> ## 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.

# QR コードの一括作成

> 最大 100 個の QR コードを一度に作成し、ZIP アーカイブでダウンロードします。

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

一括作成では、名前と URL のリストから、共通のデザインを持つ Website QR コードを作成します。処理はバックグラウンドで実行されます。開始して進捗をポーリングし、ZIP アーカイブをダウンロードします。

| メソッド | パス | 説明 |
| - | - | - |
| `GET` | `/api/v1/bulk-qr-creations` | [現在の一括作成を取得する](#現在の一括作成を取得する) |
| `POST` | `/api/v1/bulk-qr-creations` | [JSON から作成する](#json-から作成する) |
| `POST` | `/api/v1/bulk-qr-creations/csv` | [CSV ファイルから作成する](#csv-ファイルから作成する) |
| `GET` | `/api/v1/bulk-qr-creations/{id}` | [一括作成を取得する](#一括作成を取得する) |
| `DELETE` | `/api/v1/bulk-qr-creations/{id}` | [一括作成を中止する](#一括作成を中止する) |
| `GET` | `/api/v1/bulk-qr-creations/{id}/download` | [アーカイブをダウンロードする](#アーカイブをダウンロードする) |

## しくみ

**1. 一括作成を開始する**

[JSON から作成する](#json-から作成する) または [CSV ファイルから作成する](#csv-ファイルから作成する) で行を送ります。API は一括作成とその `id` を `202` で返します。

**2. 進捗をポーリングする**

`status` が `completed` または `failed` になるまで、数秒ごとに [一括作成を取得する](#一括作成を取得する) を呼び出します。

**3. アーカイブをダウンロードする**

`status` が `completed` になったら、[アーカイブをダウンロードする](#アーカイブをダウンロードする) を呼び出して、QR コードの画像の ZIP を取得します。

* **上限。** 1 回の一括作成につき最大 100 行です。
* **一度に 1 つ。** ワークスペースで実行できる一括作成は 1 つだけです。実行中に別の一括作成を開始すると、実行中のものが返ります。
* **冪等性。** すべてのリクエストに `idempotencyKey` が必要です。同じキーと同じボディでリクエストを繰り返すと、すでに開始された一括作成が返ります。同じキーを別のボディで使うと `422` が返ります。
* **行。** 各行には `name` と `url` が必要です。[行](#行) をご覧ください。
* **プラン。** 一括作成は Single QR プランでは利用できず、リクエストは `403 exceeded_limit` を返します。

## 行

* **名前。** QR コードのタイトルになります。前後の空白は除去され、40 文字に切り詰められます。重複する名前（大文字と小文字は区別しない）には番号が付きます：`Menu`、`Menu 2`、`Menu 3`。
* **URL。** リンク先になります。`example.com/menu` のように実在するドメインを持つ `http` または `https` のアドレスで、スペースを含まない必要があります。スキームのない URL には `https://` が付きます。
* **空の行。** 名前も URL もない行はスキップされます。どちらか一方だけの行は拒否されます。

すべての QR コードは、短縮リンクを持つ `website` QR コードです。[QR コードの種類](https://docs.getqr.com/ja/api/guides/qr-types.md) をご覧ください。

## ヘッダー

**Authorization** `string` *required*

`Bearer` の後に API キーを続けます。[認証](https://docs.getqr.com/ja/api/authentication.md) をご覧ください。

**Content-Type** `string`

[JSON から作成する](#json-から作成する) では `application/json`、[CSV ファイルから作成する](#csv-ファイルから作成する) では `multipart/form-data`。

## 一括作成オブジェクト

**id** `string`

一括作成の ID。例：`cm2k7x9qb0003ax8eb4f6gh2t`。

**status** `string`

`queued`、`processing`、`packaging`、`completed`。失敗した一括作成や中止された一括作成は、`rollingBack` を経て `failed` になります。

**sourceFilename** `string`

元ファイルの名前。

**totalCount** `integer`

行の数。

**createdCount** `integer`

これまでに作成された QR コードの数。

**renderedCount** `integer`

これまでにレンダリングされた QR コードの画像の数。

**percent** `integer`

全体の進捗（0〜100）。作成で最大 40、レンダリングで最大 90 まで進み、パッケージングは 95、`completed` は 100 です。

**stalled** `boolean`

実行中の一括作成が 2 分間進んでいない場合は `true`。ポーリングを続けてください。[一括作成を取得する](#一括作成を取得する) が、停滞した一括作成を再開します。

**error** `object | null`

`status` が `failed` の場合：`code` と `message`。中止された一括作成のコードは `cancelled_by_user` です。失敗した一括作成はロールバックされるため、その QR コードは 1 つも残りません。

**downloadUrl** `string | null`

`status` が `completed` になった後の、[アーカイブをダウンロードする](#アーカイブをダウンロードする) のパス。

**createdAt** `string`

開始日時（ISO 8601）。

**updatedAt** `string`

最終更新日時（ISO 8601）。

**completedAt** `string | null`

完了日時（ISO 8601）。

**failedAt** `string | null`

失敗日時（ISO 8601）。

## 現在の一括作成を取得する

`GET /api/v1/bulk-qr-creations`

ワークスペースで実行中の一括作成を返します。実行中のものがない場合は、最新の終了した一括作成（`completed` または `failed`）を、それが閉じられるまで返します。アーカイブのダウンロードか、ダッシュボードで閉じる操作によって閉じられます。それ以外の場合は `null` を返します。再起動後に追跡を再開するときに使います。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "processing",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:20.000Z",
  "completedAt": null,
  "failedAt": null
}
```

```json 200 (nothing to resume) theme={null}
null
```

## JSON から作成する

`POST /api/v1/bulk-qr-creations`

行のリストから一括作成を開始します。`202 Accepted` を返します。一括作成はバックグラウンドで実行されます。

**rows** `object[]` *required*

作成する QR コード。最大 100 個。各行は `{ "name": "...", "url": "..." }` で、他のフィールドは受け付けません。[行](#行) をご覧ください。

**design** `object` *required*

すべての QR コードに適用するデザイン：`styles`、`frameOptions`、`logoOptions`（すべて任意）。既定のデザインにするには `{}` を送ります。他のフィールドは拒否されます。[カスタマイズ](https://docs.getqr.com/ja/api/guides/customization.md) をご覧ください。

**sourceFilename** `string` *required*

ダッシュボードに表示され、アーカイブにも使われる名前。1〜255 文字。

**idempotencyKey** `string` *required*

この一括作成用の独自のキー。8〜100 文字。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      { "name": "Menu", "url": "https://example.com/menu" },
      { "name": "Wine list", "url": "example.com/wine" }
    ],
    "design": { "styles": { "dotsOptions": { "type": "rounded" } } },
    "sourceFilename": "campaign-links.csv",
    "idempotencyKey": "campaign-2026-08-14"
  }'
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## CSV ファイルから作成する

`POST /api/v1/bulk-qr-creations/csv`

[JSON から作成する](#json-から作成する) と同じですが、行を `multipart/form-data` で送る CSV ファイルとして受け取ります。`202 Accepted` を返します。

ファイルは 1,000,000 バイト以下の `.csv` である必要があります。ヘッダー行は正確に `name,url` で、その後に最大 100 行のデータ行が続きます。[CSV の形式](https://docs.getqr.com/ja/bulk/csv-format.md) をご覧ください。

**file** `file` *required*

CSV ファイル。

**design** `string` *required*

JSON としてシリアライズしたデザインオブジェクト。例：`{"styles":{"dotsOptions":{"type":"rounded"}}}`。既定のデザインにするには `{}` を送ります。

**idempotencyKey** `string` *required*

この一括作成用の独自のキー。8〜100 文字。

**sourceFilename** `string`

ダッシュボードに表示され、アーカイブにも使われる名前。最大 255 文字。既定値はアップロードしたファイルの名前です。

```bash cURL theme={null}
curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "file=@campaign-links.csv" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"
```

```csv campaign-links.csv theme={null}
name,url
Menu,https://example.com/menu
Wine list,example.com/wine
```

```json 202 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "queued",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 2,
  "createdCount": 0,
  "renderedCount": 0,
  "percent": 0,
  "stalled": false,
  "error": null,
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:00.000Z",
  "completedAt": null,
  "failedAt": null
}
```

## 一括作成を取得する

`GET /api/v1/bulk-qr-creations/{id}`

一括作成のステータスと進捗を返します。`status` が `queued`、`processing`、`packaging` の間はポーリングしてください。アーカイブの準備ができると `downloadUrl` が表示されます。

**id** `string` *required*

一括作成の ID。作成のレスポンスか、現在の一括作成のレスポンスから取得します。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "completed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 50,
  "renderedCount": 50,
  "percent": 100,
  "stalled": false,
  "error": null,
  "downloadUrl": "/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download",
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:02:10.000Z",
  "completedAt": "2026-08-14T08:02:10.000Z",
  "failedAt": null
}
```

## 一括作成を中止する

`DELETE /api/v1/bulk-qr-creations/{id}`

実行中の一括作成を停止し、すでに作成された QR コードを削除します。ロールバックはリクエストの処理中に行われるため、通常レスポンスの `status` は `failed`、`error.code` は `cancelled_by_user` になります。すでに失敗した一括作成を中止すると、変更されずにそのまま返ります。

> [!WARNING]
>
> 完了した一括作成は中止できず、リクエストは `400` を返します。代わりに、[QR コード](https://docs.getqr.com/ja/api/endpoints/qr-codes.md) でその QR コードを 1 つずつ削除してください。

**id** `string` *required*

一括作成の ID。

```bash cURL theme={null}
curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"
```

```json 200 theme={null}
{
  "id": "cm2k7x9qb0003ax8eb4f6gh2t",
  "status": "failed",
  "sourceFilename": "campaign-links.csv",
  "totalCount": 50,
  "createdCount": 18,
  "renderedCount": 12,
  "percent": 26,
  "stalled": false,
  "error": {
    "code": "cancelled_by_user",
    "message": "Bulk QR creation was cancelled."
  },
  "downloadUrl": null,
  "createdAt": "2026-08-14T08:00:00.000Z",
  "updatedAt": "2026-08-14T08:00:40.000Z",
  "completedAt": null,
  "failedAt": "2026-08-14T08:00:40.000Z"
}
```

## アーカイブをダウンロードする

`GET /api/v1/bulk-qr-creations/{id}/download`

QR コードごとに 1024 px の JPEG を 1 つずつ含む ZIP アーカイブを返します。ファイル名は行にちなんで `001-Menu.jpg`、`002-Wine list.jpg` のように付けられます。アーカイブの名前は `sourceFilename` にちなんで付けられます。`status` が `completed` になると利用できます。ダウンロードすると一括作成は閉じられ、[現在の一括作成を取得する](#現在の一括作成を取得する) で返されなくなります。

**id** `string` *required*

一括作成の ID。

```bash cURL theme={null}
curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip
```

```http 200 theme={null}
HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>
```

## よくある問題

> [accordion] "contains an invalid HTTP(S) URL" を含む 422
>
> メッセージに該当する行が示されます。各 URL は、`example.com/menu` のように実在するドメインを持つ `http` または `https` のアドレスである必要があります。行を修正して、リクエストをもう一度送ってください。

> [accordion] 422 "CSV headers must be exactly: name,url."
>
> CSV の 1 行目は、この順序の小文字で `name,url` とし、他の列は含めないでください。

> [accordion] 422 "This idempotencyKey was already used with a different request body."
>
> キーは別のバッチに再利用できません。新しい `idempotencyKey` を送ってください。

> [accordion] 409 "The bulk QR archive is not ready for download."
>
> 一括作成はまだ完了していません。`status` が `completed` になるまでポーリングを続けてください。

> [accordion] 400 "Cannot cancel a finished bulk QR creation."
>
> 一括作成はすでに完了しているため、ロールバックできません。

> [accordion] 403 exceeded\_limit
>
> ワークスペースが Single QR プランで、一括作成が含まれていません。プランをアップグレードしてください。

> [accordion] 新しい一括作成ではなく古い一括作成が返ってきた
>
> ワークスペースで別の一括作成がまだ実行中か、`idempotencyKey` を再利用しています。完了するまで待つか、新しいキーを使ってください。

## 次のステップ

> [card] [カスタマイズ](https://docs.getqr.com/ja/api/guides/customization.md)

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

> [card] [アプリでの一括作成](https://docs.getqr.com/ja/bulk/overview.md)

> [card] [CSV の形式](https://docs.getqr.com/ja/bulk/csv-format.md)


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