카탈로그 관리
카탈로그는 상품, 콘텐츠처럼 데이터를 저장해두고 쓰기 위한 기능입니다. 카탈로그에 담은 아이템은 메시지 개인화 등에 활용할 수 있습니다.
카탈로그 API로 카탈로그를 만들고, 아이템을 올리고, 저장된 아이템을 수정할 수 있습니다.
인증
모든 요청에 API 키를 헤더로 전달해야 합니다.
X-HACKLE-API-KEY
API 키 (대시보드 > 연동 정보에서 확인)
기본 규칙
Base URL:
https://api.hackle.io요청 본문은
Content-Type: application/json입니다.카탈로그와 필드는 이름으로 지정합니다. 이름은 만들고 나면 바꿀 수 없습니다.
카탈로그는 워크스페이스의 모든 환경에 만들어지고, 아이템은 API 키의 환경에만 저장됩니다.
필드 타입
STRING
문자열 (750자 이하)
"티셔츠"
NUMBER
숫자 (정수부 20자리, 소수부 10자리 이하)
19900
BOOLEAN
true / false
true
TIME
ISO-8601 문자열 또는 epoch 초
"2026-08-01T00:00:00Z", 1754006400
1. 카탈로그 목록 조회
엔드포인트: GET https://api.hackle.io/v1/catalogs
응답 본문
catalogs
Array
카탈로그 목록
catalogs[].catalogName
string
카탈로그 이름
catalogs[].description
string
카탈로그 설명
catalogs[].itemCount
number
아이템 수 (API 키의 환경 기준)
catalogs[].createdAt
string
생성 일시
catalogs[].modifiedAt
string
수정 일시
응답 코드
200 OK: 성공
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
2. 카탈로그 조회
엔드포인트: GET https://api.hackle.io/v1/catalogs/{catalogName}
경로 파라미터
catalogName
string
O
카탈로그 이름
응답 본문
catalogName
string
카탈로그 이름
description
string
카탈로그 설명
itemCount
number
아이템 수 (API 키의 환경 기준)
createdAt
string
생성 일시
modifiedAt
string
수정 일시
fields
Array
필드 목록
fields[].fieldName
string
필드 이름
fields[].fieldType
string
필드 타입
응답 코드
200 OK: 성공
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
3. 카탈로그 생성
엔드포인트: POST https://api.hackle.io/v1/catalogs
요청 본문
catalogName
string
O
카탈로그 이름. 영문, 숫자, -, _ 만 사용하며 200자 이하
description
string
X
카탈로그 설명
fields
Array
X
함께 만들 필드 목록 (최대 50개)
fields[].fieldName
string
O
필드 이름. 카탈로그 안에서 유일해야 하며 id 는 사용할 수 없음
fields[].fieldType
string
O
STRING / NUMBER / BOOLEAN / TIME
응답 본문
카탈로그 조회와 같습니다.
응답 코드
201 Created: 성공
400 Bad Request: 유효하지 않은 요청
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
409 Conflict: 같은 이름의 카탈로그가 이미 있거나 카탈로그 수 상한(20개) 초과
4. 카탈로그 삭제
엔드포인트: DELETE https://api.hackle.io/v1/catalogs/{catalogName}
경로 파라미터
catalogName
string
O
카탈로그 이름
응답 코드
204 No Content: 성공
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
카탈로그를 삭제하면 담겨 있던 아이템도 함께 사용할 수 없게 됩니다. 삭제한 이름은 다시 사용할 수 있습니다.
5. 필드 추가
엔드포인트: POST https://api.hackle.io/v1/catalogs/{catalogName}/fields
요청 본문
fieldName
string
O
필드 이름. 카탈로그 안에서 유일해야 하며 id 는 사용할 수 없음
fieldType
string
O
STRING / NUMBER / BOOLEAN / TIME
응답 본문
응답 코드
201 Created: 성공
400 Bad Request: 유효하지 않은 요청
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
409 Conflict: 같은 이름의 필드가 이미 있거나 필드 수 상한(50개) 초과
6. 필드 삭제
엔드포인트: DELETE https://api.hackle.io/v1/catalogs/{catalogName}/fields/{fieldName}
경로 파라미터
catalogName
string
O
카탈로그 이름
fieldName
string
O
필드 이름
응답 코드
204 No Content: 성공
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 또는 필드 없음
7. 아이템 추가
엔드포인트: POST https://api.hackle.io/v1/catalogs/{catalogName}/items
요청 본문
items
Array
O
추가할 아이템 목록. 1개 이상 500개 이하
items[].id
string
O
아이템 식별자. 영문, 숫자, -, _ 만 사용하며 300자 이하
items[].fields
Object
X
필드 이름과 값. 카탈로그에 정의된 필드만 사용 가능
응답 본문
processedCount
number
처리한 아이템 수
응답 코드
200 OK: 성공
400 Bad Request: 유효하지 않은 요청 또는 아이템 검증 실패 (아이템 업로드 실패 참고)
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
409 Conflict: 같은 카탈로그에 다른 업로드가 진행 중
8. 아이템 수정
엔드포인트: PUT https://api.hackle.io/v1/catalogs/{catalogName}/items
요청 본문과 응답은 아이템 추가와 같습니다.
아이템을 통째로 교체합니다. 보내지 않은 필드는 값이 지워집니다. 한 필드만 바꾸려는 경우에도 나머지 필드를 함께 보내야 합니다.
응답 코드
200 OK: 성공
400 Bad Request: 유효하지 않은 요청 또는 아이템 검증 실패
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
409 Conflict: 같은 카탈로그에 다른 업로드가 진행 중
9. 아이템 삭제
엔드포인트: DELETE https://api.hackle.io/v1/catalogs/{catalogName}/items
요청 본문
ids
Array
O
삭제할 아이템 식별자 목록. 1개 이상 500개 이하
응답 본문
응답 코드
200 OK: 성공
400 Bad Request: 유효하지 않은 요청
401 Unauthorized: 헤더값 없음 또는 유효하지 않은 API 키
404 Not Found: 해당 이름의 카탈로그 없음
409 Conflict: 같은 카탈로그에 다른 업로드가 진행 중
에러 응답
에러는 아래 형식으로 응답합니다.
400
bad_request
요청 본문 형식이 올바르지 않음
400
CATALOG_NAME_INVALID
카탈로그 또는 필드 이름 규칙 위반
400
CATALOG_FIELD_NAME_INVALID
필드 이름이 중복되거나 예약어(id) 사용
400
ITEM_UPLOAD_REQUEST_INVALID
아이템 수가 1~500 범위를 벗어남
400
INVALID_PAGINATION
페이지 번호 또는 페이지 크기가 범위를 벗어남
401
-
헤더값 없음 또는 유효하지 않은 API 키
429
TOO_MANY_REQUESTS
호출 한도 초과
404
CATALOG_NOT_FOUND
해당 이름의 카탈로그 없음
404
CATALOG_FIELD_NOT_FOUND
해당 이름의 필드 없음
404
CATALOG_ITEM_NOT_FOUND
해당 식별자의 아이템 없음
409
CATALOG_NAME_DUPLICATE
같은 이름의 카탈로그 또는 필드가 이미 있음
409
CATALOG_CAP_EXCEEDED
카탈로그 또는 필드 수 상한 초과
409
CONCURRENT_MODIFICATION
같은 카탈로그에 다른 변경이 진행 중
409
ITEM_UPLOAD_IN_PROGRESS
같은 카탈로그에 다른 아이템 업로드가 진행 중
500
internal_server_error
서버 오류
아이템 업로드 실패
아이템 추가·수정 요청의 아이템이 검증에 실패하면, 실패한 위치와 함께 400으로 응답합니다. 한 건이라도 실패하면 요청 전체가 반영되지 않습니다.
code
string
실패 사유
message
string
실패 사유 설명
failedRowNumber
number
실패한 아이템의 순번 (1부터)
failedValue
string
실패한 값
TYPE_MISMATCH
값이 필드 타입과 맞지 않거나, 카탈로그에 없는 필드를 사용
LENGTH_EXCEEDED
값이 너무 김
ITEM_LIMIT_REACHED
카탈로그의 아이템 수 상한 초과
MISSING_ITEM_KEY
아이템 식별자가 비어 있음
INVALID_ITEM_KEY
아이템 식별자 규칙 위반
MISSING_FIELD
필수 값 누락
호출 한도
카탈로그를 변경하는 요청(카탈로그·필드 생성/삭제, 아이템 추가/수정/삭제)은 워크스페이스와 환경 단위로 분당 50회로 제한합니다.
응답에 남은 호출 수를 헤더로 내려줍니다.
헤더
설명
X-RateLimit-Limit
한도
X-RateLimit-Remaining
남은 호출 수
X-RateLimit-Reset
한도가 회복되는 시각 (epoch 초)
Retry-After
한도 초과 시 재시도까지 기다려야 하는 초
한도를 넘으면 429로 응답합니다. Retry-After 만큼 기다린 뒤 재시도하세요.
제약사항
워크스페이스당 카탈로그 수
20개
카탈로그당 필드 수
50개
카탈로그당 아이템 수
1,000,000개 (환경별)
한 요청의 아이템 수
1~500개
카탈로그·필드 이름
영문, 숫자, -, _ / 200자 이하
아이템 식별자
영문, 숫자, -, _ / 300자 이하
문자열 값 길이
750자
숫자 값
정수부 20자리, 소수부 10자리
카탈로그 이름과 필드 이름은 만든 뒤에 바꿀 수 없습니다.
id는 아이템 식별자용으로 예약되어 필드 이름으로 사용할 수 없습니다.아이템에 값을 넣으려면 필드를 먼저 만들어야 합니다. 카탈로그에 없는 필드를 보내면 요청이 실패합니다.
응답의
processedCount는 요청한 아이템 수입니다. 이미 있는id를 추가하거나 없는id를 수정·삭제한 경우에도 개수에 포함됩니다.
마지막 업데이트