DEV Community

Cover image for Hướng Dẫn Lập Trình Viên: Tích Hợp Thương Mại Điện Tử Với BigCommerce APIs
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Hướng Dẫn Lập Trình Viên: Tích Hợp Thương Mại Điện Tử Với BigCommerce APIs

#tutorial #api #webdev #programming

Tóm tắt

API của BigCommerce cho phép bạn quản lý sản phẩm, đơn hàng, khách hàng và các hoạt động cửa hàng bằng lập trình. Bạn xác thực bằng mã thông báo API (server side) hoặc OAuth (app), gọi các endpoint REST tại api.bigcommerce.com và xử lý webhook để nhận cập nhật thời gian thực. Để kiểm thử, hãy dùng Apidog để lưu các lệnh gọi API, xác thực phản hồi và chia sẻ collection với nhóm.

Dùng thử Apidog ngay hôm nay

Giới thiệu

BigCommerce cung cấp nền tảng cho 60.000+ cửa hàng online. Mỗi cửa hàng đều cần tích hợp tùy chỉnh: đồng bộ kho, xử lý đơn, quản lý khách hàng, thanh toán. Đó là lúc cần API.

BigCommerce có ba loại API: Storefront API (headless), Management API (backend), Payments API (giao dịch). Phổ biến nhất là Management API, dùng để thao tác sản phẩm, đơn hàng, khách hàng và các nghiệp vụ hậu trường.

Tài liệu khá lớn, bạn sẽ phải chuyển đổi giữa các phần xác thực, tham khảo, và hướng dẫn webhook để hoàn thành task.

Bài viết này tập trung vào những gì bạn sẽ dùng thực tế: sản phẩm, đơn hàng, khách hàng và webhook. Bạn sẽ học về xác thực, các mẫu request cơ bản, và cách kiểm thử tích hợp trước khi lên hệ thống thật.

💡 Nếu bạn xây dựng tích hợp BigCommerce, Apidog giúp thiết kế, kiểm thử và ghi lại các lệnh gọi API. Lưu request thành collection, dùng biến môi trường cho nhiều cửa hàng, xác thực phản hồi khớp schema. Phát hiện lỗi trước khi ảnh hưởng tới khách hàng.

Kiểm thử API BigCommerce của bạn với Apidog - miễn phí.

Kết thúc bài này, bạn sẽ:

  • Thiết lập xác thực BigCommerce chuẩn
  • Quản lý sản phẩm, biến thể, kho hàng
  • Xử lý đơn hàng và dữ liệu khách hàng
  • Thiết lập webhook cập nhật thời gian thực
  • Kiểm thử và document tích hợp với Apidog

Xác thực: truy cập vào cửa hàng của bạn

BigCommerce hỗ trợ hai cách xác thực, tùy theo ứng dụng bạn xây dựng.

Phương pháp 1: API Token (tích hợp tùy chỉnh)

Nếu bạn viết script hoặc service cho một shop, dùng API token.

Tạo tài khoản API:

  1. Vào admin store
  2. Settings → API Accounts → Create API Account
  3. Chọn “API Token V3/V2”
  4. Chọn scope cần thiết (Products, Orders, Customers, ...)
  5. Lưu thông tin đăng nhập

Bạn sẽ nhận được:

  • URL cửa hàng: mystore.mybigcommerce.com
  • Access token: abc123def456...
  • Client ID: abc123...
  • Client Secret: xyz789...

Gọi API lần đầu:

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 là đoạn sau /stores/ trong API path hoặc URL admin.

Phương pháp 2: OAuth (ứng dụng trên marketplace)

Nếu bạn viết app cho marketplace, dùng OAuth.

Quy trình OAuth:

  1. User bấm “Install” app của bạn trên marketplace
  2. BigCommerce redirect về callback URL với auth code
  3. Server trao đổi code lấy access token
  4. Lưu access token cho các lần gọi API sau

Trao đổi code lấy token:

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 dùng cho API
// context chứa store_hash
Enter fullscreen mode Exit fullscreen mode

Sử dụng access token:

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

Quản lý sản phẩm và danh mục

API Catalog V3 quản lý sản phẩm, biến thể, danh mục, thương hiệu.

Liệt kê sản phẩm 

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

Phản hồi:

{
  "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

Tạo sản phẩm 

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

Cập nhật biến thể sản phẩm

Các sản phẩm có tuỳ chọn (size, color) sẽ có biến thể (variant). Mỗi variant có thể có SKU, giá, kho riêng.

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

Quản lý kho hàng 

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

Cập nhật kho hàng biến thể:

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

Đơn hàng và hoàn thành

API Orders V2 dùng cho tạo, cập nhật và hoàn thành đơn hàng.

Liệt kê đơn hàng 

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

Phản hồi:

[
  {
    "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

Lấy chi tiết đơn hàng 

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

Lấy sản phẩm trong đơn hàng 

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

Cập nhật trạng thái đơn hàng 

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

Các status ID phổ biến:

  • 0: Chưa hoàn thành
  • 11: Đang chờ xử lý
  • 12: Đã hoàn thành
  • 5: Đã hủy
  • 4: Đã hoàn tiền

Tạo lô hàng (shipment) 

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

Khách hàng và phân khúc

API Customers V3 dùng để quản lý khách hàng, địa chỉ, nhóm khách hàng.

Liệt kê khách hàng 

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

Phản hồi:

{
  "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

Tạo khách hàng 

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

Cập nhật khách hàng 

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

Webhooks để cập nhật thời gian thực

Webhook giúp app của bạn nhận sự kiện (order, product, customer, ...) mà không cần polling.

Tạo webhook 

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

Scope phổ biến:

  • store/order/created - Đơn hàng mới
  • store/order/updated - Đơn hàng thay đổi
  • store/order/archived - Đơn hàng lưu trữ
  • store/product/created - Thêm sản phẩm
  • store/product/updated - Sửa sản phẩm
  • store/product/deleted - Xóa sản phẩm
  • store/customer/created - Khách hàng mới
  • store/inventory/updated - Kho thay đổi

Xác minh chữ ký webhook

BigCommerce ký webhook để xác thực nguồn gốc:

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')
  }

  // Xử lý webhook
  console.log('Đơn hàng đã được tạo:', req.body.data.id)
  res.status(200).send('OK')
})
Enter fullscreen mode Exit fullscreen mode

Kiểm thử API BigCommerce với Apidog

API BigCommerce yêu cầu tiêu đề và xác thực nhất quán. Kiểm thử thủ công bằng curl rất tốn thời gian. Apidog giúp tự động hóa quy trình.

apidog-testing

1. Thiết lập môi trường

Tạo biến môi trường cho từng shop:

# Sản xuất
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Thử nghiệm
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456
Enter fullscreen mode Exit fullscreen mode

2. Tập lệnh trước yêu cầu

Tự động thêm header xác thực:

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. Xác thực phản hồi

Kiểm tra response có đủ trường bắt buộc:

pm.test('Sản phẩm có các trường bắt buộc', () => {
  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('Phân trang hoạt động', () => {
  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

Kiểm thử API BigCommerce với Apidog - miễn phí.

Các lỗi và cách khắc phục phổ biến

401 Không được ủy quyền

Nguyên nhân: Token không hợp lệ/mất.

Khắc phục:

  1. Kiểm tra header X-Auth-Token
  2. Xác minh token còn hiệu lực
  3. Đảm bảo scope API đủ quyền

403 Bị cấm

Nguyên nhân: Token hợp lệ nhưng thiếu scope.

Khắc phục:

  1. Kiểm tra quyền tài khoản API
  2. Thêm scope bị thiếu (Products, Orders...)
  3. Tạo token mới với quyền mở rộng

404 Không tìm thấy

Nguyên nhân: Sai endpoint hoặc ID không tồn tại.

Khắc phục:

  1. Kiểm tra store hash
  2. Xem version API (v2 vs v3)
  3. Đảm bảo ID tồn tại

429 Quá nhiều yêu cầu

Nguyên nhân: Vượt giới hạn rate limit.

Khắc phục:

BigCommerce có giới hạn khác nhau theo endpoint.

  • Products: 10.000 req/h
  • Orders: 30.000 req/h Kiểm tra header X-Rate-Limit-Remaining, triển khai backoff. 
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 Thực thể không thể xử lý

Nguyên nhân: Lỗi validate nội dung request.

Khắc phục:

Kiểm tra response để biết chi tiết lỗi.

{
  "errors": {
    "price": "Giá phải lớn hơn không",
    "sku": "SKU đã tồn tại"
  }
}
Enter fullscreen mode Exit fullscreen mode

Các lựa chọn thay thế và so sánh

Tính năng BigCommerce Shopify WooCommerce
Phiên bản API V2 và V3 REST và GraphQL REST
Giới hạn tỷ lệ 10K-30K/giờ 2/phút (leaky bucket) Tùy thuộc vào máy chủ
Webhooks Có Có Có (plugin)
GraphQL Không Có Không
Chất lượng SDK Tốt Tuyệt vời Chỉ PHP
Nhiều cửa hàng Có Không Không

API V3 của BigCommerce nhất quán hơn so với Shopify, nhưng Shopify GraphQL linh hoạt hơn cho truy vấn phức tạp.

Các trường hợp sử dụng thực tế

Đồng bộ kho đa kênh:

Thương hiệu bán trên BigCommerce, Amazon, cửa hàng vật lý. Dùng API sản phẩm để đồng bộ kho, chống oversell. Apidog kiểm thử endpoint trước mỗi lần deploy.

Tự động hóa đơn hàng:

Công ty subscription box dùng webhook để tự động fulfill khi đơn hàng được tạo. API đơn hàng cập nhật tracking, kho tự động nhận danh sách pick hàng qua webhook.

Phân khúc khách hàng:

Ecommerce site dùng API customer để phân nhóm theo lịch sử mua. Khách VIP được thêm vào group đặc biệt với giá ưu đãi. Tích hợp này chạy hàng tuần bằng job schedule.

Kết luận

Bạn đã học:

  • Xác thực bằng API token (tích hợp) hoặc OAuth (marketplace app)
  • API Catalog V3 cho sản phẩm/biến thể
  • API Orders V2 cho quy trình đơn hàng/fulfillment
  • API Customers V3 cho dữ liệu khách
  • Webhook push cập nhật real-time
  • Kiểm thử & document với Apidog để tích hợp tin cậy

Các bước tiếp theo:

  1. Tạo API Account trên BigCommerce store
  2. Gọi API đầu tiên liệt kê sản phẩm
  3. Thiết lập webhook cho order creation
  4. Lưu và kiểm thử các lệnh gọi API trong Apidog
  5. Xây dựng tích hợp thực tế

Kiểm thử API BigCommerce với Apidog - miễn phí.

Câu hỏi thường gặp

Khác biệt giữa API V2 và V3?

V3 là phiên bản mới, nhất quán, dùng cho sản phẩm, danh mục, thương hiệu, khách hàng. V2 vẫn dùng cho Orders. Đa số tích hợp phải dùng cả hai.

Lấy store hash ở đâu?

Trong URL admin:

https://store-abc123.mybigcommerce.com/manage

abc123 là store hash. Hoặc trong API Account settings.

Có dùng API trên trial store được không?

Có, trial store có full API. Phù hợp cho dev & test.

Rate limit API là bao nhiêu?

Tùy endpoint: Products: 10.000 req/h, Orders: 30.000 req/h. Xem X-Rate-Limit-Remaining trong response header.

Xử lý phân trang như thế nào?

Dùng query param page, limit. Mặc định 50. Xem meta.pagination trong response để lặp toàn bộ dữ liệu.

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

Tải ảnh sản phẩm qua API thế nào?

Dùng endpoint sau:

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

Xử lý đa tiền tệ và nhiều cửa hàng ra sao?

BigCommerce chỉ có 1 currency cơ bản. Đa tiền tệ xử lý ở frontend, không qua API. Nhiều cửa hàng: tạo API account riêng, dùng nhiều môi trường trong Apidog.

Nếu webhook endpoint bị lỗi thì sao?

BigCommerce retry các webhook lỗi bằng exponential backoff. Sau 5 lần lỗi trong 24h, webhook bị vô hiệu hóa. Hãy giám sát và cảnh báo endpoint webhook.

Top comments (0)