QR 코드 대량 생성

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

대량 생성은 이름과 URL 목록을 하나의 공통 디자인을 가진 Website QR 코드로 만듭니다. 작업은 백그라운드에서 실행됩니다. 시작하고, 진행 상황을 폴링한 다음, ZIP 아카이브를 다운로드하세요.

메서드	경로	설명
`GET`	`/api/v1/bulk-qr-creations`	현재 대량 생성 조회
`POST`	`/api/v1/bulk-qr-creations`	JSON으로 생성
`POST`	`/api/v1/bulk-qr-creations/csv`	CSV 파일로 생성
`GET`	`/api/v1/bulk-qr-creations/{id}`	대량 생성 조회
`DELETE`	`/api/v1/bulk-qr-creations/{id}`	대량 생성 중단
`GET`	`/api/v1/bulk-qr-creations/{id}/download`	아카이브 다운로드

작동 방식

대량 생성 시작

JSON으로 생성 또는 CSV 파일로 생성으로 행을 보냅니다. API는 대량 생성과 그 id를 담아 202를 반환합니다.

진행 상황 폴링

status가 completed 또는 failed가 될 때까지 몇 초마다 대량 생성 조회를 호출합니다.

아카이브 다운로드

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 코드 유형을 참조하세요.

헤더

string

필수

Bearer 뒤에 API 키를 붙입니다. 인증을 참조하세요.

string

JSON으로 생성에는 application/json, CSV 파일로 생성에는 multipart/form-data.

대량 생성 객체

string

대량 생성의 ID입니다. 예: cm2k7x9qb0003ax8eb4f6gh2t.

string

queued, processing, packaging, completed. 실패하거나 중단된 대량 생성은 rollingBack을 거쳐 failed가 됩니다.

string

원본 파일 이름입니다.

integer

행 수입니다.

integer

지금까지 만든 QR 코드 수입니다.

integer

지금까지 렌더링한 QR 코드 이미지 수입니다.

integer

전체 진행률(0~100)입니다. 생성은 최대 40, 렌더링은 최대 90까지이며, 패키징은 95, completed는 100입니다.

boolean

실행 중인 대량 생성이 2분 동안 진행되지 않으면 true입니다. 계속 폴링하세요. 대량 생성 조회가 멈춘 대량 생성을 다시 시작합니다.

object | null

status가 failed일 때의 code와 message입니다. 중단된 대량 생성의 코드는 cancelled_by_user입니다. 실패한 대량 생성은 롤백되므로 그 QR 코드는 하나도 남지 않습니다.

string | null

status가 completed가 되면 제공되는 아카이브 다운로드 경로입니다.

string

시작 일시(ISO 8601)입니다.

string

마지막 업데이트 일시(ISO 8601)입니다.

string | null

완료 일시(ISO 8601)입니다.

string | null

실패 일시(ISO 8601)입니다.

현재 대량 생성 조회

GET /api/v1/bulk-qr-creations 워크스페이스에서 아직 실행 중인 대량 생성을 반환합니다. 실행 중인 것이 없으면, 가장 최근에 끝난 대량 생성(completed 또는 failed)을 닫힐 때까지 반환합니다. 아카이브를 다운로드하거나 대시보드에서 닫으면 닫힙니다. 그 밖의 경우에는 null을 반환합니다. 다시 시작한 뒤 추적을 이어 갈 때 사용하세요.

curl "https://getqr.com/api/v1/bulk-qr-creations" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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
}

null

JSON으로 생성

POST /api/v1/bulk-qr-creations 행 목록으로 대량 생성을 시작합니다. 202 Accepted를 반환합니다. 대량 생성은 백그라운드에서 실행됩니다.

object[]

필수

만들 QR 코드로, 최대 100개입니다. 각 행은 { "name": "...", "url": "..." }이며 다른 필드는 받지 않습니다. 행을 참조하세요.

object

필수

모든 QR 코드에 적용할 디자인으로, styles, frameOptions, logoOptions이며 모두 선택 사항입니다. 기본 디자인을 사용하려면 {}를 보내세요. 다른 필드는 거부됩니다. 맞춤 설정을 참조하세요.

string

필수

대시보드에 표시되고 아카이브 이름에도 쓰이는 이름으로, 1~255자입니다.

string

필수

이 대량 생성에 대해 직접 정한 키로, 8~100자입니다.

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"
  }'

{
  "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으로 생성과 같지만, 행을 multipart/form-data로 보내는 CSV 파일로 받습니다. 202 Accepted를 반환합니다. 파일은 1,000,000바이트 이하의 .csv여야 합니다. 헤더 행은 정확히 name,url이어야 하며, 그 뒤에 데이터 행이 최대 100개까지 올 수 있습니다. CSV 형식을 참조하세요.

file

필수

CSV 파일입니다.

string

필수

JSON으로 직렬화한 디자인 객체입니다. 예: {"styles":{"dotsOptions":{"type":"rounded"}}}. 기본 디자인을 사용하려면 {}를 보내세요.

string

필수

이 대량 생성에 대해 직접 정한 키로, 8~100자입니다.

string

대시보드에 표시되고 아카이브 이름에도 쓰이는 이름으로, 최대 255자입니다. 기본값은 업로드한 파일의 이름입니다.

curl -X POST "https://getqr.com/api/v1/bulk-qr-creations/csv" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -F "[email protected]" \
  -F 'design={"styles":{"dotsOptions":{"type":"rounded"}}}' \
  -F "idempotencyKey=campaign-2026-08-14"

name,url
Menu,https://example.com/menu
Wine list,example.com/wine

{
  "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이 나타납니다.

string

필수

대량 생성의 ID입니다. 생성 응답이나 현재 대량 생성 조회 응답에서 가져오세요.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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입니다. 이미 실패한 대량 생성을 중단하면 변경 없이 그대로 반환합니다.

완료된 대량 생성은 중단할 수 없으며, 요청은 400을 반환합니다. 대신 QR 코드로 해당 QR 코드를 하나씩 삭제하세요.

string

필수

대량 생성의 ID입니다.

curl -X DELETE "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t" \
  -H "Authorization: Bearer $GETQR_API_KEY"

{
  "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가 되면 사용할 수 있습니다. 다운로드하면 대량 생성이 닫히므로 현재 대량 생성 조회에서 더 이상 반환되지 않습니다.

string

필수

대량 생성의 ID입니다.

curl "https://getqr.com/api/v1/bulk-qr-creations/cm2k7x9qb0003ax8eb4f6gh2t/download" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-codes.zip

HTTP/1.1 200 OK
Content-Type: application/zip
Content-Disposition: attachment; filename="campaign-links-qr-codes.zip"

<binary archive data>

자주 발생하는 문제

"contains an invalid HTTP(S) URL"이 포함된 422

메시지에 해당 행이 표시됩니다. 각 URL은 example.com/menu처럼 실제 도메인이 있는 http 또는 https 주소여야 합니다. 행을 수정한 뒤 요청을 다시 보내세요.

422 "CSV headers must be exactly: name,url."

CSV의 첫 행은 이 순서대로 소문자로 쓴 name,url이어야 하며, 다른 열이 없어야 합니다.

422 "This idempotencyKey was already used with a different request body."

키는 다른 배치에 다시 사용할 수 없습니다. 새 idempotencyKey를 보내세요.

409 "The bulk QR archive is not ready for download."

대량 생성이 아직 완료되지 않았습니다. status가 completed가 될 때까지 계속 폴링하세요.

400 "Cannot cancel a finished bulk QR creation."

대량 생성이 이미 완료되었으므로 롤백할 수 없습니다.

403 exceeded_limit

워크스페이스가 대량 생성이 포함되지 않은 Single QR 요금제를 사용 중입니다. 요금제를 업그레이드하세요.

새 대량 생성 대신 이전 대량 생성이 반환되었습니다

워크스페이스에서 다른 대량 생성이 아직 실행 중이거나, idempotencyKey를 다시 사용했습니다. 완료될 때까지 기다리거나 새 키를 사용하세요.

API

QR 코드 대량 생성

작동 방식

행

헤더

대량 생성 객체

현재 대량 생성 조회

JSON으로 생성

CSV 파일로 생성

대량 생성 조회

대량 생성 중단

아카이브 다운로드

자주 발생하는 문제

다음 단계

맞춤 설정

QR 코드

앱에서 대량 생성

CSV 형식

​작동 방식

​행

​헤더

​대량 생성 객체

​현재 대량 생성 조회

​JSON으로 생성

​CSV 파일로 생성

​대량 생성 조회

​대량 생성 중단

​아카이브 다운로드

​자주 발생하는 문제

​다음 단계

맞춤 설정

QR 코드

앱에서 대량 생성

CSV 형식

작동 방식

행

헤더

대량 생성 객체

현재 대량 생성 조회

JSON으로 생성

CSV 파일로 생성

대량 생성 조회

대량 생성 중단

아카이브 다운로드

자주 발생하는 문제

다음 단계