Open API 공통 가이드

개요

토스플레이스 Open API는 서버 간 안정적인 데이터 연동을 위한 API예요. 토스 POS에서 제공하는 주문, 결제, 카탈로그 등 다양한 기능을 외부 서비스와 통합할 수 있어요.

Open API를 사용하려면 토스플레이스 개발자센터에 가입하고 앱을 생성해야 해요. 자세한 과정은 Open API 개발 시작하기 (튜토리얼) 문서를 참고해주세요.

토스플레이스 Open API 규약은 이 페이지 외에도 다음 위치에서 확인할 수 있어요.

• API 문서
• OAS 문서 (OpenAPI Specification)

토스플레이스 Open API 변경 내역은 변경 이력 페이지를 참고해주세요.

HTTP API 공통

HTTP 요청 및 응답 Header

• 인증
  • 인증을 위해 개발자센터에서 발급한 API key pair를 사용해요. HTTP 요청 header를 다음과 같이 지정해야 해요.
    • x-access-key: <API Access Key>
    • x-secret-key: <API Secret Key>
• 요청 및 응답 형태
  • 요청과 응답은 모두 Content-Type: application/json 형태여야 해요.

응답 코드 및 Body 형태

• 응답 코드 : API가 성공적으로 응답할 시 응답 코드 200을 반환해요. 응답 실패 시 실패 이유에 따라 401, 429, 500 등 상응하는 응답 코드를 반환해요.
• 응답 형태 : 모든 HTTP API 응답 body는 기본적으로 아래 형태와 같아요.

성공 응답

{
  "resultType": "SUCCESS",
  "success": <결과>
}

실패 응답

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "4010",
    "reason": "에러 메시지",
    "data": {/* ... */}
  }
}

매장 ID

API 요청 경로에 사용되는 매장 ID (merchantId) 는 매장을 식별하는 고유 값이에요. 토스 POS에 로그인할 때 사용되는 매장고유번호(10자리 숫자)와는 서로 다른 값이니, 혼동하지 않도록 유의해주세요.

시각 (timestamp)

API 요청과 응답에 사용되는 모든 시각 (timestamp) 타입은 ISO 8601 형태(예: 2025-09-01T00:00:00Z)의 문자열이에요.

UNDEFINED 타입

Enum 타입의 "UNDEFINED"는 상태가 추가될 시 하위호환을 위해 제공되는 값이에요. 실제 존재하는 상태는 아니며, 요청에는 사용하지 마세요.

Pagination

너무 많은 정보를 한 번에 조회하지 않도록 목록 조회 시 페이지네이션을 사용해요. 페이지 기반으로 목록을 조회할 수 있으며, page ,size , sortOrder 파라미터를 사용해요.

GET https://open-api.tossplace.com/api-public/openapi/v1/merchants/{merchantId}/order/orders?page=1&size=100&sortOrder=DESC

• page : 조회할 페이지예요. 1페이지가 목록의 시작이에요.
• size : 페이지의 크기예요. 최소 1, 최대 500 값을 사용할 수 있으며 기본값은 100이에요.
• sortOrder : 목록의 정렬 순서예요. "ASC", "DESC" 값을 사용할 수 있어요.

에러 처리

API 에러 응답은 HTTP 상태 코드와 함께 구체적인 에러 정보를 제공해요.

{
  "resultType": "FAIL",
  "error": {
    "errorCode": "4010",
    "reason": "에러 메시지"
  }
}

ALPHA 기능

문서에서 ALPHA 표시가 붙은 Type, Method, Event 및 세부 필드는 사용이 가능하지만, 추후 별도 공지 없이 제공이 중단되거나 기능이 변경될 수 있어요. ALPHA 항목 사용 시 주의가 필요하며, Open API 변경 이력을 주기적으로 확인하여 변경 사항을 확인해야 해요.

호출량 제한

Open API를 안정적으로 제공하기 위해 Open API의 시간당 호출량을 제한하고 있어요. 허용된 호출량을 초과한 요청은 거부되며 HTTP 429 응답 코드를 반환해요.

GET https://open-api.tossplace.com/api-public/openapi/v1/merchants/{merchantId}
x-access-key: YOUR_ACCESS_KEY
x-secret-key: YOUR_SECRET_KEY
Content-Type: application/json

HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: <timestamp>

위 예시처럼, HTTP 응답 header를 통해 호출량 제한에 관한 정보를 얻을 수 있어요.

HTTP 응답 header	Type	설명	예시
x-ratelimit-limit	number	허용된 최대 호출량이에요.	100
x-ratelimit-remaining	number	이 요청 이후 남은 허용된 호출량이에요.	99
x-ratelimit-reset	timestamp (epoch milliseconds)	호출량 제한 초기화 시각으로, 이 시각 이후에 API를 더 호출할 수 있어요.	1700000000000

호출량 제한은 Token Bucket 알고리즘으로 작동해요.

• Open API 호출 시 토큰을 1개 소비해요. 토큰이 없는 경우 호출량 제한으로 인해 429 응답을 받아요.
• 토큰은 1초당 10개씩 충전되며, 최대 100개까지 충전돼요.
  • 예시) Open API를 연속하여 호출하는 경우, 즉시 100개의 요청은 성공해요. 이후 1초가 지나야 다음 10개 요청이 성공해요.
  • x-ratelimit-remaining과 x-ratelimit-reset 응답 header를 통해 호출 주기를 조정하는 것을 권장해요.
• 토큰은 매장별로 관리돼요.
  • 즉, 호출량 제한은 각 매장별로 적용돼요. 특정 매장에 대한 요청에서 429 응답을 받더라도, 다른 매장에 대한 요청은 정상적으로 처리될 수 있어요.

요청 추적

모든 Open API 응답은 x-toss-event-id HTTP 헤더를 포함해요. 이 값은 요청 추적 및 문의 시 필요해요.

GET https://open-api.tossplace.com/api-public/openapi/v1/merchants/{merchantId}
x-access-key: YOUR_ACCESS_KEY
x-secret-key: YOUR_SECRET_KEY
Content-Type: application/json

HTTP/1.1 200 OK
x-toss-event-id: <EVENT_ID>
// ...

Open API 사용 중 문의가 있으시다면, x-toss-event-id 헤더 값을 함께 제공해주세요. 기술 지원 중 개별 요청을 추적할 때 도움이 돼요.