> ## 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 코드 대량 생성

> QR 코드를 한 번에 최대 100개까지 만들고 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을 받습니다.

* **한도.** 대량 생성 한 번에 최대 100행입니다.
* **한 번에 하나.** 워크스페이스마다 대량 생성은 하나만 실행됩니다. 실행 중에 다른 대량 생성을 시작하면 실행 중인 것을 반환합니다.
* **멱등성.** 모든 요청에는 `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/ko/api/guides/qr-types.md)을 참조하세요.

## 헤더

**Authorization** `string` *required*

`Bearer` 뒤에 API 키를 붙입니다. [인증](https://docs.getqr.com/ko/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 코드는 하나도 남지 않습니다.

**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/ko/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/ko/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/ko/api/endpoints/qr-codes.md)로 해당 QR 코드를 하나씩 삭제하세요.

**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 하나씩을 담은 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의 첫 행은 이 순서대로 소문자로 쓴 `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/ko/api/guides/customization.md)

> [card] [QR 코드](https://docs.getqr.com/ko/api/endpoints/qr-codes.md)

> [card] [앱에서 대량 생성](https://docs.getqr.com/ko/bulk/overview.md)

> [card] [CSV 형식](https://docs.getqr.com/ko/bulk/csv-format.md)


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