> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-clara.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# CSV 파일 준비
> Twenty로 가져오기 위한 데이터 형식 지정 단계별 가이드.
## 개요
이 가이드는 성공적인 가져오기를 위해 CSV 파일을 준비하는 과정을 안내합니다. 오류를 피하려면 다음 단계를 따르세요.
## 1단계: 파일 요구 사항 확인
시작하기 전에 파일이 다음 요구 사항을 충족하는지 확인하세요:
| 요구 사항 | 세부정보 |
| --------- | ---------------- |
| **형식** | CSV, XLSX 또는 XLS |
| **크기 제한** | 파일당 10,000 레코드 |
| **인코딩** | UTF-8 권장 |
| **구조** | 파일당 한 가지 오브젝트 유형 |
10,000 레코드를 초과하는 데이터세트의 경우, 여러 파일로 분할하거나 [API 가져오기](/l/ko/user-guide/data-migration/how-tos/import-data-via-api)를 사용하세요.
## 2단계: 샘플 파일 다운로드
**가장 중요한 단계입니다.** 샘플 파일은 Twenty가 기대하는 정확한 열 이름과 형식을 보여줍니다.
1. 오브젝트 보기(사람들, 회사 등)로 이동하세요.
2. **⋮** → **레코드 가져오기**를 클릭하세요
3. **샘플 파일 다운로드**를 클릭하세요
4. 이 파일을 템플릿으로 사용하세요
**전문가 팁:** 대신 기존 레코드 몇 개를 내보내세요. 이렇게 하면 데이터가 어떻게 형식화되어야 하는지 실제 예를 얻을 수 있으며, 가져오는 동안 열 이름이 자동으로 매핑됩니다.
## 3단계: 중복 값 제거
Twenty는 일부 필드에 대해 고유성을 적용합니다. 중복 항목은 가져오기 오류를 유발합니다.
| 객체 | 고유 필드 |
| ------------- | ----------------------- |
| **사람들** | `id`, `email` |
| **회사** | `id`, `domain` |
| **사용자 지정 개체** | `id`, 그리고 고유로 표시한 모든 필드 |
**가져오기 전에:**
1. 스프레드시트를 고유 필드(이메일 또는 도메인)로 정렬하세요
2. 중복 행을 제거하거나 병합하세요
3. Twenty에 이미 존재하는 중복 항목이 있는지 확인하세요
**소프트 삭제된 레코드는 고유성에 포함됩니다.** Command Menu → 삭제된 레코드 보기에 있는 레코드는 중복 오류를 일으킵니다. 영구적으로 삭제하거나 복원한 후 업데이트하세요.
## 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`
* `MM/DD/YYYY`: `03/15/2024`
* `DD/MM/YYYY`: `15/03/2024`
* ISO 8601: `2024-03-15T10:30:00Z`
### 숫자 필드
* 숫자만 사용(텍스트 금지)
* 소수점 구분 기호로 점(.)을 사용: `1234.56`
* 천 단위 구분 기호 사용 금지(`1,234.56`는 사용하지 마세요)
### 통화 필드
통화는 두 개의 열이 필요한 **중첩 필드**이며, **두 열 모두** 채워야 합니다:
| 열 | 예시 |
| --------------------- | --------- |
| **Amount / Amount** | `1234.56` |
| **Amount / Currency** | `USD` |
### 부울 필드
대문자 사용: `TRUE` 또는 `FALSE`
소문자 `true` 또는 `false`는 동작하지 않습니다.
### 선택 필드
표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요.
**API 이름을 찾는 방법:**
1. **설정 → 데이터 모델**로 이동
2. 객체와 필드를 선택하세요
3. **고급 모드**를 활성화하세요(오른쪽 하단 토글)
4. API 이름을 복사하세요(예: `OPTION_1`, "Option 1" 아님)
새 선택 옵션은 자동으로 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가하세요.
### 다중 선택 필드
배열 형식으로 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`을 모두 포함하지 마세요)
* 워크스페이스 구성원은 이름이 아닌 **이메일**을 사용하세요
**가져오기 순서가 중요합니다!**
"one" 측을 "many" 측보다 먼저 가져오세요:
1. **회사** 먼저
2. **연락처** 두 번째(회사 참조 포함)
3. **기회** 세 번째
참조하려면 상위 레코드가 먼저 존재해야 합니다.
자세한 지침은 [관계 가져오기 방법](/l/ko/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv)을 참조하세요.
## 6단계: Twenty에 필드가 존재하는지 확인
가져오기는 필드가 아니라 레코드를 생성합니다. 가져오려는 모든 필드는 데이터 모델에 이미 존재해야 합니다.
**가져오기 전:**
1. **설정 → 데이터 모델**로 이동
2. 객체를 선택하세요
3. 필요한 사용자 정의 필드를 생성하세요
4. 필드 이름을 정확히 확인하세요(열 제목과 일치해야 합니다)
## 7단계: 최종 체크리스트
파일을 업로드하기 전에 다음을 확인하세요:
파일 형식이 CSV, XLSX 또는 XLS이어야 합니다
레코드 수가 10,000개 미만이어야 합니다
인코딩이 UTF-8이어야 합니다
이메일(연락처) 또는 도메인(회사)에 중복이 없어야 합니다
날짜 형식이 전체에서 일관되어야 합니다
도메인은 `https://domain.com` 형식을 사용해야 합니다
부울 필드는 `TRUE` 또는 `FALSE`(대문자)를 사용해야 합니다
선택 필드는 표시 라벨이 아닌 API 이름을 사용해야 합니다
모든 사용자 정의 필드가 설정 → 데이터 모델에 존재해야 합니다
상위 레코드를 하위 레코드보다 먼저 가져와야 합니다
관계 열이 기존 레코드를 참조해야 합니다
## 피해야 할 일반적인 실수
| 실수 | 해결책 |
| -------------------- | ----------------------------------- |
| `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)