DEV Community

Cover image for 빅커머스 API 사용법: 개발자를 위한 이커머스 통합 가이드
Rihpig
Rihpig

Posted on • Originally published at apidog.com

빅커머스 API 사용법: 개발자를 위한 이커머스 통합 가이드

핵심 요약

BigCommerce API를 활용하면 제품, 주문, 고객, 그리고 전체 스토어 운영을 코드로 자동화할 수 있습니다. 인증은 API 토큰(서버) 또는 OAuth(앱) 방식으로 처리하며, api.bigcommerce.com REST 엔드포인트에 요청을 보냅니다. 실시간 처리는 웹훅으로 대응하세요. 테스트 및 검증, 협업에는 Apidog를 사용해 요청을 저장하고 응답을 검증하며, 팀과 컬렉션을 공유할 수 있습니다.

지금 Apidog로 시작하기

소개

BigCommerce는 60,000개 이상의 온라인 스토어를 지원합니다. 각 스토어는 재고 동기화, 주문 처리, 고객 관리, 결제 처리 등 맞춤형 통합이 필요하며, 여기에 API가 사용됩니다.

이 플랫폼은 세 가지 API 유형을 제공합니다: 스토어프론트 API(헤드리스 커머스), 관리 API(백엔드 운영), 결제 API(거래). 대부분의 개발자는 관리 API를 사용합니다. 이 API는 제품, 주문, 고객 및 모든 백엔드 작업을 처리합니다.

학습 곡선이 가파르지는 않지만, 문서는 다소 부담스러울 수 있습니다. 간단한 작업을 완료하기 위해서도 인증 문서, API 참조, 그리고 웹훅 가이드 사이를 오가야 할 것입니다.

이 가이드는 실제로 사용하게 될 내용에 중점을 둡니다. 제품, 주문, 고객, 그리고 웹훅입니다. 인증, 일반적인 패턴, 그리고 실제 스토어에 적용하기 전에 통합을 테스트하는 방법을 배우게 될 것입니다.

💡BigCommerce 통합을 구축 중이라면, Apidog가 API 호출을 설계, 테스트 및 문서화하는 데 도움이 됩니다. 요청을 컬렉션으로 저장하고, 다양한 스토어에 환경 변수를 사용하며, 응답이 예상 스키마와 일치하는지 검증할 수 있습니다. 이는 실제 고객에게 영향을 미치기 전에 오류를 잡아냅니다.

Apidog로 BigCommerce API 테스트하세요 - 무료

이 가이드의 끝에 도달하면 다음을 할 수 있습니다:

  • BigCommerce 인증을 올바르게 설정
  • 제품, 변형, 재고 관리
  • 주문 처리 및 고객 데이터 관리
  • 실시간 업데이트용 웹훅 설정
  • Apidog로 통합 테스트 및 문서화

인증: 스토어에 액세스하기

BigCommerce는 두 가지 인증 방식을 지원합니다.

방법 1: API 토큰 (맞춤 통합용)

단일 스토어에 연동하는 스크립트 또는 서비스는 API 토큰을 사용하세요.

API 계정 생성

  1. 스토어 관리자 패널 → 설정 → API 계정 → API 계정 생성
  2. “V3/V2 API 토큰” 선택
  3. 필요한 스코프(제품, 주문, 고객 등) 선택
  4. 자격 증명 저장

얻는 정보

  • 스토어 URL: mystore.mybigcommerce.com
  • 액세스 토큰: abc123def456...
  • 클라이언트 ID, 클라이언트 시크릿

API 호출 예시

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"
Enter fullscreen mode Exit fullscreen mode

store-hash는 관리자 URL에서 /stores/ 다음에 오는 값입니다.

방법 2: OAuth (마켓플레이스 앱용)

마켓플레이스 앱을 구축할 때는 OAuth를 사용합니다.

OAuth 플로우

  1. 사용자가 앱 설치 클릭
  2. 인증 코드와 함께 콜백 URL로 리디렉션
  3. 서버에서 코드 → 액세스 토큰 교환
  4. 토큰 저장

토큰 교환 예시

const response = await fetch('https://login.bigcommerce.com/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    client_id: process.env.BC_CLIENT_ID,
    client_secret: process.env.BC_CLIENT_SECRET,
    redirect_uri: 'https://yourapp.com/auth/callback',
    grant_type: 'authorization_code',
    code: authCode,
    scope: 'store_v2_default store_v3_products'
  })
})

const { access_token, context } = await response.json()
// access_token은 API 호출에 사용
// context에는 store_hash 포함
Enter fullscreen mode Exit fullscreen mode

API 호출

curl -X GET "https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products" \
  -H "X-Auth-Token: {access-token}" \
  -H "Content-Type: application/json"
Enter fullscreen mode Exit fullscreen mode

제품 및 카탈로그 관리

제품 목록 가져오기 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

응답 예시

{
  "data": [
    {
      "id": 174,
      "name": "Plain T-Shirt",
      "type": "physical",
      "sku": "PLAIN-T",
      "price": 29.99,
      "sale_price": 24.99,
      "inventory_level": 150,
      "inventory_tracking": "product",
      "is_visible": true,
      "categories": [23, 45],
      "brand_id": 12
    }
  ],
  "meta": {
    "pagination": {
      "total": 500,
      "count": 50,
      "page": 1,
      "per_page": 50
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

제품 생성 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products
X-Auth-Token: {token}
Content-Type: application/json

{
  "name": "Premium Hoodie",
  "type": "physical",
  "sku": "HOODIE-PREM",
  "price": 79.99,
  "description": "Premium cotton blend hoodie",
  "weight": 1.5,
  "width": 20,
  "height": 28,
  "depth": 2,
  "inventory_level": 100,
  "inventory_tracking": "product",
  "is_visible": true,
  "categories": [23]
}
Enter fullscreen mode Exit fullscreen mode

제품 변형 업데이트

옵션(크기, 색상)별 변형 업데이트 예시:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "sku": "HOODIE-PREM-BLK-M",
  "price": 79.99,
  "inventory_level": 50,
  "option_values": [
    { "option_display_name": "Color", "label": "Black" },
    { "option_display_name": "Size", "label": "Medium" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

재고 관리 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "inventory_level": 75
}
Enter fullscreen mode Exit fullscreen mode

또는 변형의 경우:

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/variants/{variant-id}
Content-Type: application/json

{
  "inventory_level": 25
}
Enter fullscreen mode Exit fullscreen mode

주문 및 이행

주문 목록 가져오기 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

응답 예시

[
  {
    "id": 115,
    "status": "Awaiting Fulfillment",
    "status_id": 11,
    "customer_id": 45,
    "date_created": "2026-03-24T10:30:00+00:00",
    "subtotal_ex_tax": 149.99,
    "total_inc_tax": 162.49,
    "items_total": 2,
    "items_shipped": 0,
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "street_1": "123 Main St",
      "city": "Austin",
      "state": "Texas",
      "zip": "78701",
      "country": "United States"
    }
  }
]
Enter fullscreen mode Exit fullscreen mode

주문 상세 정보 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

주문 제품 정보 

GET https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/products
X-Auth-Token: {token}
Enter fullscreen mode Exit fullscreen mode

주문 상태 업데이트 

PUT https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "status_id": 12
}
Enter fullscreen mode Exit fullscreen mode

주요 상태 ID

  • 0: 불완전
  • 11: 이행 대기 중
  • 12: 완료됨
  • 5: 취소됨
  • 4: 환불됨

배송(이행) 생성 

POST https://api.bigcommerce.com/stores/{store-hash}/v2/orders/{order-id}/shipments
X-Auth-Token: {token}
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "UPS",
  "shipping_method": "UPS Ground",
  "items": [
    {
      "order_product_id": 234,
      "quantity": 1
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

고객 및 세분화

고객 목록 

GET https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Accept: application/json
Enter fullscreen mode Exit fullscreen mode

응답 예시

{
  "data": [
    {
      "id": 45,
      "email": "john.doe@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "company": "Acme Corp",
      "phone": "512-555-1234",
      "customer_group_id": 1,
      "notes": "VIP customer",
      "tax_exempt_category": "",
      "date_created": "2025-11-15T09:30:00+00:00",
      "date_modified": "2026-03-20T14:22:00+00:00"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

고객 생성 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/customers
X-Auth-Token: {token}
Content-Type: application/json

{
  "email": "jane.smith@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "512-555-5678",
  "customer_group_id": 2
}
Enter fullscreen mode Exit fullscreen mode

고객 업데이트 

PUT https://api.bigcommerce.com/stores/{store-hash}/v3/customers/{customer-id}
X-Auth-Token: {token}
Content-Type: application/json

{
  "notes": "Repeat customer - priority support",
  "customer_group_id": 3
}
Enter fullscreen mode Exit fullscreen mode

실시간 업데이트를 위한 웹훅

웹훅은 스토어 이벤트(주문, 제품, 고객 등) 발생 시 앱에 실시간으로 알립니다.

웹훅 생성 

POST https://api.bigcommerce.com/stores/{store-hash}/v3/hooks
X-Auth-Token: {token}
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://yourapp.com/webhooks/orders",
  "is_active": true
}
Enter fullscreen mode Exit fullscreen mode

대표 스코프

  • store/order/created – 새 주문
  • store/order/updated – 주문 상태 변경
  • store/product/created – 제품 추가
  • store/product/updated – 제품 수정

웹훅 서명 검증 

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

app.post('/webhooks/orders', (req, res) => {
  const signature = req.headers['x-bc-webhook-signature']
  const payload = JSON.stringify(req.body)

  if (!verifyWebhook(payload, signature, process.env.BC_CLIENT_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // 웹훅 처리
  console.log('Order created:', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Apidog로 BigCommerce API 테스트하기

BigCommerce API는 인증, 헤더 관리 등 반복 작업이 많습니다. curl로 직접 테스트하는 대신 Apidog로 프로세스를 간편하게 자동화하세요.

Apidog BigCommerce 테스트 예시

1. 환경 설정

각 스토어별 환경 변수 지정:

# 운영 스토어
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# 스테이징 스토어
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. 사전 요청 스크립트

인증 헤더 자동화:

pm.request.headers.add({
  key: 'X-Auth-Token',
  value: pm.environment.get('ACCESS_TOKEN')
})
pm.request.headers.add({
  key: 'Accept',
  value: 'application/json'
})
Enter fullscreen mode Exit fullscreen mode

3. 응답 유효성 검사

필수 필드 및 페이지네이션 테스트:

pm.test('Products have required fields', () => {
  const response = pm.response.json()
  response.data.forEach(product => {
    pm.expect(product).to.have.property('id')
    pm.expect(product).to.have.property('name')
    pm.expect(product).to.have.property('price')
    pm.expect(product.price).to.be.above(0)
  })
})

pm.test('Pagination works', () => {
  const response = pm.response.json()
  pm.expect(response.meta.pagination).to.have.property('total')
  pm.expect(response.meta.pagination.page).to.eql(1)
})
Enter fullscreen mode Exit fullscreen mode

Apidog로 BigCommerce API 테스트하기 - 무료

일반적인 오류 및 해결 방법

401 권한 없음

  • 원인: 토큰 누락/오류
  • 해결: X-Auth-Token 헤더와 토큰 유효성, 스코프 확인

403 접근 금지

  • 원인: 권한 부족
  • 해결: API 계정 권한 및 스코프 추가, 새 토큰 발급

404 찾을 수 없음

  • 원인: 잘못된 엔드포인트, 리소스 없음
  • 해결: 스토어 해시, API 버전(v2/v3), 리소스 ID 확인

429 너무 많은 요청

  • 원인: 요청 제한 초과
  • 해결: 제품: 시간당 10,000회, 주문: 30,000회 제한. X-Rate-Limit-Remaining 체크, 백오프 구현 
async function callWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fn()
    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Rate-Limit-Reset')
      await new Promise(r => setTimeout(r, retryAfter * 1000))
    } else {
      return response
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

422 처리할 수 없는 엔티티

  • 원인: 요청 본문 유효성 오류
  • 해결: 응답 상세 오류 확인 
{
  "errors": {
    "price": "가격은 0보다 커야 합니다",
    "sku": "SKU가 이미 존재합니다"
  }
}
Enter fullscreen mode Exit fullscreen mode

대안 및 비교

기능 BigCommerce Shopify WooCommerce
API 버전 관리 V2 및 V3 REST 및 GraphQL REST
요청 제한 시간당 1만-3만 분당 2회 (리키 버킷) 호스팅에 따라 다름
웹훅 예 예 예 (플러그인)
GraphQL 아니요 예 아니요
SDK 품질 좋음 우수함 PHP 전용
멀티 스토어 예 아니요 아니요

BigCommerce V3 API는 Shopify에 비해 일관성이 높고, Shopify의 GraphQL은 복잡한 쿼리에 더 유연합니다.

실제 사용 사례

다채널 재고 동기화

브랜드가 BigCommerce, Amazon, 오프라인 매장 등 여러 채널에서 판매할 때, 제품 API로 재고를 동기화하여 과다 판매를 방지합니다. Apidog로 동기화 엔드포인트를 배포 전 자동 테스트하세요.

주문 자동화

구독 박스 회사는 주문 웹훅으로 자동 이행을 트리거하고, 주문 API로 추적 번호를 업데이트합니다. 창고는 웹훅 핸들러에서 피킹 리스트를 자동 수신합니다.

고객 세분화

구매 내역 기반으로 고객 API로 VIP, 일반 그룹 분류 및 혜택을 자동 적용합니다. 예약 작업으로 주기적 세분화 자동화가 가능합니다.

결론

이 글에서는 다음을 다뤘습니다:

  • 인증: API 토큰(간단), OAuth(앱)
  • V3 카탈로그 API: 제품·변형 관리
  • V2 주문 API: 주문·이행 처리
  • V3 고객 API: 고객 데이터 관리
  • 웹훅: 실시간 업데이트
  • Apidog로 테스트 및 문서화

다음 단계

  1. BigCommerce 스토어에서 API 계정 생성
  2. 제품 목록 API 호출
  3. 주문 웹훅 설정
  4. Apidog에 API 호출 저장
  5. 통합 구현 시작

Apidog로 BigCommerce API 테스트하기 - 무료

자주 묻는 질문

V2와 V3 API의 차이점은?

V3는 최신이며 일관성 높습니다(제품, 카테고리, 브랜드, 고객). V2는 주문 등 일부 영역에서 사용됩니다. 두 버전을 혼용해야 할 수 있습니다.

스토어 해시는 어디서 찾나요?

BigCommerce 관리자 URL의 https://store-abc123.mybigcommerce.com/manage에서 abc123이 해시입니다. API 계정 생성 시에도 확인 가능합니다.

체험 스토어에서도 API 사용 가능한가요?

예. 체험 스토어도 전체 API 권한 제공. 개발·테스트에 적합합니다.

요청 제한은?

제품: 시간당 10,000회, 주문: 30,000회. 응답 헤더의 X-Rate-Limit-Remaining 확인.

페이지네이션 처리 방법

page, limit 파라미터 사용. 응답의 meta.pagination 확인 후 반복 요청.

let allProducts = []
let page = 1

while (true) {
  const response = await fetch(
    `${baseUrl}/v3/catalog/products?page=${page}&limit=100`,
    { headers: { 'X-Auth-Token': token } }
  )
  const data = await response.json()
  allProducts.push(...data.data)

  if (page >= data.meta.pagination.total_pages) break
  page++
}
Enter fullscreen mode Exit fullscreen mode

API로 제품 이미지 업로드 가능?

예. 제품 이미지 엔드포인트 사용.

POST https://api.bigcommerce.com/stores/{store-hash}/v3/catalog/products/{product-id}/images
Content-Type: application/json

{
  "image_url": "https://example.com/image.jpg",
  "is_thumbnail": true
}
Enter fullscreen mode Exit fullscreen mode

통화/멀티 스토어 관리

스토어별 기본 통화만 사용 가능. 다중 스토어는 각각 API 계정 생성, Apidog에서 각 환경 별 관리.

웹훅 엔드포인트 다운 시?

BigCommerce는 지수 백오프로 재시도, 24시간 내 5회 실패 시 웹훅 비활성화. 엔드포인트 모니터링 필수.

Top comments (0)