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": {/* ... */}
  }
}

시각 (timestamp)

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

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": "에러 메시지"
  }
}

호출량 제한

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 헤더 값을 함께 제공해주세요. 기술 지원 중 개별 요청을 추적할 때 도움이 됩니다.