Data Export API

개요

데이터 내보내기 (Data Export) API는 주문·결제 내역, 매장 카탈로그 등 토스 POS가 제공하는 데이터를 대량으로 조회 및 추출할 수 있는 API예요.

데이터 내보내기를 요청하면, 요청한 데이터셋에 대한 자료를 추출하여 다운로드 링크를 제공해요. 링크를 통해 내려받은 파일을 자사 시스템에 적재하거나, 분석 용도로 활용하거나, 대시보드를 구성하는 등 다양한 용도로 활용할 수 있어요.

주문, 결제, 카탈로그 등 일반적인 API 호출과 동일한 데이터 조회가 가능하지만, Data Export API는 장기간·대량 데이터 조회 및 집계에 적합해요. 많은 매장의 데이터를 한 번에 조회해야 하거나, 호출량 제한으로 인해 데이터 조회에 어려움이 있는 경우 Data Export API를 활용해보세요.

이런 경우에 추천해요

• 장기간 주문·결제 내역 등 대량의 데이터가 필요한 경우
• 브랜드·프랜차이즈 등 다수 가맹점을 보유한 경우
• ERP, 대시보드 등 추출한 데이터를 자사 시스템에 적재하여 추가로 활용하려는 경우

이런 경우에는 추천하지 않아요

아래의 경우에 해당된다면 주문 API, 결제 API 등에서 제공하는 조회 기능을 활용해주세요.

• 실시간으로 갱신되는 데이터 조회가 필요한 경우
• 1·2개 등 소수 가맹점의 데이터를 다루는 경우

활용 사례

• 본사 통합 매출 대시보드: 브랜드·프랜차이즈 본사에서 가맹점 매출 데이터를 일별·매장별·상품별 집계하여 대시보드를 구성해요.
• 회계 시스템 연동: 토스 POS 결제 내역을 추출하여 회계 전표를 구성을 자동화해요.
• 정산 관리: 토스 POS 결제 내역을 추출하여 결제 정산 주체 및 결제수단별 승인·취소 내역을 확인하고 대사에 활용해요.
• 메뉴·상품 관리: 카탈로그 데이터를 추출하여 상품별 코드·가격 등을 관리해요.

시작하기

Data Export API도 Open API와 동일한 방법으로 사용할 수 있어요. Open API - 튜토리얼 문서를 참고하여 환경 설정을 완료해주세요.

WARNING

Data Export API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요. Data Export API를 사용하려면 개발자센터 지원 이메일로 아래와 같은 정보를 전달해 권한을 요청해주세요.

• 애플리케이션 ID
• 연동 대상 본사(브랜드·프랜차이즈)명, 예상 매장 수
• 추출 데이터 사용 목적
• 사용하려는 데이터셋 및 추출 주기 (예: ORDERS, PAYMENTS / 매일)

데이터 추출 요청

매장(MERCHANTS) 데이터셋을 추출 요청해볼게요.

curl -X 'POST' \
  'https://open-api.tossplace.com/api-public/openapi/v1/data-export/exports' \
  -H 'x-access-key: ${ACCESS_KEY}' \
  -H 'x-secret-key: ${SECRET_KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "export": {
    "datasets": [
      "MERCHANTS"
    ],
    "merchantIds": {
      "include": [
        ${MERCHANT_ID}
      ]
    },
    "schemaVersion": "2026-10-01",
    "format": "CSV"
  }
}'

• merchantIds 파라미터에 추출 대상 매장 ID 목록을 지정해주세요. 지정하지 않을 경우, 이 앱이 연결된 매장의 데이터가 모두 추출돼요. 앱이 연결되지 않은 매장의 정보는 추출할 수 없어요.

응답에서 요청이 정상적으로 처리되었는지 확인할 수 있어요.

{
  "resultType": "SUCCESS",
  "error": null,
  "success": {
    "requestId": "<request-id>",
    "datasets": [
      "MERCHANTS"
    ],
    "format": "CSV",
    "schemaVersion": "2026-10-01",
    "state": "REQUESTED",
    // ...
  }
}

추출 요청 상태 확인

추출 요청 상태를 확인해볼게요. 앞서 응답에서 받은 requestId를 사용해 추출 요청 상태를 확인할 수 있어요.

curl -X 'GET' \
  'https://open-api.tossplace.com/api-public/openapi/v1/data-export/exports/<request-id>' \
  -H 'x-access-key: ${ACCESS_KEY}' \
  -H 'x-secret-key: ${SECRET_KEY}'

{
  "resultType": "SUCCESS",
  "error": null,
  "success": {
    "requestId": "<request-id>",
    "datasets": [
      "MERCHANTS"
    ],
    "format": "CSV",
    "schemaVersion": "2026-10-01",
    "state": "RUNNING",
    // ...
  }
}

추출이 완료될 때까지 수 분 정도 소요될 수 있어요. 추출 요청 상태가 COMPLETED로 변경될 떄까지 기다려주세요.

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

추출이 완료되면 상태가 COMPLETED로 변하고, 결과 파일 목록을 확인할 수 있어요.

{
  "requestId": "<request-id>",
  "datasets": [
    "MERCHANTS"
  ],
  "format": "CSV",
  "schemaVersion": "2026-10-01",
  "state": "COMPLETED",
  "requestedAt": "<requested-at>",
  "expiresAt": "<expires-at>",
  "completedAt": "<completed-at>",
  "files": [
    {
      "fileKey": "<file-key>",
      "dataset": "MERCHANTS",
      "filename": "MERCHANTS.csv",
      "format": "CSV",
      "size": 159,
      "rowCount": 1
    }
  ],
  // ...
}

requestId와 fileKey를 사용하여 결과 파일을 다운로드 받을 수 있는 링크를 발급해주세요. 추출 요청 이후 3일이 지나면 더 이상 링크를 발급할 수 없어요.

curl -X 'POST' \
  'https://open-api.tossplace.com/api-public/openapi/v1/data-export/exports/<request-id>/files/<file-key>/download-link' \
  -H 'x-access-key: ${ACCESS_KEY}' \
  -H 'x-secret-key: ${SECRET_KEY}'

{
  "resultType": "SUCCESS",
  "error": null,
  "success": {
    "url": "<download-link>",
    "expiresAt": "<expires-at>"
  }
}

추출 결과 확인

링크를 통해 결과 파일을 다운로드 받을 수 있어요. 링크는 발급 이후 15분 동안 유효해요.

파일은 CSV 형식으로 제공돼요. 상세 형식 및 데이터셋별 속성 정보는 데이터 형식 상세 문서를 참고해주세요.

결과 예시:

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

데이터 형식 상세

Data Export API에서 제공하는 데이터셋과 상세 속성 정보는 데이터 형식 상세 문서를 참고해주세요.

API 상세

Data Export - API 상세 문서를 참고해주세요.