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

# CSV 형식

> 대량 생성용 CSV 파일 준비 방법: 필수 헤더, 행, URL 규칙 및 유효성 검사 오류를 안내합니다.

대량 생성은 간단한 CSV 파일을 읽습니다. 헤더 행 하나와, 이름과 대상 URL이 담긴 QR 코드당 한 행으로 구성됩니다. 이 페이지에서는 업로드할 때 GetQR이 확인하는 규칙을 설명합니다.

## 샘플 파일

```csv bulk-qr-template.csv theme={null}
name,url
Spring Menu,https://getqr.com/spring
Store #14,https://getqr.com/store-14
Table 7,example.com/menu?table=7
"Downtown, Main St",https://example.com/stores/downtown
```

앱에서도 이 시작 파일을 다운로드할 수 있습니다. **Add links** 단계에서 **Download CSV template**을 클릭하세요.

## 규칙

| 항목 | 규칙 |
| - | - |
| 파일 | `.csv` 파일이어야 합니다. Excel 및 기타 형식은 허용되지 않습니다. |
| 헤더 | 첫 번째 행은 정확히 `name,url`이어야 합니다. 소문자로, 이 순서대로, 다른 열 없이 작성하세요. |
| 행 | 비어 있지 않은 행 최대 100개. 빈 행은 무시됩니다. |
| `name` | 필수. QR 코드 이름이 됩니다. 최대 40자이며, 더 긴 이름은 40자로 잘립니다. |
| `url` | 필수. `http://` 또는 `https://`로 시작하는 웹 주소입니다. |

### URL 규칙

* 스킴을 생략하면 GetQR이 `https://`를 추가합니다. `example.com/menu`는 `https://example.com/menu`가 됩니다.
* 주소에는 `example.com`처럼 점이 포함된 실제 도메인이 있어야 합니다.
* 공백, 탭, 줄바꿈은 사용할 수 없습니다.
* 웹 링크만 사용할 수 있습니다. `mailto:`, `ftp://`, `javascript:` 및 일반 이메일 주소는 거부됩니다.

### 중복된 이름

이름이 고유하지 않아도 됩니다. 두 행의 이름이 같으면(대소문자 무시) GetQR이 반복되는 이름에 번호를 붙입니다: `Menu`, `Menu 2`, `Menu 3`.

### 쉼표와 따옴표

이름에 쉼표가 포함되어 있으면 `"Downtown, Main St"`처럼 큰따옴표로 감싸세요. 스프레드시트 앱은 CSV로 저장할 때 이를 자동으로 처리합니다.

## 스프레드시트에서 파일 만들기

**1. 열 두 개 설정**

첫 번째 행의 A열에 `name`, B열에 `url`을 입력합니다.

**2. 코드당 한 행 추가**

각 행에 이름과 링크를 입력합니다. 최대 100행까지 입력할 수 있습니다.

**3. CSV로 저장**

시트를 CSV로 내보내거나 저장합니다. Excel에서는 **CSV UTF-8**을 선택합니다. Google Sheets에서는 **File > Download > Comma-separated values**를 선택합니다.

> [!TIP]
>
> UTF-8로 저장하면 이름에 포함된 한글, 악센트 문자 등 영어 이외의 문자가 그대로 유지됩니다.

## 유효성 검사 오류

### 파일 오류

이 오류가 발생하면 파일 전체가 처리되지 않습니다. 파일을 수정한 후 다시 업로드하세요.

| 메시지 | 해결 방법 |
| - | - |
| Choose a CSV file. Other file types are not supported. | 파일을 `.xlsx`나 `.numbers`가 아닌 `.csv`로 저장하세요. |
| The CSV header must be exactly name,url in that order. | 첫 번째 행을 정확히 `name,url`로 만드세요. 대문자, 추가 열 또는 헤더 누락 여부를 확인하세요. |
| Add at least one non-empty data row to the CSV. | 파일에 헤더만 있고 행이 없습니다. 이름과 링크를 하나 이상 추가하세요. |
| A CSV can contain at most 100 non-empty rows. | 목록을 최대 100행씩 여러 파일로 나누세요. |
| This CSV is malformed and could not be read. | 스프레드시트 앱에서 파일을 다시 내보내세요. 닫히지 않은 따옴표가 있는지 확인하세요. |

### 행 오류

이 오류는 개별 행에 표시됩니다. 수정 후 다시 업로드하거나, 유효한 행만으로 계속 진행할 수 있습니다.

| 배지 또는 메시지 | 원인 |
| - | - |
| **MISSING** / Name is required | `name` 셀이 비어 있습니다. |
| **MISSING** / URL is required | `url` 셀이 비어 있습니다. |
| **INVALID** / Enter a valid HTTP(S) URL | 링크가 [URL 규칙](#url-rules) 중 하나를 위반합니다. |

행 번호는 헤더를 1행으로 계산하므로, 첫 번째 데이터 행은 스프레드시트와 마찬가지로 2행입니다.

## 자주 발생하는 문제

> **헤더가 올바른 것 같은데도 헤더 오류가 발생합니다**
>
> 헤더는 소문자여야 하며 열이 두 개만 있어야 합니다. `Name,URL`이나 `name,url,notes`는 실패합니다. 스프레드시트에서 `url` 오른쪽에 빈 열이 있는지도 확인하세요.

> **브라우저에서 작동하는 링크가 INVALID로 표시됩니다**
>
> 링크에 공백이 있거나 http 또는 https 이외의 스킴을 사용하고 있을 수 있습니다. 공백을 `%20`으로 인코딩하거나 제거하고, 전체 웹 주소를 사용하세요.

> **일부 이름이 짧아졌습니다**
>
> 40자를 초과하는 이름은 40자로 잘립니다. 원하는 문구로 정하려면 파일에서 직접 이름을 줄이세요.

## 다음 단계

> **[CSV로 QR 코드 만들기](/ko/bulk/create-from-csv)**
>
> 파일을 업로드하고 배치를 시작하세요.

> **[대량 생성 개요](/ko/bulk/overview)**
>
> 제한 사항과 대량 생성의 작동 방식을 알아보세요.


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