Data Export - API 상세

WARNING

Data Export API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요. 문의사항이 있으신 경우 개발자센터 지원 이메일로 문의해주세요.

Types

데이터 추출 (DataExport)

요청 조건, 진행 상태, 결과 파일 등 데이터 추출 요청에 대한 정보를 담고 있어요.

Name	Type	Required	Description	Example
requestId	String	✅	요청 ID	"d290f1ee-6c54-4b01-90e6-d701748f0851"
datasets	DataExportDataset[]	✅	추출 데이터셋 목록	["MERCHANTS"]
idempotencyKey	String		요청 중복 방지 식별자	"export-20261001-0001"
from	timestamp		조회 범위 시작점	"2026-10-01T00:00:00Z"
to	timestamp		조회 범위 종료점	"2026-10-01T00:00:00Z"
format	DataExportFormat	✅	추출 결과 형식	"CSV"
schemaVersion	String	✅	추출 결과 스키마 버전 스키마 버전을 참고해주세요.	"2026-10-01"
state	DataExportState	✅	요청 처리 상태	"RUNNING"
files	DataExportFile[]		추출 결과 파일 목록
requestedAt	timestamp	✅	요청 시각	"2026-10-01T00:00:00Z"
expiresAt	timestamp	✅	요청 만료 시각 데이터 추출 요청은 요청한 지 3일이 지나면 만료돼요. 만료된 추출 요청은 더 이상 결과 파일을 조회할 수 없어요.	"2026-10-01T00:00:00Z"
completedAt	timestamp		요청 완료 시각	"2026-10-01T00:00:00Z"
failedAt	timestamp		요청 실패 시각	"2026-10-01T00:00:00Z"
cancelledAt	timestamp		요청 취소 시각	"2026-10-01T00:00:00Z"

데이터 추출 요청 (DataExport.Create)

Name	Type	Required	Description	Example
datasets	DataExportDataset[]	✅	추출 데이터셋 목록	["MERCHANTS"]
idempotencyKey	String		요청 중복 방지 식별자 기존 요청과 idempotencyKey가 동일한 요청을 제출하면 처리가 거부돼요. 불필요한 요청을 방지하기 위해 사용할 수 있어요.	"export-20261001-0001"
merchantIds	{ "include": Long[]?, "exclude": Long[]? }		추출 대상 매장 ID 지정하지 않을 경우, 이 앱이 연결된 매장의 데이터가 모두 추출돼요. - include 목록을 지정하면 해당 매장의 데이터만 추출돼요. 앱이 연결되지 않은 매장의 데이터는 추출되지 않아요. - exclude 목록을 지정하면 해당 매장의 데이터는 제외돼요. - include와 exclude 목록을 동시에 지정할 수 없어요.	{ "include": [42] }
schemaVersion	String		추출 결과 스키마 버전 스키마 버전을 참고해주세요.	"2026-10-01"
from	timestamp		조회 범위 시작점 기간 조회 데이터셋 추출 요청 시 필수로 지정해야 해요. 최근 90일 내역까지 추출 가능해요.	"2026-10-01T00:00:00Z"
to	timestamp		조회 범위 종료점 기간 조회 데이터셋 추출 요청 시 필수로 지정해야 해요. 최근 90일 내역까지 추출 가능해요.	"2026-10-01T00:00:00Z"
format	DataExportFormat		추출 결과 형식 현재 CSV 형식만 지원해요. 기본값으로 CSV가 적용돼요.	"CSV"

데이터셋 (DataExportDataset)

추출할 수 있는 데이터셋의 종류를 나타내요.

Value	Description
"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"	결제 내역
"UNDEFINED"

조회 시점 스냅샷 데이터셋: 추출 요청 시점의 데이터를 모두 제공해요.

• MERCHANTS
• CATALOG_CATEGORIES
• CATALOG_ITEMS
• CATALOG_OPTIONS
• CATALOG_OPTION_CHOICES
• CATALOG_ITEM_OPTIONS

기간 조회 데이터셋: 추출 요청에 설정한 조회 기간 내의 데이터를 제공해요. 추출 요청 시 조회 기간 (from, to)을 지정해야 하며, 최근 90일 내역까지 추출 가능해요. 내역의 수정 시각(updated_at)을 기준으로 조회되므로, 주문 또는 결제 내역의 경우 뒤늦게 환불/취소된 내역이 추출 결과에 포함될 수 있다는 점에 유의하세요.

• ORDERS
• ORDER_LINE_ITEMS
• ORDER_LINE_ITEM_OPTION_CHOICES
• ORDER_DISCOUNTS
• PAYMENTS

데이터 추출 결과 형식 (DataExportFormat)

Value	Description
"CSV"	.csv 파일
"UNDEFINED"

데이터 추출 처리 상태 (DataExportState)

요청 처리 상태를 나타내요. 완료된 데이터 추출 요청에서 결과 파일 목록을 확인할 수 있어요.

Value	Description
"REQUESTED"	요청됨
"RUNNING"	처리 중
"COMPLETED"	완료
"FAILED"	실패
"CANCELLED"	취소
"EXPIRED"	만료됨
"UNDEFINED"

데이터 추출 결과 파일 (DataExportFile)

Name	Type	Required	Description	Example
fileKey	String	✅	파일 식별자
dataset	DataExportDataset	✅	결과가 속한 데이터셋	"MERCHANTS"
filename	String	✅	파일명
format	DataExportFormat	✅	파일 형식	"CSV"
size	Long		파일 크기 (bytes)	1000000
rowCount	Long		파일에 속한 레코드 수	100

데이터 추출 결과 파일 다운로드 링크 (DataExportFileDownload)

Name	Type	Required	Description	Example
url	String	✅	파일 다운로드 링크
expiresAt	timestamp	✅	링크 만료 시각	"2026-10-01T00:00:00Z"

Methods

데이터 추출 요청

Property	Value
Method	POST
Path	/api-public/openapi/v1/data-export/exports
Response Type	DataExport
Description	데이터 추출을 요청해요. 데이터 추출에는 다음과 같은 제한이 적용돼요. - 동일한 앱에서 데이터 추출은 하루에 20회까지만 요청할 수 있어요. (요청 허용 횟수는 자정을 기준으로 초기화돼요.) - 데이터 추출은 동시에 5건까지만 요청할 수 있어요. - 추출 결과는 3일간 저장돼요. 만료된 추출 요청은 더 이상 결과 파일을 조회할 수 없어요. - 기간 조회 (주문 및 결제) 데이터셋은 최근 90일 내역까지만 추출 가능해요.

요청 파라미터

Parameter	Location	Type	Required	Description
export	Body	DataExport.Create	✅	데이터 추출 요청

데이터 추출 취소

Property	Value
Method	POST
Path	/api-public/openapi/v1/data-export/exports/{requestId}/cancel
Response Type	DataExport
Description	데이터 추출을 취소해요.

요청 파라미터

Parameter	Location	Type	Required	Description
requestId	Path	String	✅	요청 ID

데이터 추출 단건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/data-export/exports/{requestId}
Response Type	DataExport
Description	데이터 추출 요청을 하나 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Description
requestId	Path	String	✅	요청 ID

데이터 추출 목록 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/data-export/exports
Response Type	DataExport[]
Description	데이터 추출 요청 내역을 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
page	Query	Int		1	조회할 페이지
size	Query	Int		25	페이지 크기

데이터 추출 결과 파일 다운로드 링크 발급

Property	Value
Method	POST
Path	/api-public/openapi/v1/data-export/exports/{requestId}/files/{fileKey}/download
Response Type	DataExportFileDownload
Description	데이터 추출 결과 파일 다운로드 링크를 발급해요. 발급된 링크는 15분간 유효해요.

요청 파라미터

Parameter	Location	Type	Required	Description
requestId	Path	String	✅	요청 ID
fileKey	Path	String	✅	파일 식별자