e
EBUT Developer Portal 이벗 API 통합 문서 · v3 · api.ebut.co.kr
시작하기 · Quickstart

5분 만에 첫 호출하기

이벗(EBUT) API v3 의 첫 호출을 5분 안에 완료할 수 있도록 안내합니다. 키 발급 → 헤더 구성 → curl 호출 → 응답 처리 4단계만 따라오시면 됩니다.

1. API Key 발급 신청

help@ebut.co.kr 로 다음 정보를 보내주시면 무료 test 키를 받으실 수 있습니다. (운영 키 발급은 요금제 페이지 참고)

test 키 vs live 키 ebut_test_xxxx 는 실거래 영향이 없는 테스트용입니다. ebut_live_xxxx 는 운영 키로, 무료 티어에서는 발급되지 않습니다. 자세한 차이는 Pricing 참고.

2. 공통 헤더 구성

모든 요청은 아래 헤더를 포함합니다. X-Service 는 호출하는 서비스를 명시하며, 게이트웨이 라우팅·로깅에 활용됩니다.

헤더 값 / 예시
X-API-Keyebut_test_xxxxxxxxxxxxxxxx
Content-Typeapplication/json
Acceptapplication/json
X-Servicewms · manager · cam · pay

3. 첫 호출 — 주문 목록 조회

이벗매니저의 본인 주문 10건을 조회하는 가장 단순한 예제입니다. 매니저 v3 는 토큰에서 셀러를 자동 추출하므로 별도 파라미터가 필요 없습니다.

cURL

curl -X GET "https://api.ebut.co.kr/v3/manager/orders?page=1&size=10" \
  -H "X-API-Key: ebut_test_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "X-Service: manager"

Node.js (fetch)

const response = await fetch(
  "https://api.ebut.co.kr/v3/manager/orders?page=1&size=10",
  {
    method: "GET",
    headers: {
      "X-API-Key": "ebut_test_xxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
      "Accept": "application/json",
      "X-Service": "manager"
    }
  }
);
const result = await response.json();
console.log(result);

Python (requests)

import requests

url = "https://api.ebut.co.kr/v3/manager/orders"
headers = {
    "X-API-Key": "ebut_test_xxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-Service": "manager",
}
params = {"page": 1, "size": 10}

response = requests.get(url, headers=headers, params=params, timeout=10)
print(response.json())

4. 응답 처리

응답은 항상 success 필드로 시작합니다. 성공 / 실패를 먼저 판단한 뒤 분기하세요.

성공 응답

{
  "success": true,
  "data": [
    {
      "order_no": "20260614-000001",
      "mall_product_name": "유기농 사과 5kg",
      "order_status_code": 100,
      "registered_date": "2026-06-14 11:17:23"
    }
  ],
  "pagination": {
    "page": 1,
    "size": 10,
    "total": 152,
    "total_pages": 16,
    "has_next": true
  }
}

실패 응답

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_TOKEN",
    "message": "API Key 가 유효하지 않습니다."
  }
}

분기 처리 예시 (Node.js)

const result = await response.json();

if (!result.success) {
  console.error("[" + result.error.code + "] " + result.error.message);
  if (response.status === 401) {
    // 키 재발급 또는 토큰 갱신
  }
  if (response.status === 429) {
    // Rate Limit — Retry-After 만큼 대기 후 재시도
  }
  return;
}

// 정상 처리
for (const order of result.data) {
  console.log(order.order_no, order.mall_product_name);
}

5. 자주 만나는 에러

에러 코드 HTTP 원인 / 해결
AUTH_INVALID_TOKEN401키 오타 또는 발급 안 된 키 — 헤더 확인
AUTH_MISSING_TOKEN401X-API-Key 헤더 누락
REQUIRED_PARAMETER400필수 파라미터 누락 — endpoint 문서 확인
RATE_LIMIT_EXCEEDED429분당 한도 초과 — Rate Limits 참고

전체 에러 코드는 에러 코드 페이지 에서 확인할 수 있습니다.

다음 단계