Data Export - 데이터 형식 상세

공통

스키마 버전

Data Export API에서 제공하는 데이터셋과 속성의 명세를 관리하는 버전 정보에요. 데이터 추출 요청 시 스키마 버전을 지정할 수 있으니, 스키마 버전을 참고하여 추출 결과의 형식을 확인해주세요. 데이터 추출 요청 시 스키마 버전을 지정하지 않으면 최신 스키마 버전이 적용돼요.

버전	설명
2026-10-01	최신

제공 데이터셋

Data Export API를 통해 조회할 수 있는 데이터셋 목록이에요.

구분	데이터셋	설명	관계
매장	MERCHANTS	매장	조회 시점 스냅샷
카탈로그	CATALOG_CATEGORIES	카테고리	조회 시점 스냅샷
카탈로그	CATALOG_ITEMS	상품	조회 시점 스냅샷
카탈로그	CATALOG_OPTIONS	옵션	조회 시점 스냅샷
카탈로그	CATALOG_OPTION_CHOICES	옵션 선택지	조회 시점 스냅샷
카탈로그	CATALOG_ITEM_OPTIONS	상품에 할당된 옵션	조회 시점 스냅샷
주문	ORDERS	주문	기간 조회
주문	ORDER_LINE_ITEMS	주문 내역	기간 조회
주문	ORDER_LINE_ITEM_OPTION_CHOICES	주문 내역의 옵션 선택지	기간 조회
주문	ORDER_DISCOUNTS	주문에 적용된 할인 내역	기간 조회
결제	PAYMENTS	결제 내역	기간 조회

조회 시점 스냅샷 데이터셋은 추출 요청 시점의 데이터를 모두 제공해요. 기간 조회 데이터셋은 데이터 추출 요청에 설정한 조회 기간 내의 데이터를 제공해요. 주문 또는 결제 내역 조회 시, 내역의 수정 시각(updated_at)을 기준으로 조회되므로 뒤늦게 환불/취소된 내역이 추출 결과에 포함될 수 있다는 점에 유의하세요.

데이터셋 관계

카탈로그

주문·결제

데이터 갱신 주기

주문, 결제 관련 데이터셋에서 당일 내역은 조회되지 않을 수 있다는 점에 유의해주세요.

파일 형식

현재 CSV 파일 형식만 제공해요.

상세 규격:

• 인코딩: UTF-8
• 구분자: 콤마(,)
• 개행: \n
• 첫 행은 헤더 행으로, 데이터셋별로 제공하는 속성명이 순서대로 제공돼요.
• Boolean 값(boolean)은 true 또는 false로 제공돼요.
• 날짜(date)는 yyyy-MM-dd 형식(예: 2026-01-01)으로 제공돼요.
• 시각(timestamp)은 UTC 기준, ISO 8601 형식(예: 2026-01-01T00:00:00Z)으로 제공돼요.

예시 (MERCHANTS 데이터셋)

"merchant_id","name","business_number","address"
42,"플레이스 베이커리","0000000000","서울특별시 서초구 강남대로 459 (서초동)"

데이터셋 상세 (버전: 2026-10-01)

매장

매장 (MERCHANTS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
name	string	매장 이름		"플레이스 베이커리"
business_number	string	사업자 번호		"0000000000"
address	string	주소		"서울특별시 서초구 강남대로 459 (서초동)"

카탈로그

카테고리 (CATALOG_CATEGORIES)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
category_id	string	카테고리 ID	PK	"42"
title	string	카테고리명		"커피"
code	string	카테고리 코드		"COFFEE_000"
order	int	정렬 순서		1
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"

상품 (CATALOG_ITEMS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
item_id	string	상품 ID	PK	"42"
title	string	상품명		"아메리카노"
code	string	상품 코드		"AMERICANO_000"
category_id	string	카테고리 ID		"42"
order	int	카테고리 내 정렬 순서		1
price_type	string	가격 종류 ("FIXED", "VARIABLE", "UNIT") 상품 가격 종류를 참고해주세요.		"FIXED"
price_unit	long	가격 단위		1
price_value	long	가격		3000
barcode	string	바코드		"1234567890"
attributes	json	기타 속성		{"key": "value"}
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"

옵션 (CATALOG_OPTIONS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
option_id	string	옵션 ID	PK	"42"
title	string	옵션명		"온도"
code	string	옵션 코드		"VARIATION_000"
order	int	정렬 순서		1
required	boolean	필수 선택 여부		true
min_choices	int	고를 수 있는 최소 선택지 개수		1
max_choices	int	고를 수 있는 최대 선택지 개수		3
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"

옵션 선택지 (CATALOG_OPTION_CHOICES)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
option_id	string	옵션 ID		"42"
option_choice_id	string	선택지 ID	PK	"42"
title	string	선택지명		"ICE"
code	string	선택지 코드		"ICE_000"
order	int	옵션 내 정렬 순서		1
price_value	long	가격		3000
quantity_enabled	boolean	수량 선택 가능 여부		true
min_quantity	int	선택 가능 최소 수량		1
max_quantity	int	선택 가능 최대 수량		999
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"

상품에 할당된 옵션 (CATALOG_ITEM_OPTIONS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
item_id	string	상품 ID	PK	"42"
option_id	string	옵션 ID	PK	"42"

주문

주문 (ORDERS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
order_id	string	주문 ID	PK	"620000000000000000"
order_key	string	주문 키 주문을 식별하는 용도로 사용하는 문자열이에요. 주문 채널에 따라 고유의 값 체계를 사용할 수 있어요.		"EXT-20260512-0001"
source	string	주문 채널 주문이 인입된 경로를 말해요. 예를 들어, 토스 POS로부터 인입된 주문은 "POS", 토스 키오스크로부터 인입된 주문은 "KIOSK" 등이에요.		"POS"
source_group	string	주문 채널 대분류 (POS/KIOSK/DELIVERY, 미분류 주문은 값 없음)		"POS"
order_state	string	주문 상태		"OPENED"
date	date	주문 발생일 (주문의 created_at 기준)		"2026-01-01"
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"
opened_at	timestamp	주문 수락 시각		"2026-01-01T00:00:00Z"
cancelled_at	timestamp	주문 취소 시각		"2026-01-01T00:00:00Z"
charge_price_list_price	long	원주문 금액		3500
charge_price_discount_amount	long	할인 금액		-300
charge_price_tip_amount	long	팁		0
charge_price_tax_amount	long	세액		291
charge_price_total_amount	long	최종 주문 금액		3200
line_items_count	int	주문 내역 개수		1
line_items_total_quantity	int	주문 내역 총 수량		1
payments_count	int	결제 건수		1
payments_approved_amount	long	승인 결제 금액		3200
payments_cancelled_amount	long	취소 결제 금액		0
accurals_point_amount	long	적립 포인트 금액		100
accurals_stamp_count	int	적립 스탬프 개수		1

주문 내역 (ORDER_LINE_ITEMS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
order_id	string	주문 ID	PK	"620000000000000000"
line_item_no	int	주문 내역 순번	PK	1
date	date	주문 발생일 (주문의 created_at 기준)		"2026-01-01"
dining_option	string	식사 옵션 예: 매장 식사(HERE), 포장(TOGO), 배달(DELIVERY)		"HERE"
item_type	string	상품 종류 예: 일반 상품(ITEM), 세트 상품(COMBO)		"ITEM"
item_title	string	상품명		"아메리카노"
item_code	string	상품 코드		"AMERICANO_000"
category_title	string	카테고리명		"커피"
price_type	string	가격 종류 (FIXED/VARIABLE/UNIT)		"FIXED"
price_unit	long	가격 단위		1
price_value	long	단가		3000
is_tax_free	boolean	면세 여부		false
tax_percentage	int	세율		10
tax_inclusive	boolean	부가세 포함 여부		true
quantity	int	수량		1
charge_price_list_value	long	내역 원금액 (상품 및 옵션 추가금 포함)		3500
charge_price_discount_amount	long	내역에 적용된 할인 금액		-300
charge_price_total_amount	long	내역 최종 금액		3200

주문 내역의 옵션 선택지 (ORDER_LINE_ITEM_OPTION_CHOICES)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
order_id	string	주문 ID	PK	"620000000000000000"
line_item_no	int	주문 내역 순번	PK	1
option_choice_no	int	내역의 옵션 선택지 순번	PK	1
date	date	주문 발생일 (주문의 created_at 기준)		"2026-01-01"
option_title	string	옵션명		"온도"
option_choice_title	string	선택지명		"ICE"
option_choice_code	string	선택지 코드		"ICE_000"
quantity	int	수량		1
price_value	long	가격		500

주문에 적용된 할인 내역 (ORDER_DISCOUNTS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
order_id	string	주문 ID	PK	"620000000000000000"
line_item_no	int	주문 내역 순번 값이 없는 경우 주문 전체에 적용된 할인	PK	1
discount_no	int	할인 순번	PK	1
date	date	할인 적용일 (주문의 created_at 기준)		"2026-01-01"
title	string	할인명		"PROMOTION"
type	string	할인 종류 (예: "FIXED_AMOUNT", "FIXED_PERCENTAGE")		"FIXED_AMOUNT"
code	string	할인 코드		"PROMOTION_00"
amount	long	할인 적용 금액		1000
percentage	double	정률할인 비율 (정률할인이 아닌 경우 0)		0
fixed_amount	long	정액할인 금액 (정액할인이 아닌 경우 0)		1000
precedence	int	할인 적용 우선순위 (값이 작을수록 높은 우선순위)		1

결제

결제 (PAYMENTS)

속성명	타입	설명	관계	예시
merchant_id	long	매장 ID	PK	42
payment_id	string	결제 ID	PK	"620000000000000000"
order_id	string	주문 ID		"620000000000000000"
date	date	결제 발생일 (approved_at 기준)		"2026-01-01"
state	string	결제 상태 (APPROVED/CANCELLED)		"APPROVED"
source_type	string	결제수단 대분류 (CASH/CARD/PREPAID_VALUE/ACCOUNT_TRANSFER/BARCODE/EXTERNAL)		"CARD"
payment_method	string	결제수단 세부 분류		"CARD_NFC"
van	string	VAN		"NICE"
amount	long	결제금액		3200
tax_amount	long	세액		291
supply_amount	long	공급가액		2909
tax_exempt_amount	long	면세금액		0
tip_amount	long	봉사료		0
approved_no	string	승인번호		"00000000"
approved_at	timestamp	승인 시각		"2026-01-01T00:00:00Z"
cancelled_at	timestamp	취소 시각		"2026-01-01T00:00:00Z"
created_at	timestamp	생성 시각		"2026-01-01T00:00:00Z"
updated_at	timestamp	수정 시각		"2026-01-01T00:00:00Z"
card_type	string	카드 종류 (CREDIT/DEBIT/PREPAID/FOREIGN)		"CREDIT"
card_brand	string	발급사명
card_brand_id	string	발급사 코드
card_no	string	카드번호 (마스킹 적용)		"00000000********"
card_acquirer	string	매입사명
card_acquirer_id	string	매입사 코드
card_installment_month	string	할부개월 수		"00"
easy_pay_provider	string	간편결제 제공사		"토스페이"
easy_pay_type	string	간편결제 결제수단 종류 (ACCOUNT/CARD)		"ACCOUNT"
external_source	string	외부 결제수단명		"모바일 상품권"
cash_receipt_issuer_type	string	현금영수증 발급 종류 (CONSUMER/BUSINESSES)		"CONSUMER"
cash_receipt_issuance_type	string	현금영수증 발급 방법 (PHONE/BUSINESS_NUMBER/CARD)		"PHONE"
cash_receipt_self_issuance	boolean	현금영수증 자진 발급 여부		true
cash_receipt_issue_number	string	현금영수증 발급 번호		"0000000000"
cash_receipt_issued_at	timestamp	현금영수증 발급 시각		"2026-01-01T00:00:00Z"
cash_receipt_amount	long	현금영수증 발급 금액		3200
bundle_key	string	결제 번들 식별자