Store Platforms

Tích hợp API Wix: Xác thực, Webhook và bẫy Catalog V3

Giải thích tích hợp API Wix: OAuth, API key, access token, khác biệt Catalog V1/V3 và webhook tự động thử lại 12 lần, kèm mã mẫu.

Ảnh đại diện Long Nguyen

Long Nguyen

Lập trình viên Fullstack · Kỹ sư AI · Nhà nghiên cứu

• • 5 phút đọc •

Tích hợp API Wix bao gồm những gì?

Tích hợp API Wix là đoạn mã dùng để đọc hoặc ghi dữ liệu Wix (sản phẩm, đơn hàng, liên hệ, lịch đặt) thông qua REST API hoặc JavaScript SDK của Wix, hoặc phản hồi các sự kiện Wix bằng webhook. Mã có thể chạy ngay trên website Wix, trên máy chủ riêng của bạn hoặc bên trong một ứng dụng được cài đặt trên website của người khác.

Vị trí chạy mã quyết định cách xác thực, và lựa chọn đó ảnh hưởng đến toàn bộ phần còn lại. Tài liệu của Wix chia thành năm hướng triển khai:

Hướng triển khai Mã chạy ở đâu Xác thực
Mở rộng một website Wix Trên website Wix Xác thực máy chủ, được áp dụng tự động
Ứng dụng do Wix quản lý (CLI hoặc Blocks) Được Wix lưu trữ Tích hợp sẵn; Wix cấp token phiên bản ứng dụng cho mã backend
Ứng dụng tự quản lý Máy chủ của bạn, cài đặt trên website của các merchant OAuth
Dự án headless Bất kỳ stack nào bạn chọn OAuth cho khách truy cập và thành viên; client credentials hoặc API key cho tác vụ quản trị
Tự động hóa bên ngoài Máy chủ, script hoặc tác vụ CI của bạn API key

Phần lớn dự án “kết nối cửa hàng Wix với một hệ thống khác” thuộc hai hàng cuối. Hãy xác định mình đang ở trường hợp nào trước khi viết mã, vì thông tin xác thực, thời hạn token và mô hình phân quyền đều khác nhau.

Nên dùng OAuth hay API key để xác thực Wix?

Wix hỗ trợ OAuth và API key cho mã chạy bên ngoài dashboard, trình chỉnh sửa hoặc website Wix. Hai phương thức này không thể thay thế cho nhau.

  OAuth API key
Phù hợp nhất với Ứng dụng được cài đặt trên nhiều website; danh tính khách truy cập, thành viên và ứng dụng Tự động hóa server-to-server, tích hợp bên ngoài, tác vụ quản trị trên các website bạn quản lý
Thời hạn Access token có hiệu lực 4 giờ Có hiệu lực cho đến khi bị thu hồi hoặc thay mới trong dashboard Wix
Gia hạn Token của khách truy cập và thành viên: refresh token, mặc định 365 ngày và được thay mới sau mỗi lần sử dụng. Token ứng dụng: không có refresh token, phải tạo token mới Không áp dụng
Được cấp bởi OAuth client của ứng dụng hoặc dự án headless Chủ tài khoản hoặc đồng chủ tài khoản trong dashboard
Mô hình phân quyền Scope được cấp cho ứng dụng Scope cùng quyền truy cập website (tất cả website trong tài khoản hoặc chỉ các website được chọn)
Ứng dụng Wix bên thứ ba Bắt buộc Không khả dụng

Nguyên tắc thực tế cho các dự án: nếu tích hợp được cài đặt bởi nhiều merchant hoặc được đăng trên App Market, hãy xây dựng một ứng dụng và dùng OAuth. Nếu tích hợp kết nối website Wix của một doanh nghiệp với ERP, kho hàng hoặc công cụ marketplace của chính doanh nghiệp đó, API key giới hạn phạm vi thường là lựa chọn nhanh hơn. Một phương án khác là dùng client credentials của dự án headless khi bạn chỉ cần quyền quản trị trên website riêng của dự án đó.

Hãy coi API key như mật khẩu tài khoản. Giới hạn key ở nhóm website và scope tối thiểu mà tích hợp cần, lưu key trong secrets manager và nhớ rằng các lệnh gọi ở cấp website chỉ hoạt động với key được tạo từ tài khoản sở hữu website. Nếu bạn thực hiện việc này cho khách hàng, họ sẽ phải tự tạo key vì chỉ chủ tài khoản và đồng chủ tài khoản mới có quyền đó.

Cách lấy Wix access token bằng client credentials

Đối với các thao tác quản trị trong dự án headless, client credentials grant sẽ đổi client ID và secret của OAuth thành một token có thời hạn ngắn. Chỉ chạy quy trình này trong mã backend. Secret chỉ hiển thị một lần khi bạn tạo trong Headless Settings, vì vậy hãy lưu ngay lập tức.

Endpoint cấp token là https://www.wixapis.com/oauth2/token, và phản hồi có expires_in là 14400 giây. Không nên yêu cầu token mới cho mỗi lần gọi. Hãy lưu vào bộ nhớ đệm và gia hạn ngay trước khi token hết hạn:

let cached = { token: null, expiresAt: 0 };

async function getWixToken() {
  const now = Date.now();
  if (cached.token && now < cached.expiresAt - 5 * 60 * 1000) {
    return cached.token;
  }
  const res = await fetch('https://www.wixapis.com/oauth2/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'client_credentials',
      client_id: process.env.WIX_CLIENT_ID,
      client_secret: process.env.WIX_CLIENT_SECRET
    })
  });
  if (!res.ok) throw new Error('Wix token request failed: ' + res.status);
  const data = await res.json();
  cached = { token: data.access_token, expiresAt: now + data.expires_in * 1000 };
  return cached.token;
}

async function wixPost(path, body) {
  const token = await getWixToken();
  const res = await fetch('https://www.wixapis.com' + path, {
    method: 'POST',
    headers: { 'Authorization': token, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  });
  return res.json();
}

Lưu ý: token phải được đưa vào header Authorization đúng nguyên dạng được trả về, không thêm tiền tố nào. API key cũng được gửi trong header này. Nếu lệnh gọi trả về 401, nhiều khả năng token đã hết hạn, vì vậy nên bổ sung cơ chế gia hạn và thử lại một lần quanh wixPost.

Wix Stores Catalog V1 và V3: cái bẫy trong hầu hết tích hợp

Đây là nơi các tích hợp cửa hàng thường âm thầm gặp lỗi. Wix Stores có hai API catalog sản phẩm và mỗi website sẽ sử dụng một trong hai. Theo tài liệu Catalog Versioning của Wix, hai phiên bản không tương thích ngược, tất cả website cuối cùng sẽ chuyển sang V3, và bạn nên gọi endpoint GetCatalogVersion khi bắt đầu mỗi quy trình để biết cần dùng API nào. Mỗi phiên bản cũng phát webhook riêng, vì vậy một tích hợp phải phục vụ mọi website cần đăng ký cả sự kiện V1 và V3.

Hướng dẫn chuyển đổi của Wix cũng nêu rõ rằng không có cách chuyển đổi tự động, đồng thời ứng dụng phải hỗ trợ cả hai phiên bản để có thể được cài đặt trên các website mới lẫn website hiện tại. Những khác biệt có ý nghĩa thực tế gồm:

Hạng mục Catalog V1 Catalog V3
Sản phẩm không có tùy chọn Sản phẩm thông thường Một biến thể mặc định với mảng choices rỗng; mọi thực thể có thể mua đều là một biến thể
Biến thể trong kết quả truy vấn Được xử lý bằng các lệnh gọi V1 Các endpoint Query và Search không trả về biến thể; hãy dùng Read-Only Variants API
Tồn kho stock.quantity trên sản phẩm Inventory Items API, tìm kiếm theo productId và/hoặc variantId
Giá đã giảm price và discountedPrice Khi có giảm giá: price của V1 trở thành compareAtPrice, discountedPrice của V1 trở thành actualPrice. Khi không giảm giá: price trở thành actualPrice
Tùy chọn Tùy chọn có managedVariants true hoặc false Customizations API: options (tạo biến thể) và modifiers (không tạo biến thể)
Trường văn bản tùy chỉnh customTextFields Modifier có loại FREE_TEXT
Phân trang Dùng numericId để phân trang bằng cursor Query và Search tích hợp sẵn phân trang bằng cursor
Sự kiện Webhook V1 Webhook V3 với cấu trúc payload đã thay đổi

Sai lầm tốn kém là viết theo V3 vì đây là phiên bản mới hơn, rồi phát hiện cửa hàng của merchant vẫn dùng V1, hoặc ngược lại. Hãy đặt một adapter giữa business logic và Wix để việc kiểm tra phiên bản chỉ diễn ra một lần:

// One interface, two implementations. Business logic never sees the version.
const catalog = (await isCatalogV3(siteAuth))
  ? new CatalogV3(siteAuth)
  : new CatalogV1(siteAuth);

const products = await catalog.listProducts();
const stock = await catalog.getStock(productId);

Việc tách tồn kho và biến thể trong V3 là phần gây nhiều công sức làm lại nhất: thao tác đọc một sản phẩm trước đây trở thành truy vấn sản phẩm, truy vấn biến thể và tìm kiếm tồn kho. Nếu không muốn tự duy trì hai luồng mã, đây là loại công việc được dịch vụ tích hợp Wix và nền tảng ecommerce của chúng tôi hỗ trợ.

Cách xử lý webhook Wix để không mất sự kiện

Wix gửi dữ liệu webhook dưới dạng JSON Web Token đã ký trong phần body của request, và bạn xác minh token bằng public key trên trang Webhooks trong dashboard ứng dụng. Các hành vi dưới đây được nêu trong tài liệu webhook của Wix:

  • Endpoint phải trả về HTTP 200 trong vòng 1250 mili giây, nếu không Wix sẽ coi lần gửi là thất bại.
  • Khi thất bại, hệ thống sẽ thực hiện tối đa 12 lần thử thêm theo lịch retry.
  • Webhook được gửi lại có thể đến sau một webhook mới hơn đã xử lý thành công ngay lần đầu, vì vậy sự kiện có thể bị trễ và không theo thứ tự.
  • Webhook không phải lúc nào cũng chứa toàn bộ thực thể, và Wix khuyến nghị thiết kế để xử lý sự kiện trùng lặp.
  • Website sử dụng phiên bản major cũ hơn của ứng dụng sẽ không nhận được webhook mới được thêm vào.

Khoảng thời gian 1250 mili giây không đủ để ghi database hoặc gọi thêm API. Handler nên xác minh chữ ký, đưa sự kiện vào queue rồi trả về 200. Chỉ cần như vậy:

import express from 'express';
import jwt from 'jsonwebtoken';

const app = express();

app.post('/webhooks/wix', express.text({ type: '*/*' }), function (req, res) {
  let event;
  try {
    event = jwt.verify(req.body, process.env.WIX_APP_PUBLIC_KEY, {
      algorithms: ['RS256']
    });
  } catch (err) {
    return res.sendStatus(401);
  }
  queue.add(event); // your own job queue: parse and process later
  res.sendStatus(200);
});

Nếu xây dựng bằng Wix CLI, các event extension sẽ xử lý payload thay bạn, nên handler này chỉ cần thiết cho ứng dụng tự lưu trữ. Tab Logs trên trang Webhooks của dashboard ứng dụng hiển thị mọi lần gửi và là nơi đầu tiên cần kiểm tra khi có vẻ như sự kiện bị thiếu.

Mẫu đồng bộ có thể chịu được retry và sự cố gián đoạn

Vì lần gửi có thể lặp lại, đến muộn hoặc không theo thứ tự, một handler chỉ thực hiện “tồn kho thay đổi, trừ 1” sẽ dần sai lệch. Payload của Wix là tín hiệu cho biết có thay đổi, không phải sổ ghi nhận giao dịch. Mẫu sau đây hoạt động ổn định hơn:

  1. Xác nhận thật nhanh. Xác minh, đưa một job nhỏ (loại sự kiện và ID thực thể) vào queue rồi trả về 200.
  2. Đọc lại dữ liệu, không tin tuyệt đối vào payload. Worker lấy thực thể hiện tại từ Wix API, nhờ đó trạng thái được ghi luôn là trạng thái mới nhất.
  3. Upsert theo ID thực thể Wix. Chạy cùng một job hai lần phải cho ra cùng một kết quả.
  4. Đối soát theo lịch. Wix cũng khuyến nghị gửi request API định kỳ để xác nhận webhook chính xác. Truy vấn sản phẩm hoặc đơn hàng vừa thay đổi mỗi đêm sẽ phát hiện những dữ liệu webhook bỏ sót.
  5. Giới hạn đồng thời và backoff khi gặp HTTP 429. Nhập dữ liệu hàng loạt là lúc các tích hợp dễ vướng giới hạn request nhất.

Bước 2 và 4 tạo nên khác biệt giữa một tích hợp chạy được trong bản demo và một tích hợp vẫn duy trì dữ liệu chính xác sau nhiều tháng.

Lỗi Wix API và nguyên nhân thường gặp

Triệu chứng Nguyên nhân có thể Cách khắc phục
401 trên mọi lệnh gọi REST OAuth access token đã hết hạn (thời hạn 4 giờ) Tạo hoặc refresh token rồi thử lại một lần
401 khi gọi Stores: invalid authorization token hoặc Wix Stores chưa được cài đặt Token không thuộc website đó hoặc website chưa có Wix Stores Xác nhận website đã cài Stores và token được cấp cho website đó
403 khi dùng API key Key thiếu scope cho thao tác đó hoặc website đích nằm ngoài quyền truy cập website của key Điều chỉnh scope và quyền truy cập website trong API Keys Manager
Lệnh gọi cấp website thất bại dù key hợp lệ Key được tạo từ tài khoản khác với tài khoản sở hữu website Dùng key từ tài khoản sở hữu website
Sản phẩm không có biến thể sau khi chuyển sang V3 Query và Search của V3 không trả về biến thể Dùng Read-Only Variants API
Tích hợp hoạt động trên một cửa hàng nhưng lỗi trên cửa hàng khác Hai cửa hàng dùng các phiên bản catalog khác nhau Gọi GetCatalogVersion trước rồi phân nhánh xử lý
Một số website không bao giờ nhận webhook mới Website đang dùng phiên bản major cũ hơn của ứng dụng Yêu cầu merchant cập nhật; kiểm tra tab Logs
Cùng một sự kiện được xử lý hai lần Retry sau khi bỏ lỡ phản hồi 200 hoặc timeout quá 1250 mili giây Khử trùng lặp và thiết kế handler idempotent

Tự xây dựng hay thuê bên ngoài?

Một quy trình xuất dữ liệu một chiều, chỉ đọc, từ một cửa hàng Wix duy nhất và được thực hiện bởi đội ngũ có lập trình viên backend là dự án phù hợp để tự làm. Tình hình sẽ khác nếu có bất kỳ điều kiện nào sau đây:

  • Đồng bộ hai chiều (đơn hàng đi vào, tồn kho và mã vận đơn đi ra) giữa các marketplace, ERP hoặc hệ thống kho.
  • Có từ hai cửa hàng Wix trở lên, vì bạn sẽ phải xử lý cả hai phiên bản catalog.
  • Không ai trong đội ngũ muốn chịu trách nhiệm lâu dài về độ tin cậy của webhook, xử lý token và đối soát dữ liệu.

Trước khi trao đổi với bất kỳ đơn vị nào, hãy viết ra năm câu trả lời: dữ liệu di chuyển theo hướng nào, những thực thể nào liên quan (sản phẩm, đơn hàng, khách hàng), mỗi cửa hàng đang dùng phiên bản catalog nào, ai sở hữu tài khoản Wix có quyền tạo API key và cần làm gì khi đồng bộ thất bại lúc 3 giờ sáng. Năm câu trả lời này chiếm phần lớn phạm vi dự án.

Nếu muốn có thêm ý kiến chuyên môn hoặc báo giá triển khai, hãy yêu cầu báo giá miễn phí cho tích hợp Wix, kèm thông tin về cửa hàng, hệ thống cần kết nối và dữ liệu liên quan. Chi phí được xác định theo phạm vi công việc.

CÂU HỎI THƯỜNG GẶP

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

Wix có public API không?

Có. Wix cung cấp REST API để truy cập qua HTTP vào các giải pháp kinh doanh và dữ liệu website, chẳng hạn như sản phẩm và đơn hàng Wix Stores, cùng JavaScript SDK và webhook cho các sự kiện.

Tôi có cần xây dựng ứng dụng Wix để kết nối cửa hàng của mình với hệ thống khác không?

Không nhất thiết. Với tự động hóa server-to-server trên các website bạn quản lý, API key được thiết kế cho mục đích này; một dự án headless cũng có thể dùng client credentials cho các lệnh gọi quản trị. Bạn cần một ứng dụng dùng OAuth khi phân phối qua Wix App Market hoặc cài đặt trên website của merchant khác.

Wix access token có hiệu lực trong bao lâu?

OAuth access token có hiệu lực trong 4 giờ. Token của khách truy cập và thành viên đi kèm refresh token mặc định có hiệu lực 365 ngày, trong khi token ứng dụng từ client credentials không có refresh token và phải được tạo lại. API key vẫn có hiệu lực cho đến khi bạn thu hồi hoặc thay mới.

Tôi có thể dùng Wix API key bên trong ứng dụng Wix của bên thứ ba không?

Không. Wix API key không dành cho ứng dụng bên thứ ba. Các ứng dụng phải xác thực bằng OAuth.

Wix Stores Catalog V1 và V3 khác nhau như thế nào?

Đây là hai API catalog sản phẩm riêng biệt và không tương thích ngược. Trong V3, mọi sản phẩm đều có ít nhất một biến thể, tồn kho nằm trong Inventory Items API, options và modifiers được quản lý qua Customizations API, còn các endpoint truy vấn V3 không trả về biến thể. Hãy gọi GetCatalogVersion để biết website đang dùng phiên bản nào.

Endpoint của tôi phải phản hồi webhook Wix nhanh đến mức nào?

Trong vòng 1250 mili giây với HTTP 200. Nếu không, Wix sẽ thử gửi lại tối đa 12 lần, khiến sự kiện trùng lặp và không theo thứ tự là điều bình thường; handler của bạn nên có tính idempotent.

Cập nhật cùng Netalith

Nhận kiến thức công nghệ, cập nhật sản phẩm và ưu đãi đặc biệt qua email.