업무 데이터 API - Tello Voice

할 수 있는 일

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

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

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

시작하기 전에

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

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

권한(역할)

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

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

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

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

사용 방법

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

기본 주소

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`)

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

레코드

{
  "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 예요. 다시 미리보기 하고 올려요.

수정을 초안에 쌓고 게시하기

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는 재고·주문처럼 결과 필드가 있는 응답을 돌려줘야 에이전트가 정확히 안내해요.

​할 수 있는 일

​시작하기 전에

​권한(역할)

​사용 방법

​레코드

​초안과 게시

​비동기 작업

​안전장치

​오류

​알아두기

할 수 있는 일

시작하기 전에

권한(역할)

사용 방법

레코드

초안과 게시

비동기 작업

안전장치

오류

알아두기