Blog

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

Ashley Innocent

Ashley Innocent

24 tháng 3 2026

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

Apidog cho doanh nghiệp

Triển khai tại chỗ

SSO & RBAC

Tuân thủ SOC 2

Khám phá Apidog Enterprise

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 cửa hàng một cách có lập trình. Bạn xác thực bằng mã thông báo API (cho phía máy chủ) hoặc OAuth (cho ứng dụng), gọi các điểm cuối REST tại api.bigcommerce.com và xử lý webhook để cập nhật theo thời gian thực. Để kiểm thử, hãy sử dụng Apidog để lưu các lệnh gọi API của bạn, xác thực phản hồi và chia sẻ bộ sưu tập với nhóm của bạn.

Giới thiệu

BigCommerce đang cung cấp nền tảng cho hơn 60.000 cửa hàng trực tuyến. Mỗi cửa hàng đều cần các tích hợp tùy chỉnh – đồng bộ hóa kho hàng, xử lý đơn hàng, quản lý khách hàng, xử lý thanh toán. Đó là lúc các API phát huy tác dụng.

Nền tảng này cung cấp ba loại API: Storefront API (thương mại không giao diện), Management API (các hoạt động backend) và Payments API (giao dịch). Hầu hết các nhà phát triển làm việc với Management API. API này xử lý sản phẩm, đơn hàng, khách hàng và mọi thứ diễn ra ở hậu trường.

Đường cong học tập không quá dốc, nhưng tài liệu có thể gây choáng ngợp. Bạn sẽ thấy mình phải chuyển đổi liên tục giữa tài liệu xác thực, tài liệu tham khảo API và hướng dẫn webhook chỉ để hoàn thành một tác vụ đơn giản.

Hướng dẫn này tập trung vào những gì bạn thực sự sẽ sử dụng. Sản phẩm, đơn hàng, khách hàng và webhook. Bạn sẽ tìm hiểu về xác thực, các mẫu phổ biến và cách kiểm thử các tích hợp của mình trước khi chúng được triển khai trên cửa hàng thực.

💡
Nếu bạn đang xây dựng tích hợp BigCommerce, Apidog giúp bạn thiết kế, kiểm thử và ghi lại các lệnh gọi API đó. Lưu các yêu cầu dưới dạng bộ sưu tập, sử dụng biến môi trường cho các cửa hàng khác nhau và xác thực rằng các phản hồi khớp với các lược đồ dự kiến. Nó giúp bạn phát hiện lỗi trước khi chúng ảnh hưởng đến khách hàng thực.
button

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

Sau khi hoàn thành hướng dẫn này, bạn sẽ có thể:

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

BigCommerce cung cấp hai phương thức xác thực tùy thuộc vào những gì bạn đang xây dựng.

Phương pháp 1: Mã thông báo API (dành cho các tích hợp tùy chỉnh)

Nếu bạn đang xây dựng một tập lệnh hoặc dịch vụ hoạt động với một cửa hàng, hãy sử dụng mã thông báo API.

Tạo tài khoản API:

  1. Truy cập bảng điều khiển quản trị cửa hàng của bạn
  2. Cài đặt (Settings) → Tài khoản API (API Accounts) → Tạo tài khoản API (Create API Account)
  3. Chọn “Mã thông báo API V3/V2”
  4. Chọn các phạm vi bạn cần (Sản phẩm, Đơn hàng, Khách hàng, v.v.)
  5. Lưu thông tin đăng nhập

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

Thực hiện lệnh gọi đầu tiên của bạn:

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"

store-hash là phần sau /stores/ trong đường dẫn API của bạn. Nó cũng hiển thị trong URL quản trị cửa hàng của bạn.

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

Nếu bạn đang xây dựng một ứng dụng cho marketplace của BigCommerce, hãy sử dụng OAuth.

Quy trình OAuth:

  1. Người dùng nhấp vào “Cài đặt” ứng dụng của bạn trên marketplace
  2. BigCommerce chuyển hướng đến URL gọi lại của bạn với mã xác thực
  3. Máy chủ của bạn trao đổi mã để lấy mã thông báo truy cập
  4. Lưu mã thông báo để thực hiện các lệnh gọi API trong tương lai

Trao đổi mã để lấy mã thông báo:

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 is what you use for API calls
// context contains store_hash

Sử dụng mã thông báo:

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

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

Sản phẩm là trái tim của mọi cửa hàng BigCommerce. API Danh mục V3 xử lý sản phẩm, biến thể, danh mục và 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

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

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]
}

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

Các sản phẩm có tùy chọn (kích thước, màu sắc) có biến thể. Mỗi biến thể có thể có SKU, giá và kho hàng 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"
    }
  ]
}

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
}

Hoặc 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
}

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

Đơn hàng là nơi diễn ra hoạt động kinh doanh. API Đơn hàng V2 xử lý việc 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

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"
    }
  }
]

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

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

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}

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
}

Các ID trạng thái phổ biến:

Tạo lô hàng (hoàn thành)

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
    }
  ]
}

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

API Khách hàng V3 xử lý dữ liệu khách hàng, địa chỉ và 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

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"
    }
  ]
}

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
}

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
}

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

Webhook thông báo cho ứng dụng của bạn khi các sự kiện xảy ra trong một cửa hàng. Thay vì thăm dò, BigCommerce đẩy dữ liệu đến các điểm cuối của bạn.

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
}

Phạm vi có sẵn:

Xác minh chữ ký webhook

BigCommerce ký webhook để bạn có thể xác minh chúng là hợp pháp:

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

Kiểm thử API BigCommerce với Apidog

API BigCommerce yêu cầu tiêu đề nhất quán và xác thực phù hợp. Kiểm thử thủ công bằng curl trở nên tẻ nhạt. Apidog giúp hợp lý hóa điều này.

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

Tạo môi trường cho mỗi cửa hàng:

# Cửa hàng sản xuất
STORE_HASH: abc123
ACCESS_TOKEN: xyz789
BASE_URL: https://api.bigcommerce.com/stores/abc123

# Cửa hàng thử nghiệm
STORE_HASH: staging456
ACCESS_TOKEN: staging_token
BASE_URL: https://api.bigcommerce.com/stores/staging456

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

Tự động thêm tiêu đề 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'
})

3. Xác thực phản hồi

Kiểm thử xem sản phẩm có các trường bắt buộc hay không:

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

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: Mã thông báo truy cập không hợp lệ hoặc bị thiếu.

Cách khắc phục:

  1. Kiểm tra xem tiêu đề X-Auth-Token của bạn đã được đặt chưa
  2. Xác minh mã thông báo chưa bị thu hồi
  3. Đảm bảo tài khoản API có các phạm vi phù hợp

403 Bị cấm

Nguyên nhân: Mã thông báo hợp lệ nhưng thiếu phạm vi yêu cầu.

Cách khắc phục:

  1. Kiểm tra quyền tài khoản API của bạn
  2. Thêm phạm vi bị thiếu (Sản phẩm, Đơn hàng, v.v.)
  3. Tạo mã thông báo mới với các quyền mở rộng

404 Không tìm thấy

Nguyên nhân: Điểm cuối sai hoặc tài nguyên không tồn tại.

Cách khắc phục:

  1. Xác minh store hash là chính xác
  2. Kiểm tra phiên bản API trong URL (v2 so với v3)
  3. Đảm bảo ID tài nguyên tồn tại

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

Nguyên nhân: Vượt quá giới hạn tỷ lệ.

Cách khắc phục: BigCommerce cho phép các giới hạn khác nhau cho mỗi điểm cuối. Sản phẩm: 10.000 yêu cầu/giờ. Đơn hàng: 30.000 yêu cầu/giờ. Kiểm tra tiêu đề X-Rate-Limit-Remaining và triển khai chiến lược 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
    }
  }
}

422 Thực thể không thể xử lý

Nguyên nhân: Lỗi xác thực trong nội dung yêu cầu.

Cách khắc phục: Kiểm tra phản hồi để biết chi tiết. BigCommerce trả về các lỗi xác thực cụ thể:

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

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 cách tiếp cận phân mảnh của Shopify, nhưng API GraphQL của Shopify mang lại sự linh hoạt hơn cho các truy vấn phức tạp.

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

Đồng bộ hóa kho hàng đa kênh. Một thương hiệu bán hàng trên BigCommerce, Amazon và các cửa hàng vật lý. Họ sử dụng API Sản phẩm để đồng bộ hóa mức kho hàng trên các kênh, ngăn chặn tình trạng bán quá mức. Apidog kiểm tra các điểm cuối đồng bộ hóa trước mỗi lần triển khai.

Tự động hóa đơn hàng. Một công ty hộp đăng ký sử dụng webhook để kích hoạt việc hoàn thành khi đơn hàng được tạo. API Đơn hàng cập nhật số theo dõi. Kho hàng của họ tự động nhận danh sách chọn hàng thông qua các trình xử lý webhook.

Phân khúc khách hàng. Một trang web thương mại điện tử sử dụng API Khách hàng để phân khúc người mua dựa trên lịch sử mua hàng. Khách hàng VIP được thêm vào một nhóm đặc biệt với giá độc quyền. Tích hợp này chạy hàng tuần thông qua công việc đã lên lịch.

Kết luận

Đây là những gì bạn đã học được:

Các bước tiếp theo của bạn:

  1. Tạo tài khoản API trong cửa hàng BigCommerce của bạn
  2. Thực hiện lệnh gọi API đầu tiên của bạn để liệt kê sản phẩm
  3. Thiết lập webhook để tạo đơn hàng
  4. Lưu các lệnh gọi API của bạn trong Apidog
  5. Xây dựng tích hợp của bạn

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

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

Sự khác biệt giữa API V2 và V3 là gì?V3 là API mới hơn, nhất quán hơn. Hãy sử dụng nó cho sản phẩm, danh mục, thương hiệu và khách hàng. V2 xử lý các đơn hàng, vốn chưa được di chuyển. Bạn sẽ sử dụng cả hai trong hầu hết các tích hợp.

Làm cách nào để lấy store hash của tôi?Nó nằm trong URL quản trị BigCommerce của bạn: https://store-abc123.mybigcommerce.com/manage. Phần abc123 là store hash của bạn. Nó cũng hiển thị trong cài đặt tài khoản API.

Tôi có thể sử dụng API trên cửa hàng dùng thử không?Có. Các cửa hàng dùng thử BigCommerce có quyền truy cập API đầy đủ. Điều này hoàn hảo cho việc phát triển và kiểm thử trước khi ra mắt.

Giới hạn tỷ lệ cho các lệnh gọi API là gì?Tùy thuộc vào điểm cuối. Sản phẩm: 10.000 yêu cầu/giờ. Đơn hàng: 30.000 yêu cầu/giờ. Kiểm tra X-Rate-Limit-Remaining trong tiêu đề phản hồi để xem giới hạn hiện tại của bạn.

Làm cách nào để xử lý phân trang?Sử dụng các tham số truy vấn page và limit. Giới hạn mặc định là 50. Kiểm tra meta.pagination trong phản hồi để biết tổng số trang. Lặp cho đến khi bạn đã tải tất cả các bản ghi.

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++
}

Tôi có thể tải hình ảnh sản phẩm qua API không?Có. Sử dụng điểm cuối hình ảnh sản phẩm:

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
}

Làm cách nào để xử lý tiền tệ và nhiều cửa hàng?Các cửa hàng BigCommerce có một loại tiền tệ cơ sở. Đa tiền tệ được xử lý ở cấp độ giao diện cửa hàng, không phải API. Đối với nhiều cửa hàng, hãy tạo các tài khoản API riêng biệt và sử dụng các môi trường khác nhau trong Apidog.

Điều gì xảy ra nếu điểm cuối webhook của tôi bị sập?BigCommerce thử lại các webhook bị lỗi với cơ chế backoff lũy thừa. Sau 5 lần lỗi trong vòng 24 giờ, webhook sẽ bị vô hiệu hóa. Theo dõi các điểm cuối của bạn và cảnh báo khi có lỗi.

Thực hành thiết kế API trong Apidog

Khám phá cách dễ dàng hơn để xây dựng và sử dụng API

Đăng ký miễn phíTải xuống