> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telloai.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 업무 데이터

> 상품·매장·주소처럼 고객이 말한 값을 등록된 목록으로 확인해, 도구에는 정확한 값만 보내요.

## 할 수 있는 일

고객은 «여의도 IFC점», «IFC몰점»처럼 같은 대상을 여러 이름으로 말해요. 업무 데이터에 목록을 등록해 두면, 통화 중 고객이 말한 이름을 목록과 대조해 확인하고 도구에는 **정해 둔 값**(매장 코드 등)만 보내요. 하나로 정해지지 않으면 API를 부르지 않고 고객에게 다시 물어요.

데이터셋은 두 종류예요. `데이터셋 만들기`를 누르면 나오는 창의 **종류**에서 골라요. 만든 뒤에는 목록 표의 **종류** 칸에 표시돼요.

| 종류 | 쓰임 |
| - | - |
| **내 목록** | 파일이나 직접 입력으로 채우는 목록이에요. 상품·매장·지점처럼 우리 업무 대상을 등록해요 |
| **주소·장소 검색(카카오)** | 고객이 말한 주소·장소를 카카오에서 찾아, 고객이 확인한 값을 보내요 |

## 시작하기 전에

사이드바 **에이전트 › 업무 데이터**에서 관리해요. 데이터셋은 만들기만 해서는 통화에 쓰이지 않아요. 아래 순서를 모두 거쳐야 해요.

**1. 데이터셋을 만들고 채워요**

`데이터셋 만들기`로 만들고 레코드를 넣어요.

**2. 게시해요**

변경은 **초안**에 쌓여요. 위쪽 배너에서 `게시`해야 통화에 쓰여요.

**3. 도구 인자에 연결해요**

[도구 모음](https://docs.telloai.io/agents/tools.md#업무데이터-연결)에서 API 요청 도구를 열고, 인자의 `고급` › **업무데이터 연결**에서 데이터셋을 골라요.

**4. 도구를 발행해요**

연결을 바꾼 뒤에는 도구를 발행해야 통화에 반영돼요.

## 데이터셋 만들기

목록 화면 오른쪽 위의 `데이터셋 만들기`를 누르면 **데이터셋 만들기** 창이 떠요. **이름**(필수), \*\*설명(선택)\*\*을 적고 **종류**에서 **내 목록** 또는 \*\*주소·장소 검색(카카오)\*\*를 골라요. `만들기`를 누르면 상세 화면으로 넘어가요.

> [!TIP]
>
> `표준 양식 CSV`를 누르면 열 이름과 예시 행이 들어 있는 양식 파일을 받을 수 있어요. 이 양식에 맞춰 채우면 가져오기가 쉬워요.

데이터셋이 하나도 없으면 목록 자리에 «데이터셋이 없습니다» 안내만 보여요. 만든 뒤에는 목록 표에 데이터셋마다 종류, 레코드 수, **현재 버전**(게시 전이면 `미게시`), 게시 시각, 연결된 도구 수, 외부 API 사용 여부가 보여요. 만든 데이터셋을 다시 열려면 표의 **이름**을 눌러요(마우스를 올리면 밑줄이 생겨요).

## 내 목록 데이터셋

상세 화면에는 **레코드 · 가져오기 · 설정 · 버전 · 연결 · 외부 API** 탭이 있어요.

### 레코드

레코드 하나가 업무 대상 하나예요. `레코드 추가`로 한 건씩 넣어요.

| 항목 | 뜻 |
| - | - |
| **record\_id** | 고객사 코드처럼 바뀌지 않는 값이에요. 나중에 바꿀 수 없어요 |
| **표시명** | 고객에게 읽어 줄 정식 이름이에요 |
| **API 값** | 도구 인자로 보낼 값이에요(코드·이름 등) |
| **별칭(쉼표로 구분)** | 고객이 다르게 부르는 이름이에요. 예: `IFC점, IFC몰점` |
| **설명(선택)** | 후보를 안내할 때 함께 말할 정보예요. 설정 탭의 **후보를 물을 때 함께 말할 정보**에서 **설명**을 체크해야 쓰여요 |
| **속성** | 설정 탭에서 만든 속성마다 칸이 생겨요 |
| **사용** | 끄면 통화에서 찾지 않아요 |

검색창에서 표시명·record\_id·API 값으로 찾을 수 있고, `게시본`과 `초안`을 바꿔 가며 볼 수 있어요.

> [!NOTE]
>
> 레코드를 추가·수정·삭제하면 **초안에 담겨요.** 게시하기 전까지 통화는 지금 게시된 데이터를 그대로 써요.

### 가져오기 (CSV·XLSX)

목록을 파일로 한 번에 올려요. 올린 파일은 **기존 목록 전체를 바꾸는 초안**이 돼요.

**1. 파일 올리기**

CSV나 XLSX 파일(20MB 이내)을 고르고 `파일 읽기`를 눌러요. XLSX는 **시트**와 **헤더 행**을, CSV는 **인코딩**(UTF-8 / CP949(엑셀 한글) / EUC-KR)을 골라요. 인코딩은 자동으로 추측하지 않아요.

**2. 열 매핑**

파일의 열마다 어디에 쓸지 골라요(record\_id, display\_name, api\_value, description, aliases, active, 속성). 쓰지 않을 열은 **무시**로 둬요. 표준 양식과 열 이름이 똑같거나 저장해 둔 매핑이 있으면 미리 채워져요. 그 밖에는 비슷한 이름이라고 맞추지 않으니 열마다 정해요. 표시명(display\_name) 열은 꼭 있어야 해요. 파일의 aliases 열은 `|`로 구분해요(예: `IFC점|IFC몰점`).

**3. 검사하고 초안 만들기**

`검사`를 눌러 오류가 없으면 `미리보기 만들기(초안)`를 눌러요. 큰 파일은 1분 가까이 걸릴 수 있어요. **초안 준비됨**이 뜨면 위 배너에서 게시해요.

**record\_id 만드는 방법**은 열에서 가져오기(권장)와 표시명으로 만들기 중에, **API 로 보낼 값**은 api\_value 열, record\_id 열과 같은 값, 표시명 그대로 중에 골라요. 속성 열을 쓰려면 **설정** 탭에서 속성을 먼저 만들어요.

### 초안과 게시

변경이 생기면 탭 위에 **게시 대기 중인 변경이 있습니다** 배너가 떠요.

* `미리보기`: 추가·삭제·변경된 레코드 수와 표본을 보여줘요.
* `게시`: 다음 통화부터 새 데이터로 확인해요.
* `버리기`: 초안의 변경을 모두 버려요.

초안은 24시간 동안 유효해요. 레코드를 절반 넘게 지우거나 0건이 되는 변경은 확인 체크를 해야 게시돼요.

### 설정

| 항목 | 뜻 |
| - | - |
| **속성** | 지역·용량처럼 이름이 같은 대상을 가르는 정보예요. 역할을 **거르기**(말하면 그 값만), **구별**(후보를 가를 때 씀), **필수**(말하지 않으면 묻기), **보관만** 중에 골라요 |
| **이름 끝에서 무시할 말** | 예: `점, 매장`. «여의도IFC점»을 «여의도IFC»로도 찾아요 |
| **한 번에 보여 줄 후보 수(1\~5)** | 후보가 여럿일 때 몇 개까지 안내할지 정해요. 기본 3 |
| **후보를 물을 때 함께 말할 정보** | 후보를 안내할 때 함께 말할 설명이나 속성을 골라요. 하나도 고르지 않으면 후보마다 값이 다른 속성(거르기·구별·필수)을 써요 |

거리나 당일 휴무처럼 자주 바뀌는 값은 **보관만**으로 둬요. 속성, 무시할 말, 후보 수, 함께 말할 정보를 바꿔 저장하면 같은 데이터로 새 버전이 바로 게시돼요. 게시 대기 중인 초안이 있으면 먼저 게시하거나 버려야 저장돼요.

### 버전

게시한 버전 목록이에요. 현재 버전과 바로 이전 버전 1개만 복원할 수 있어요. 그보다 오래된 버전은 레코드가 정리돼 복원할 수 없어요. `복원`은 그 버전으로 **새 초안**을 만들어요. 배너에서 미리보기 후 게시해야 되돌아가요.

### 연결

* **연결된 도구**: 이 데이터셋을 쓰는 도구와 인자, 반영 상태(`통화 반영`, `발행 필요` 등)가 보여요. 연결은 도구 편집 화면에서 바꿔요.
* **식별 기록(최근 30일)**: 통화 중 들어온 값과 식별 결과(확정·재질문·찾지 못함 등)를 보여줘요. 자주 못 찾는 이름은 레코드 별칭으로 보강해요.

> [!WARNING]
>
> 도구에 연결된 데이터셋은 삭제할 수 없어요. **연결** 탭에서 연결마다 `무효로 하기`를 누른 뒤 삭제해요. 도구 편집 화면에서 `연결 안 함`으로 바꾸기만 해서는 풀리지 않아요.

## 외부 API로 편집하기

ERP·POS 같은 우리 시스템이 목록을 직접 고치게 할 수 있어요. 데이터셋 상세의 **외부 API** 탭에서 설정해요.

**1. 외부 API 사용을 켜요**

**외부 API 사용** 스위치를 켜요. 끄면 이 데이터셋의 키 요청이 모두 거부돼요. 게시된 데이터와 통화에는 영향이 없어요.

**2. 데이터셋 키를 발급해요**

`키 발급`을 누르고 이름과 역할을 정해요. 키는 `tbd_live_`로 시작하고, **그 데이터셋 하나에만** 쓸 수 있어요. 원문은 발급 직후 한 번만 보이니 바로 복사해 안전한 곳에 둬요.

**3. 개발자에게 전달해요**

요청 주소와 방법은 [업무 데이터 API](https://docs.telloai.io/developer/business-data.md) 문서에 있어요.

키를 발급할 때 역할을 골라요. 기본으로 읽기·쓰기가 선택돼 있어요.

| 역할 | 할 수 있는 일 |
| - | - |
| **읽기** | 레코드·작업 조회 |
| **쓰기** | 레코드 추가·수정·삭제 |
| **전체교체** | 목록 통째 교체·파일 업로드 |
| **게시** | 초안 게시·버리기 |

> [!NOTE]
>
> **게시** 역할이 없는 키로 고친 내용은 초안에만 쌓여요. 포털이나 게시 역할이 있는 키로 게시해야 통화에 반영돼요. 키 목록에 `기존 키` 표시가 붙은 예전 키는 고치면 바로 게시돼요.

* `재발급`: 같은 역할의 새 키를 만들어요. 옛 키는 즉시 폐기하거나 10분·1시간·24시간 뒤 만료되게 둘 수 있어요.
* `폐기`: 그 키를 즉시 막아요.
* **감사 기록**: 키 발급·폐기, 레코드 변경, 게시, 인증 실패를 1년 동안 남겨요. 누가 했는지 포털·API 키·시스템으로 구분해 보여줘요.

> [!WARNING]
>
> 계정 API 키(`tello_live_`)로는 업무 데이터를 고칠 수 없어요. 데이터셋 키를 따로 발급해요. 주소·장소 검색 데이터셋에는 외부 API가 없어요.

## 주소·장소 검색 데이터셋

데이터셋을 만들 때 종류를 \*\*주소·장소 검색(카카오)\*\*로 고르고 두 가지를 정해요.

| 검색 종류 | 도구에 보낼 값 |
| - | - |
| **주소 검색** | 도로명주소(기본) · 지번주소 · 우편번호 · 좌표(경도,위도) |
| **장소(키워드) 검색** | 장소명(기본) · 장소 ID · 도로명주소 · 지번주소 · 좌표(경도,위도) |

상세 화면에는 **검색 설정·시험**과 **연결** 탭이 있어요. 검색 설정에서는 **지역 제한(선택)**(예: `서울`로 시작하는 주소만), 장소 검색의 **카테고리 코드(선택)**, \*\*한 번에 보여 줄 후보 수(1\~5)\*\*를 정해요. **검색 시험**에 주소나 장소를 넣어 보면 통화에서 어떤 후보가 나올지 미리 볼 수 있어요. Tello 키를 쓰는 중이면 시험 검색도 하루 한도에 포함돼요.

통화에서는 이렇게 동작해요.

* 후보가 1개여도 고객에게 읽어 주고, 고객이 맞다고 답한 뒤에만 도구에 보내요.
* 후보가 여럿이면 구분해서 묻고, 고객이 고른 후보만 보내요.
* 건물번호·지번이 없는 불완전한 주소는 확정하지 않고 더 물어요.
* 동·호수 같은 상세 주소는 이 인자가 아니라 별도 인자로 받아요.

> [!NOTE]
>
> 카카오 검색 결과와 고객이 말한 주소는 저장하지 않아요. 통화 중 확인에만 쓰고 통화가 끝나면 지워요. 그래서 식별 기록에도 상태와 후보 수만 남아요.

### 카카오 주소검색용 API 키

업무 데이터 목록 화면의 **카카오 주소검색용 API 키** 카드에서 관리해요. 계정 안의 주소·장소 검색 데이터셋이 모두 이 키를 함께 써요.

* 키를 등록하지 않으면 Tello 키를 **계정당 하루 100건**(한국시간 자정 초기화)까지 써요.
* 내 카카오 REST API 키를 등록하면 한도 없이 쓰고, 카카오 쿼터와 비용은 가입자 부담이에요.

키를 발급받는 방법이에요.

**1. 앱을 만들어요**

카카오 디벨로퍼스(developers.kakao.com) 앱 관리 페이지에서 \[앱 생성]으로 앱을 만들어요.

**2. 카카오맵을 켜요**

앱 관리 페이지 \[카카오맵] › \[사용 설정]을 ON으로 켜요. 꺼져 있으면 등록할 때 거부돼요.

**3. REST API 키를 붙여 넣어요**

\[앱] › \[플랫폼 키]의 **REST API 키**를 복사해 **내 카카오 REST API 키 등록** 칸에 넣고 `등록`해요. JavaScript 키나 네이티브 앱 키가 아니에요.

등록한 키는 암호화해 보관하고 다시 보여 주지 않아요. `교체`로 바꾸거나 `삭제`로 지울 수 있고, 지우면 다시 Tello 키(하루 한도)를 써요.

## 주의사항

* 파일 가져오기·전체교체는 최대 50,000건까지예요. 별칭은 레코드당 50개까지예요.
* 장소 검색으로는 우리 회사 내부 매장코드를 얻을 수 없어요. 내부 코드가 필요하면 «내 목록» 데이터셋으로 장소명과 코드를 따로 만들어요.
* 데이터셋 삭제는 되돌릴 수 없어요.

## 관련 문서

* [도구 모음 › 업무데이터 연결](https://docs.telloai.io/agents/tools.md#업무데이터-연결)
* [업무 데이터 API](https://docs.telloai.io/developer/business-data.md)
* [지식 관리](https://docs.telloai.io/agents/knowledge.md)


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