> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/catalog/manage.md).

# 카탈로그 관리하기

이 페이지는 이미 만든 카탈로그를 최신 상태로 유지하는 방법을 다룹니다. 신상품을 붙이고, 가격·재고를 갱신하고, 단종 상품을 정리하고, 필드를 늘리거나 카탈로그 자체를 삭제하는 일이 여기에 해당합니다.

카탈로그를 처음 만드는 방법은 카탈로그 만들기, 메시지에서 쓰는 방법은 메시지에서 카탈로그 사용하기를 참고하세요.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fnytt37I9evXaIN0mY4pr%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%206.53.43.png?alt=media&amp;token=afc53587-0c2d-42c1-ba98-facaf660e0af" alt=""><figcaption><p>카탈로그 상세화면</p></figcaption></figure>

## 아이템 편집하기 <a href="#undefined" id="undefined"></a>

아이템은 하나씩 고칠 수도 있고 CSV로 한 번에 바꿀 수도 있습니다. 몇 개만 급하게 고칠 때는 직접 수정, 그 외에는 CSV가 빠르고 실수도 적습니다. **아이템 탭 > 아이템 편집** 버튼에서 시작합니다.

### **직접 추가하기**

* 아이템 추가: 아이템 편집 > 직접 추가하기 → 필드 값 입력 → 저장하기.\
  \* `id`는 필수이며 중복될 수 없습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fs4lJlKR4m8qyQYyLdUOJ%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.27.35.png?alt=media&amp;token=b3020ad1-a2c4-41b2-9155-753b18a3a9ad" alt=""><figcaption></figcaption></figure>

#### **목록에서 직접 수정하기**

* 목록에서 바꿀 값을 더블 클릭하여 값을 직접 수정할 수 있습니다.
* 수정 후 상단의 \[저장하기]를 눌러 변경사항을 저장합니다.\
  \* `id`는 수정할 수 없습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FTGt58IwYx0MxAhExM7Dp%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-22%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.01.06.png?alt=media&amp;token=cf41b820-fd72-4f4b-a11a-39a430c2c079" alt=""><figcaption><p>목록에서 직접 수정하기</p></figcaption></figure>

* 아이템 삭제: 목록 왼쪽 체크박스로 선택한 뒤 삭제합니다.

### CSV 업로드

**아이템 편집 > CSV 업로드**를 누르면 먼저 업로드 방식을 고릅니다. CSV의 `id`가 카탈로그에 이미 있는지에 따라 동작이 달라지므로, 방식을 잘못 고르면 의도하지 않은 결과가 나옵니다.

아이템 CSV를 올릴 때는 미리 정의한 필드가 CSV 헤더에 모두 포함되어야 합니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FWSqJgIRBIzr7RzpJF4nJ%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.31.04.png?alt=media&amp;token=53921901-bfb7-462d-bfaa-dc51e7610de3" alt=""><figcaption></figcaption></figure>

아이템 업로드는 백그라운드로 동작합니다. 화면을 닫아도 계속 진행되며, 완료되면 카탈로그 상세에서 결과를 확인할 수 있습니다. 한 카탈로그에 CSV 업로드는 한 번에 하나씩만 진행됩니다.

{% hint style="info" %}
**동일한 id를 가진 행이 CSV에 있다면 아래처럼 처리됩니다.**

* 새 아이템만 추가: 더 먼저 나온 행의 값이 반영됩니다.
* 기존 아이템만 수정: 더 나중에 나온 행의 값이 반영됩니다.
* 추가하고 수정: 더 나중에 나온 행의 값이 반영됩니다.
  {% endhint %}

#### CSV 파일 준비 체크리스트 <a href="#csv-checklist" id="csv-checklist"></a>

업로드 전에 파일이 아래 조건을 모두 만족하는지 확인하세요. 하나라도 빠지면 업로드가 실패하거나 값이 비어서 올라갑니다.

<table><thead><tr><th width="153.296875">확인 항목</th><th>요건</th></tr></thead><tbody><tr><td>헤더</td><td>첫 행은 필드 이름입니다. 이 이름이 그대로 카탈로그의 필드명이 됩니다.<br>필드명은 영문·숫자·<code>-</code>·<code>_</code>만 사용 가능합니다.</td></tr><tr><td><code>id</code> 컬럼</td><td>반드시 있어야 합니다. 이름은 정확히 <code>id</code>여야 하며, 컬럼 순서는 상관없습니다.</td></tr><tr><td><code>id</code> 값</td><td>중복 없음 · 최대 300자 · 영문·숫자·<code>-</code>·<code>_</code>만 사용 가능합니다.</td></tr><tr><td>컬럼 수</td><td>최대 50개</td></tr><tr><td>값 형식</td><td>각 컬럼의 값이 타입(string·number·boolean·time)에 맞아야 합니다.<br>숫자 컬럼에는 단위나 콤마가 없어야 하고, 날짜 컬럼은 시간대 오프셋이 있는 ISO 8601 형식이어야 합니다.</td></tr><tr><td>미정의 값</td><td>빈 셀은 허용됩니다.<br><code>NULL</code>, <code>null</code>, <code>-</code> 같은 값은 빈 값이 아니라 문자로 저장되니 비워 두세요.</td></tr><tr><td>파일 형식</td><td>CSV, UTF-8 인코딩</td></tr><tr><td>파일 크기</td><td>최대 500MB</td></tr><tr><td>아이템 수</td><td>최대 100만 개 (<code>id</code> 기준)</td></tr></tbody></table>

#### 카탈로그 데이터 유형 <a href="#catalog-data-types" id="catalog-data-types"></a>

카탈로그는 데이터를 효과적으로 구성하고 체계화하는 데 도움이 되는 다양한 데이터 유형을 지원합니다.

<table><thead><tr><th width="98.30078125">데이터 유형</th><th width="168.7890625">형식</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td>String</td><td>텍스트</td><td>자유로운 텍스트. 한글·특수문자·공백 허용 (최대 750자)</td><td><code>"Hello World"</code></td></tr><tr><td>Number</td><td>정수 또는 소수</td><td>계산할 수 있는 숫자. 정수·소수·부호 허용 (정수부 20자리 · 소수부 10자리)</td><td><code>42000</code> 또는 <code>19.99</code></td></tr><tr><td>Boolean</td><td><code>true</code> 또는 <code>false</code></td><td>둘 중 하나인 값. true/false(대소문자 무관) 또는 1/0</td><td><code>true</code></td></tr><tr><td>Time</td><td>ISO 8601</td><td>타임존이 지정된, 올바른 ISO 8601 형식</td><td><code>"2026-09-15T09:00:00Z"</code></td></tr></tbody></table>

## 필드 관리

필드는 **필드 탭**에서 관리합니다. 추가하고 설명을 고치고 삭제할 수 있지만, **한 번 만든 필드의 이름과 타입은 바꿀 수 없습니다.** 메시지가 필드명으로 값을 찾기 때문입니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FE37XhQylRJlKRB8ZDAOv%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%207.07.03.png?alt=media&amp;token=850e651a-1c20-4538-9c7c-95abb4bfc734" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FFFy5GTLRIpyCmRduu617%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.25.37.png?alt=media&amp;token=ce211839-c031-4fff-bb5a-5b3dc6121288" alt=""><figcaption><p>필드 추가 입력창</p></figcaption></figure>

* **필드 추가**: 언제든 가능합니다. 단, 필드를 추가하면 이후 올리는 아이템 CSV 헤더에도 그 필드가 있어야 합니다.
  * 새 필드는 기존 아이템에서 모두 빈 값으로 시작합니다. `id`와 새 필드 컬럼만 담은 CSV를 **기존 아이템만 수정**으로 올려 값을 한 번에 채우세요.
* **필드 삭제**: 가능하지만, 아이템이 있는 상태에서 필드를 삭제하면 **그 필드에 들어 있던 값이 모두 사라지고 되돌릴 수 없습니다.** 그 필드를 참조하는 메시지가 있는지 먼저 확인하세요.
* **필드 타입 변경**: 불가합니다. 필드를 삭제한 뒤 다시 만들어야 합니다.

{% hint style="warning" %}
**발송 중인 메시지가 사용 중인 필드는 삭제하지 마세요.**

사라진 필드를 참조하는 메시지는 그 자리가 비어서 나갑니다. 삭제 전에 이 필드를 쓰는 메시지부터 정리하세요.
{% endhint %}

## 카탈로그 삭제하기

카탈로그 상세 화면 오른쪽 위의 휴지통 아이콘을 누르면 삭제 확인 창이 뜹니다. 카탈로그와 그 안의 아이템이 모두 삭제되며, 운영 환경과 개발 환경에서 함께 사라집니다. 되돌릴 수 없습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2F6SyHS3AThW0saZ4MXMIR%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-22%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2010.41.48.png?alt=media&amp;token=3f2c7a89-050b-42c9-bb70-0a4f83176e46" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/catalog/manage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.