---
title: CSV 파일 준비
description: Twenty로 가져오기 위한 데이터 형식 지정 단계별 가이드.
---

## 개요

이 가이드는 성공적인 가져오기를 위해 CSV 파일을 준비하는 과정을 안내합니다. 오류를 피하려면 다음 단계를 따르세요.

## 1단계: 파일 요구 사항 확인

시작하기 전에 파일이 다음 요구 사항을 충족하는지 확인하세요:

| 요구 사항     | 세부정보             |
| --------- | ---------------- |
| **형식**    | CSV, XLSX 또는 XLS |
| **크기 제한** | 파일당 10,000 레코드   |
| **인코딩**   | UTF-8 권장         |
| **구조**    | 파일당 한 가지 오브젝트 유형 |

<Note>10,000 레코드를 초과하는 데이터세트의 경우, 여러 파일로 분할하거나 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요.</Note>

## 2단계: 샘플 파일 다운로드

**가장 중요한 단계입니다.** 샘플 파일은 Twenty가 기대하는 정확한 열 이름과 형식을 보여줍니다.

1. 오브젝트 보기(사람들, 회사 등)로 이동하세요.
2. **⋮** → **레코드 가져오기**를 클릭하세요
3. **샘플 파일 다운로드**를 클릭하세요
4. 이 파일을 템플릿으로 사용하세요

<Note>**전문가 팁:** 대신 기존 레코드 몇 개를 내보내세요. 이렇게 하면 데이터가 어떻게 형식화되어야 하는지 실제 예를 얻을 수 있으며, 가져오는 동안 열 이름이 자동으로 매핑됩니다.</Note>

## 3단계: 중복 값 제거

Twenty는 일부 필드에 대해 고유성을 적용합니다. 중복 항목은 가져오기 오류를 유발합니다.

| 객체            | 고유 필드                   |
| ------------- | ----------------------- |
| **사람들**       | `id`, `email`           |
| **회사**        | `id`, `domain`          |
| **사용자 지정 개체** | `id`, 그리고 고유로 표시한 모든 필드 |

**가져오기 전에:**

1. 스프레드시트를 고유 필드(이메일 또는 도메인)로 정렬하세요
2. 중복 행을 제거하거나 병합하세요
3. Twenty에 이미 존재하는 중복 항목이 있는지 확인하세요

<Warning>**소프트 삭제된 레코드는 고유성에 포함됩니다.** Command Menu → 삭제된 레코드 보기에 있는 레코드는 중복 오류를 일으킵니다. 영구적으로 삭제하거나 복원한 후 업데이트하세요.</Warning>

## 4단계: 각 필드 유형을 올바르게 형식 지정하기

필드 유형에 따라 요구되는 형식이 다릅니다. 전체 참고 자료는 다음과 같습니다:

### 텍스트 필드

* 특별한 형식 지정이 필요 없습니다
* 앞/뒤 공백은 자동으로 제거됩니다

### 이메일 필드

* 유효한 이메일 형식이어야 합니다: `name@domain.com`
* 고유해야 합니다(파일 또는 Twenty에 중복이 없어야 함)
* 추가 이메일의 경우 **Emails / Additional Emails** 열에서 다음 형식을 사용하세요:

```
["jane@twenty.com","jane.doe@twenty.com"]
```

### 도메인 필드

* **권장 형식**: `https://domain.com`
* 이는 메일박스/캘린더 동기화에서 사용하는 형식과 일치하며 중복을 방지합니다
* 두 열을 모두 채우세요:
  * **Domain / Domain Label**: `domain.com`
  * **Domain / Domain URL**: `https://domain.com`
* 파일 내 및 Twenty에서 고유해야 합니다

### 전화번호 필드

전화번호는 여러 열이 필요한 **중첩 필드**입니다:

| 열                                       | 예시           |
| --------------------------------------- | ------------ |
| **Phones / Primary Phone Number**       | `4159095555` |
| **Phones / Primary Phone Country Code** | `US`         |
| **Phones / Primary Phone Calling Code** | `+1`         |

### 주소 필드

Address는 여러 열로 구성된 **중첩 필드**이며(일부는 비워 둘 수 있음):

* **Address / Address 1**: 주소 1행
* **Address / Address 2**: 주소 2행(선택 사항)
* **Address / City**: 도시 이름
* **Address / State**: 주 또는 도
* **Address / Country**: 국가 이름
* **Address / Post Code**: 우편번호/ZIP 코드

### 날짜 필드

파일 전체에서 일관된 형식을 사용하세요:

* `YYYY-MM-DD` (권장): `2024-03-15`
* ISO 8601: `2024-03-15T10:30:00Z`

### 숫자 필드

* 숫자만 사용(텍스트 금지)
* 소수점 구분 기호로 점(.)을 사용: `1234.56`
* 천 단위 구분 기호 사용 금지(`1,234.56`는 사용하지 마세요)

### 통화 필드

통화는 두 개의 열이 필요한 **중첩 필드**이며, **두 열 모두** 채워야 합니다:

| 열                     | 예시        |
| --------------------- | --------- |
| **Amount / Amount**   | `1234.56` |
| **Amount / Currency** | `USD`     |

### 부울 필드

대문자 사용: `TRUE` 또는 `FALSE`

<Warning>소문자 `true` 또는 `false`는 동작하지 않습니다.</Warning>

### 선택 필드

표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요.

**API 이름을 찾는 방법:**

1. **설정 → 데이터 모델**로 이동
2. 객체와 필드를 선택하세요
3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
4. API 이름을 복사하세요(예: `OPTION_1`, "Option 1" 아님)

<Note>새 선택 옵션은 자동으로 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가하세요.</Note>

### 다중 선택 필드

배열 형식으로 API 이름을 사용:

```
["VALUE1","VALUE2"]
```

### 배열 필드

JSON 배열 형식 사용:

```
["value1","value2"]
```

### 평점 필드

다음 형식을 사용: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, 또는 `RATING_5`

### 링크/URL 필드

두 열을 모두 채우세요:

* **Links / Link Label**: `Twenty`
* **Links / Link URL**: `https://twenty.com`

보조 링크의 경우 **Links / Secondary Links** 열을 사용하세요:

```
[{"url":"https://twenty.com","label":"Twenty"}]
```

### JSON 필드

유효한 JSON 형식을 사용:

```
{"key":"value","key2":"value2"}
```

### ID 필드

* **선택 사항**: 제공하지 않으면 Twenty가 ID를 자동 생성합니다
* **형식**: UUID(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`)
* **사용 사례**: 새로 생성하는 대신 기존 레코드를 업데이트하려면 ID를 포함하세요

## 5단계: 관계 열 추가(레코드를 연결하는 경우)

레코드를 다른 객체에 연결하려면(예: People을 Companies에) 관련 레코드의 고유 식별자가 있는 열을 추가하세요.

**예시**: People을 Companies에 연결

People CSV에 열을 추가:

```
firstName,lastName,email,companyDomain
John,Smith,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,https://widgets.co
```

**관계에 대한 중요 규칙:**

* 상위 레코드는 Twenty에 이미 존재해야 합니다
* 라벨이 아니라 **도메인 URL** 형식(`https://domain.com`)을 사용하세요
* 고유 식별자는 하나만 매핑하세요(`companyId`와 `companyDomain`을 모두 포함하지 마세요)
* 워크스페이스 구성원은 이름이 아닌 **이메일**을 사용하세요

<Warning>
**가져오기 순서가 중요합니다!**

"one" 측을 "many" 측보다 먼저 가져오세요:
1. **회사** 먼저
2. **연락처** 두 번째(회사 참조 포함)
3. **기회** 세 번째

참조하려면 상위 레코드가 먼저 존재해야 합니다.
</Warning>

자세한 지침은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.

## 6단계: Twenty에 필드가 존재하는지 확인

가져오기는 필드가 아니라 레코드를 생성합니다. 가져오려는 모든 필드는 데이터 모델에 이미 존재해야 합니다.

**가져오기 전:**

1. **설정 → 데이터 모델**로 이동
2. 객체를 선택하세요
3. 필요한 사용자 정의 필드를 생성하세요
4. 필드 이름을 정확히 확인하세요(열 제목과 일치해야 합니다)

## 7단계: 최종 체크리스트

파일을 업로드하기 전에 다음을 확인하세요:

<Check>파일 형식이 CSV, XLSX 또는 XLS이어야 합니다</Check>
<Check>레코드 수가 10,000개 미만이어야 합니다</Check>
<Check>인코딩이 UTF-8이어야 합니다</Check>
<Check>이메일(연락처) 또는 도메인(회사)에 중복이 없어야 합니다</Check>
<Check>날짜 형식이 전체에서 일관되어야 합니다</Check>
<Check>도메인은 `https://domain.com` 형식을 사용해야 합니다</Check>
<Check>부울 필드는 `TRUE` 또는 `FALSE`(대문자)를 사용해야 합니다</Check>
<Check>선택 필드는 표시 라벨이 아닌 API 이름을 사용해야 합니다</Check>
<Check>모든 사용자 정의 필드가 설정 → 데이터 모델에 존재해야 합니다</Check>
<Check>상위 레코드를 하위 레코드보다 먼저 가져와야 합니다</Check>
<Check>관계 열이 기존 레코드를 참조해야 합니다</Check>

## 피해야 할 일반적인 실수

| 실수                   | 해결책                                 |
| -------------------- | ----------------------------------- |
| `TRUE` 대신 `true` 사용  | 부울 값은 대문자여야 합니다                     |
| 선택 필드에서 표시 라벨 사용     | 설정에서 API 이름을 찾아 사용하세요               |
| 회사보다 연락처를 먼저 가져오기    | 항상 상위 객체를 먼저 가져오세요                  |
| 통화 필드에 통화 코드 누락      | Amount와 Currency 열을 모두 채우세요         |
| 잘못된 도메인 형식           | `https://domain.com` 형식을 일관되게 사용하세요 |
| 관계에 여러 개의 고유 필드를 매핑함 | 하나만 매핑하세요(도메인 또는 ID, 둘 다는 안 됨)      |

## 다음 단계

파일이 준비되었습니다! 이제:

* [회사 가져오기](/l/ko/user-guide/data-migration/how-tos/import-companies-via-csv) (먼저 가져오세요)
* [연락처 가져오기](/l/ko/user-guide/data-migration/how-tos/import-contacts-via-csv)
* [가져오기 오류 수정](/l/ko/user-guide/data-migration/how-tos/fix-import-errors)