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

# 업무 데이터 API

> 상품·매장 같은 업무 데이터를 외부 시스템(ERP·POS)에서 직접 고치고 게시해요.

## 할 수 있는 일

포털 **업무 데이터**에 만든 «내 목록» 데이터셋을 여러분 시스템이 API로 바꿀 수 있어요. 통화 중 도구 인자는
**게시된 버전**으로만 식별되므로, 고친 내용은 게시해야 통화에 반영돼요.

* 레코드 조회·추가·수정·삭제, 전체 교체(JSON), 파일 올리기(CSV·XLSX)
* 바뀔 내용 미리보기(초안)와 게시
* 작업 상태 조회

<Note>
  주소·장소 검색(카카오) 데이터셋에는 외부 편집 API가 없어요. 데이터셋 설정·키 발급·Tool 연결은 포털에서만 해요.
</Note>

## 시작하기 전에

1. 포털 **업무 데이터 › 데이터셋 › 외부 API** 탭에서 **API 사용**을 켜요. 꺼져 있으면 모든 요청이 `403 API_DISABLED`예요.
2. 같은 탭에서 **데이터셋 키**(`tbd_live_`로 시작)를 발급해요. 키 원문은 발급 창에서 한 번만 보여요.
3. 키는 **그 데이터셋 하나**에만 쓸 수 있어요. 다른 데이터셋이나 다른 계정의 데이터에는 `404`예요.

<Warning>
  계정 API 키(`tello_live_`)로는 업무 데이터 API를 쓸 수 없어요(`403 ACCOUNT_KEY_NOT_SUPPORTED`). MCP·SDK·A2A에는 그대로 써요.
</Warning>

## 권한(역할)

키마다 역할을 골라 발급해요. **고칠 수 있다고 게시까지 할 수 있는 것은 아니에요.**

| 역할 | 할 수 있는 일 |
| - | - |
| `read` | 데이터셋·레코드·버전·작업 조회 |
| `write` | 레코드 추가·수정·삭제 |
| `replace` | 전체 교체(`PUT /records`)·파일 올리기(`POST /imports`) |
| `publish` | 초안 게시·버리기, 쓰기의 즉시 게시 |

`publish` 가 없는 키로 쓰면 변경은 **초안**에만 쌓이고 응답에 `"staged": true, "publish_denied": true` 가 붙어요.
포털이나 `publish` 키로 게시해야 통화에 반영돼요.

<Info title="예전에 발급한 키">
  이 기능 이전에 발급한 키는 예전처럼 쓰기가 곧바로 게시돼요(키 목록에 «기존 키»로 보여요). 새 규칙을 쓰려면 다시 발급해요.
</Info>

## 사용 방법

모든 요청에 `Authorization: Bearer <데이터셋 키>` 를 붙여요. 기본 주소는 다음과 같아요.

```bash 기본 주소 theme={null}
https://telloai.io/api/v1/business-datasets/{dataset_id}
```

### 레코드

| 작업 | 요청 |
| - | - |
| 목록(커서) | `GET /records?limit=100&cursor=<마지막 record_id>` |
| 초안 목록 | `GET /records?source=draft` |
| 한 건 | `GET /records/{record_id}` |
| 추가 | `POST /records` |
| 수정(보낸 필드만) | `PATCH /records/{record_id}` |
| 삭제 | `DELETE /records/{record_id}` |
| 전체 교체 | `PUT /records` 본문 `{"records": [...], "options": {...}}` |
| 파일 올리기 | `POST /imports` (`multipart/form-data`: `file`, 필요하면 `mapping`·`sheet`·`encoding`) |

레코드 모양은 업종과 상관없이 같아요.

```json 레코드 theme={null}
{
  "record_id": "S-IFC",
  "display_name": "여의도IFC점",
  "api_value": "1001",
  "aliases": ["IFC몰점"],
  "attributes": { "district": "영등포구" },
  "active": true
}
```

### 초안과 게시

* 쓰기에 `?publish=false`(전체 교체·파일은 `options.publish: false`)를 붙이면 게시하지 않고 초안에 쌓아요.
* `GET /versions` 에서 `status: "draft"` 인 버전이 게시 대기 초안이에요. `GET /versions/{version}` 은 추가·삭제·변경 건수와 앞쪽 표본을 줘요.
* `POST /versions/{version}/publish` 로 게시하고, `DELETE /versions/{version}` 으로 버려요.
* 초안은 24시간 동안 유지돼요. 그사이 다른 게시가 먼저 일어나면 게시가 `409 CONFLICT` 예요. 다시 미리보기 하고 올려요.

```bash 수정을 초안에 쌓고 게시하기 theme={null}
curl -X PATCH "https://telloai.io/api/v1/business-datasets/$DS/records/S-IFC?publish=false" \
  -H "Authorization: Bearer $TBD_KEY" -H "Content-Type: application/json" \
  -d '{"api_value": "1101"}'

curl -X POST "https://telloai.io/api/v1/business-datasets/$DS/versions/8/publish" \
  -H "Authorization: Bearer $TBD_PUBLISH_KEY" -H "Content-Type: application/json" -d '{}'
```

### 비동기 작업

전체 교체·파일 올리기는 `202` 와 작업을 돌려줘요. `202` 는 게시 성공이 아니에요.
`GET /sync-jobs/{job_id}` 의 `status` 가 `PUBLISHED`(게시됨)·`STAGED`(초안으로 멈춤)·`FAILED` 중 하나가 될 때까지 확인해요.

### 안전장치

| 장치 | 동작 |
| - | - |
| `If-Match` | 활성 버전 ETag(`"v<번호>"`)와 다르면 `412` |
| `Idempotency-Key` | 같은 키·같은 본문은 같은 작업, 다른 본문은 `422 IDEMPOTENCY_KEY_REUSED` |
| 대량 삭제·0건 | 기존의 절반 넘게 지우거나 0건이 되면 게시하지 않아요(`options.allow_mass_delete`·`allow_empty` 로 명시 허용) |
| 동시 작업 | 진행 중인 전체 교체·파일·게시가 있으면 `429 JOB_IN_PROGRESS` |
| 요청 수 | 키마다 분당 120회. 넘으면 `429 RATE_LIMITED` |

## 오류

| HTTP | 코드 | 뜻 |
| - | - | - |
| 401 | `UNAUTHORIZED` | 키가 없거나, 폐기·만료된 키 |
| 403 | `API_DISABLED` | 데이터셋의 API 사용이 꺼져 있음 |
| 403 | `ACCOUNT_KEY_NOT_SUPPORTED` | 계정 키로 요청함 |
| 403 | `FORBIDDEN`·`PUBLISH_REQUIRED` | 키 역할 밖의 작업 |
| 404 | `DATASET_NOT_FOUND` | 없는 데이터셋이거나 이 키의 데이터셋이 아님 |
| 409 | `CONFLICT`·`DRAFT_PENDING` | 초안의 기준 버전이 바뀜, 게시 대기 초안이 있음 |
| 410 | `DRAFT_EXPIRED` | 24시간이 지난 초안 |
| 422 | `VALIDATION_FAILED`·`MAPPING_REQUIRED` 등 | 레코드·파일 검증 실패(행 번호 포함) |

## 알아두기

* 키를 폐기·재발급하거나 API 사용을 꺼도 이미 게시된 버전과 통화에는 영향이 없어요. 재발급 때 옛 키를 최대 24시간 유예할 수 있어요.
* 키 발급·폐기·게시·인증 실패는 포털 **외부 API** 탭의 감사 기록에 남아요. 레코드 내용과 키 원문은 남기지 않아요.
* 응답 필드가 없는 업무 API(예: 헬스 체크)는 통화에서 «성공»만 알려 줘요. 도구가 부르는 API는 재고·주문처럼 **결과 필드가 있는 응답**을 돌려줘야 에이전트가 정확히 안내해요.


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