> ## 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/ko/api/endpoints/qr-codes.md)
>
> QR 코드를 생성, 목록 조회, 업데이트, 일시 중지, 복제, 삭제, 다운로드합니다.

> [card] [분석](https://docs.getqr.com/ko/api/endpoints/analytics.md)
>
> QR 코드 하나 또는 워크스페이스 전체의 스캔 합계와 세부 분류를 조회합니다.

> [card] [보고서](https://docs.getqr.com/ko/api/endpoints/reports.md)
>
> 일회성 보고서를 내보내거나 정기 보고서 이메일을 예약합니다.

> [card] [템플릿](https://docs.getqr.com/ko/api/endpoints/templates.md)
>
> 디자인을 저장하고 새 QR 코드에 적용합니다.

> [card] [QR 코드 대량 생성](https://docs.getqr.com/ko/api/endpoints/bulk-qr-creations.md)
>
> JSON 또는 CSV 파일로 QR 코드를 한 번에 최대 100개까지 만듭니다.

> [card] [파일](https://docs.getqr.com/ko/api/endpoints/files.md)
>
> QR 코드에 사용할 PDF, 이미지, 동영상, 로고를 업로드합니다.

> [card] [상태 확인](https://docs.getqr.com/ko/api/endpoints/health.md)
>
> API가 작동 중인지 확인합니다. API 키가 필요 없습니다.

## 가이드

> [card] [QR 코드 유형](https://docs.getqr.com/ko/api/guides/qr-types.md)
>
> 16가지 QR 코드 유형별 데이터 형식.

> [card] [맞춤 설정](https://docs.getqr.com/ko/api/guides/customization.md)
>
> 점 스타일, 모서리, 색상, 프레임, 로고.

> [card] [접근 규칙](https://docs.getqr.com/ko/api/guides/access-rules.md)
>
> 일정, 스캔 제한, 비밀번호, 일시 중지, 삭제.

## 기본 URL

모든 엔드포인트는 하나의 기본 URL 아래에 있습니다.

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

## 버전 관리

API 버전은 경로에 포함됩니다. 모든 엔드포인트는 `/api/v1/` 아래에 있습니다.

* 호환성이 깨지는 변경은 `/api/v2/` 같은 새 버전 접두사로 제공되며, `/api/v1/`은 계속 작동합니다.
* 새로운 선택 필드나 새 엔드포인트 같은 추가 변경은 v1 안에서 이루어질 수 있습니다. 코드가 인식하지 못하는 응답 필드는 무시하세요.

## 빠른 시작

**1. API 키 받기**

계정 설정에서 키를 생성하거나 확인합니다. [인증](https://docs.getqr.com/ko/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/ko/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` 엔드포인트는 보낸 필드만 변경합니다.
* **민감한 정보.** 응답에는 비밀번호나 내부 식별자가 포함되지 않습니다. 비밀번호로 보호된 QR 코드는 `passwordProtected: true`만 반환합니다.
* **워크스페이스.** 모든 요청은 API 키가 속한 워크스페이스에서 실행됩니다. 워크스페이스 ID를 전달할 필요가 없습니다. [접근 권한 및 역할](https://docs.getqr.com/ko/api/authentication.md#접근-권한-및-역할)을 참조하세요.
* **오류.** 실패한 요청은 고정된 `code`가 담긴 `error` 객체를 반환합니다. [오류](https://docs.getqr.com/ko/api/errors.md)를 참조하세요.

## 페이지네이션

목록 엔드포인트(QR 코드, 템플릿, 예약 보고서)는 두 개의 쿼리 매개변수를 받습니다.

| 매개변수 | 설명 |
| - | - |
| `page` | 반환할 페이지입니다. 기본값은 `1`입니다. |
| `pageSize` | 페이지당 결과 수로, 최대 `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/ko/api/errors#유효성-검사-오류)를 반환합니다.

## 멱등성

네트워크 오류가 발생하면 요청이 처리되었는지 알 수 없을 때가 있습니다. [QR 코드 생성](https://docs.getqr.com/ko/api/endpoints/qr-codes.md#qr-코드-생성)을 안전하게 재시도하려면 직접 정한 고유한 값을 담아 `Idempotency-Key` 헤더를 보내세요.

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

* 24시간 안에 같은 키로 요청을 반복하면 두 번째 QR 코드를 만들지 않고 원래 응답을 반환합니다.
* 응답 헤더 `x-idempotent-replay`는 재생된 응답에서는 `true`, 새 응답에서는 `false`입니다.
* 해당 키의 첫 번째 요청이 아직 처리 중이면 API는 `409 conflict`를 반환합니다. 처리가 끝난 뒤 다시 시도하세요.
* 같은 키를 다른 요청 본문과 함께 다시 사용하면 `422 unprocessable_entity`를 반환합니다.
* 헤더가 없으면 30초 안에 보낸 동일한 요청 본문은 중복으로 처리됩니다.

대량 생성에서는 대신 요청 본문의 `idempotencyKey` 필드를 사용합니다. [QR 코드 대량 생성](https://docs.getqr.com/ko/api/endpoints/bulk-qr-creations.md)을 참조하세요.

## 요청 한도

API 키마다 분당 최대 600개의 요청을 보낼 수 있습니다. [요청 한도](https://docs.getqr.com/ko/api/rate-limits.md)를 참조하세요.

## 추후 제공 예정

인쇄용 패키지는 이후 릴리스에서 제공될 예정입니다.

## 다음 단계

> [card] [인증](https://docs.getqr.com/ko/api/authentication.md)

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


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