Social Commerce

Kết nối TikTok Shop với website riêng: Xác thực, webhook và đồng bộ

Hướng dẫn kết nối TikTok Shop với website riêng: dữ liệu cần đồng bộ, OAuth, webhook, polling và các lỗi mapping gây thất lạc đơn hàng.

Ảnh đại diện Long Nguyen

Long Nguyen

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

• • 4 phút đọc •

Thực chất “kết nối TikTok Shop với website riêng” là gì?

TikTok Shop không phải là một widget để bạn nhúng vào website. Khách hàng hoàn tất thanh toán ngay trong TikTok, vì vậy “kết nối” website riêng có nghĩa là đồng bộ dữ liệu giữa hai hệ thống, chứ không phải đưa quy trình thanh toán TikTok lên các trang của bạn. Khi nhìn vấn đề theo cách này, công việc sẽ được chia thành bốn luồng dữ liệu, mỗi luồng có những điểm dễ lỗi riêng.

Luồng Hướng Dữ liệu được chuyển Điểm dễ lỗi
Danh mục Từ website của bạn sang TikTok Shop Sản phẩm, biến thể, hình ảnh, giá, thuộc tính danh mục Quy định danh mục và thuộc tính bắt buộc khác nhau theo từng thị trường; sản phẩm bị từ chối cần có luồng báo lỗi rõ ràng
Tồn kho Hai chiều Số lượng tồn theo SKU Bán vượt tồn khi hai kênh cùng bán đơn vị cuối cùng trong một khoảng thời gian đồng bộ
Đơn hàng Từ TikTok Shop sang website của bạn Đơn hàng mới, thay đổi trạng thái, thông tin người mua và giao hàng Bỏ sót hoặc xử lý trùng sự kiện; tên trạng thái không khớp với trạng thái đơn hàng của bạn
Thực hiện đơn hàng Từ website của bạn sang TikTok Shop Mã vận đơn, đơn vị vận chuyển, hủy đơn và trả hàng Cập nhật vận đơn trễ làm ảnh hưởng chỉ số người bán; giao hàng từng phần

Hãy xác định chính xác bạn cần luồng nào trong bốn luồng trên trước khi viết dòng code đầu tiên. Nhiều cửa hàng chỉ cần nhận đơn hàng và gửi thông tin vận đơn, còn bỏ qua việc đẩy danh mục sẽ giúp loại bỏ phần khó nhất của dự án.

Ba cách kết nối TikTok Shop với website riêng

Lựa chọn phù hợp phụ thuộc vào mức độ logic của bạn có thể dùng theo chuẩn có sẵn và mức độ tùy chỉnh riêng.

Phương án Phù hợp khi Đánh đổi
Công cụ kết nối hoặc ứng dụng có sẵn Website của bạn chạy trên một nền tảng phổ biến đã có tích hợp TikTok Shop Triển khai nhanh, nhưng bạn phải chấp nhận cách mapping trường dữ liệu, thời điểm đồng bộ và các giới hạn của công cụ
Nền tảng tích hợp (iPaaS) Bạn cần một vài quy trình và chấp nhận mức phí hằng tháng tính theo tác vụ Chi phí tăng theo số lượng đơn hàng; mapping phức tạp trở nên khó xử lý
Tích hợp riêng trên TikTok Shop Partner Center API Bạn vận hành website tự xây dựng, cần logic đơn hàng riêng hoặc đồng bộ nhiều kênh Cần nhiều công sức ban đầu nhất, nhưng toàn quyền kiểm soát mapping, cơ chế thử lại và quyền sở hữu dữ liệu

Nếu website được xây dựng riêng, thường sẽ không có công cụ kết nối dựng sẵn phù hợp. Vì vậy, phần còn lại của hướng dẫn này tập trung vào phương án thứ ba.

Cần chuẩn bị gì trước khi viết code?

  • Tài khoản người bán TikTok Shop đã được phê duyệt cho từng shop bạn muốn kết nối, tại thị trường nơi bạn kinh doanh.
  • Ứng dụng dành cho nhà phát triển trên TikTok Shop Partner Center. Bạn tạo ứng dụng, chọn các phạm vi API cần dùng, sau đó nhận app key và app secret. Loại ứng dụng phù hợp phụ thuộc vào việc bạn chỉ kết nối shop của mình hay nhiều shop của các nhà bán hàng khác; các lựa chọn hiện có được mô tả trong hướng dẫn xác thực của Partner Center.
  • Backend HTTPS công khai có thể nhận redirect và lời gọi webhook. Website tĩnh không thể tự thực hiện việc này.
  • Nơi lưu trữ an toàn cho các secret: app secret và token của từng shop phải được lưu ở phía server, tuyệt đối không đưa vào code frontend.

Phạm vi API và khả năng hỗ trợ theo từng thị trường có thể thay đổi, vì vậy hãy đọc danh sách scope trên Partner Center tại thời điểm xây dựng thay vì chỉ dựa vào một bài blog, kể cả bài này.

Quy trình xác thực TikTok Shop hoạt động như thế nào?

TikTok Shop sử dụng quy trình kiểu OAuth. Các khái niệm dưới đây tương đối ổn định; hãy lấy URL, tên tham số và thời hạn token chính xác từ tài liệu chính thức.

  1. Đưa người bán đến trang xác thực của TikTok dành cho ứng dụng của bạn. Người bán đăng nhập và cấp các scope bạn yêu cầu.
  2. TikTok chuyển hướng trở lại URL callback của bạn kèm một mã xác thực có thời hạn ngắn.
  3. Backend của bạn đổi mã này lấy access token và refresh token bằng app key và app secret. Lời gọi này phải được thực hiện ở phía server.
  4. Tra cứu shop đã cấp quyền và lưu mã định danh của shop cùng các token. Các lời gọi API cấp shop cần mã định danh mà TikTok trả về cho lần xác thực đó, vì vậy hãy lưu mã này trong bản ghi của shop.
  5. Làm mới token trước khi hết hạn. Access token có thời hạn ngắn, nên một tác vụ được lên lịch cần gia hạn token và lưu lại cặp token mới.

Mỗi lời gọi API cũng được ký bằng app secret, nên chỉ dùng một HTTP client thông thường là chưa đủ: bạn cần triển khai routine ký theo tài liệu chính thức hoặc SDK. Hãy làm đúng phần này trong một test script trước, vì lỗi chữ ký là nguyên nhân phổ biến nhất khiến lời gọi API đầu tiên thất bại.

Lưu ý thực tế khi quản lý token

  • Refresh token có thể được luân phiên. Hãy lưu giá trị mới mỗi lần và đừng bao giờ ghi đè bằng bản cũ từ một job chạy song song. Dùng database lock để tuần tự hóa việc refresh theo từng shop.
  • Mã hóa token khi lưu trữ và không để token xuất hiện trong log. Token bị lộ đồng nghĩa với quyền truy cập trực tiếp vào đơn hàng và dữ liệu khách hàng của người bán.
  • Thiết kế cho tình huống thu hồi quyền. Người bán có thể thu hồi quyền truy cập bất cứ lúc nào. Hãy coi lỗi xác thực là trạng thái “shop đã ngắt kết nối”, tạm dừng đồng bộ và hiển thị cảnh báo trong trang quản trị thay vì thử lại vô hạn.

Kiến trúc backend đủ bền vững khi số lượng đơn tăng

Mô hình có thể vận hành ổn định cũng giống với phần lớn tích hợp marketplace: dùng webhook để phản hồi nhanh, polling theo lịch để đảm bảo tính chính xác, đặt queue ở giữa và dùng handler idempotent ở mọi nơi.

Thành phần Nhiệm vụ Vì sao quan trọng
Dịch vụ xác thực Xử lý callback, lưu và refresh token theo từng shop Một nơi duy nhất quản lý thông tin xác thực
Bộ nhận webhook Kiểm tra chữ ký, ghi nhận sự kiện và trả phản hồi thành công nhanh Handler chậm sẽ gây timeout và khiến hệ thống thử lại
Queue và worker Lấy đầy đủ thông tin đơn hàng hoặc sản phẩm rồi cập nhật database Giữ bộ nhận webhook phản hồi nhanh và cho phép thử lại an toàn
Job đối soát Định kỳ lấy danh sách đơn hàng vừa thay đổi và so sánh với dữ liệu của bạn Bắt được những sự kiện chưa từng đến hệ thống
Log đồng bộ Lưu mọi lời gọi đi và kết quả tương ứng theo từng shop Cách duy nhất để tìm hiểu “vì sao đơn hàng này bị thiếu” sau một tháng

TikTok Shop gửi các thay đổi về đơn hàng và sản phẩm đến webhook bạn đăng ký; loại sự kiện, trường dữ liệu và cơ chế thử lại hiện tại được nêu trong tài liệu webhook của Partner Center. Dù lịch thử lại cụ thể ra sao, hãy luôn chuẩn bị cho hai thực tế: sự kiện có thể đến hai lần và cũng có thể bị thất lạc.

Khung bộ nhận webhook

Cấu trúc dưới đây là phần không thay đổi giữa các nền tảng. Việc kiểm tra chữ ký và tên trường phải lấy từ tài liệu chính thức, nên được để dưới dạng placeholder được đánh dấu rõ ràng thay vì tự phỏng đoán.

import json
from django.http import HttpResponse
from django.views.decorators.csrf import csrf_exempt
from django.db import IntegrityError
from .models import WebhookEvent
from .tasks import process_event


def signature_is_valid(request, raw_body):
    # Implement exactly as described in the Partner Center webhook docs.
    raise NotImplementedError


@csrf_exempt
def tiktok_webhook(request):
    raw_body = request.body
    if not signature_is_valid(request, raw_body):
        return HttpResponse(status=401)

    payload = json.loads(raw_body)
    event_key = payload.get("EVENT_ID_FIELD_FROM_DOCS")  # dedupe key

    try:
        # unique constraint on event_key makes duplicates harmless
        event = WebhookEvent.objects.create(event_key=event_key, body=payload)
    except IntegrityError:
        return HttpResponse(status=200)  # already seen

    process_event.delay(event.id)  # heavy work happens in a worker
    return HttpResponse(status=200)

Ba chi tiết trong đoạn code này tạo nên phần lớn độ tin cậy: kiểm tra chữ ký trên raw body trước khi phân tích, lưu dữ liệu trước rồi mới xử lý, và áp dụng tính duy nhất ở database thay vì chỉ dựa vào code ứng dụng.

Cách đồng bộ sản phẩm, đơn hàng và tồn kho chính xác

Phần lớn lỗi tích hợp nằm ở mapping chứ không phải API. Dưới đây là những quyết định cần được cân nhắc một cách chủ động.

Khu vực Quyết định cần đưa ra Khuyến nghị
Định danh SKU Điều gì liên kết sản phẩm của bạn với listing trên TikTok Shop? Lưu mã định danh sản phẩm và SKU của TikTok trong một bảng mapping; không dựa vào tiêu đề hoặc chỉ một chuỗi SKU của người bán
Danh mục và thuộc tính Cây danh mục của bạn sẽ không trùng với TikTok Duy trì bảng mapping danh mục rõ ràng và kiểm tra thuộc tính bắt buộc trước khi đẩy dữ liệu, để lỗi hiển thị trong trang quản trị thay vì bị từ chối âm thầm
Trạng thái đơn hàng Trạng thái của TikTok so với trạng thái trong hệ thống của bạn Mapping tường minh mọi trạng thái TikTok và ghi log các giá trị chưa biết thay vì bỏ qua
Tồn kho Hệ thống nào là nguồn dữ liệu chính? Database website của bạn, đẩy dữ liệu sang TikTok mỗi khi có thay đổi và chạy đối soát toàn bộ theo lịch
Giá và tiền tệ Giá theo từng thị trường Duy trì trường giá riêng cho từng kênh để chương trình khuyến mãi trên TikTok không ghi đè giá trên website
Dữ liệu khách hàng Thông tin người mua là dữ liệu cá nhân Chỉ lưu những gì cần cho việc hoàn tất đơn hàng và tuân thủ các điều khoản xử lý dữ liệu bạn đã đồng ý trên Partner Center

Với tồn kho, duy trì một lượng hàng an toàn luôn rẻ hơn việc phải xin lỗi khách hàng. Giữ một phần đệm nhỏ cho mỗi kênh nhiều nhất chỉ khiến bạn mất vài lượt bán; bán vượt tồn có thể dẫn đến hủy đơn, điều này ảnh hưởng đến shop của bạn.

Nên tự xây dựng hay thuê đội ngũ thực hiện?

Hãy tự xây dựng nếu bạn có một backend developer, chỉ vận hành một shop và chỉ cần đồng bộ đơn hàng cùng thông tin vận chuyển. Phần xác thực và webhook có thể hoàn thành trong vài ngày; phần tốn công về lâu dài là mapping và xử lý lỗi.

Nên tìm hỗ trợ khi bạn bán ở nhiều thị trường, đồng bộ danh mục và tồn kho hai chiều, hoặc đã vận hành các kênh khác trên cùng một hệ thống. Khi đó, job đối soát, log đồng bộ và quản lý token cho nhiều shop không còn là phần tùy chọn. Dịch vụ tích hợp TikTok Shop API của chúng tôi tập trung chính xác vào lớp này; bạn có thể đối chiếu phạm vi công việc với hệ thống hiện tại trước khi cam kết.

Các sự cố thường gặp khi kết nối TikTok Shop và cách khắc phục

Triệu chứng Nguyên nhân có thể Cách khắc phục
Mọi lời gọi API đều thất bại với lỗi chữ ký Routine ký khác với tài liệu (thứ tự tham số, cách xử lý body, vị trí đặt secret) Tái hiện bằng SDK chính thức hoặc công cụ kiểm thử của Partner Center, sau đó so sánh các đầu vào
Hôm qua gọi được API nhưng hôm nay lại lỗi Access token đã hết hạn và quá trình refresh không chạy hoặc bị tranh chấp Dùng khóa refresh theo từng shop và cảnh báo khi refresh thất bại
Đơn hàng không xuất hiện trên website Webhook chưa được đăng ký cho shop đó, endpoint timeout hoặc sự kiện bị thất lạc Kiểm tra trạng thái gửi, rút ngắn công việc tại bộ nhận và bổ sung job đối soát
Đơn hàng bị trùng Sự kiện được thử lại và xử lý hai lần Thiết lập ràng buộc duy nhất cho mã sự kiện và mã đơn hàng
Sản phẩm có trên website nhưng không có trên TikTok Yêu cầu về danh mục, thuộc tính hoặc hình ảnh không đạt kiểm duyệt Hiển thị lý do bị từ chối từ API trong trang quản trị
Tồn kho giữa các kênh không khớp Hai kênh cùng bán đơn vị cuối cùng trong khoảng thời gian đồng bộ Dùng lượng hàng an toàn và đẩy dữ liệu khi có thay đổi thay vì chỉ đồng bộ định kỳ

Nếu muốn có thêm một góc nhìn trước khi xây dựng mô hình như trên, hãy gửi bản phác thảo qua biểu mẫu nhận báo giá miễn phí của chúng tôi và mô tả website, thị trường cùng số lượng đơn hàng của bạn.

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

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

Tôi có thể nhúng thanh toán TikTok Shop vào website riêng không?

Không. Đơn hàng TikTok Shop được đặt ngay trong TikTok. Kết nối website riêng có nghĩa là đồng bộ sản phẩm, tồn kho, đơn hàng và thông tin vận chuyển giữa hệ thống của bạn với TikTok Shop thông qua Partner Center API.

Tôi có cần tài khoản nhà phát triển để kết nối TikTok Shop với website riêng không?

Có, nếu bạn thực hiện tích hợp riêng. Bạn cần tạo một ứng dụng trên TikTok Shop Partner Center, yêu cầu các scope API cần thiết và để từng người bán cấp quyền cho ứng dụng. Nếu nền tảng của bạn đã có công cụ kết nối dựng sẵn, bạn có thể không cần tự xây dựng trực tiếp trên API.

Nên dùng webhook hay polling để nhận đơn hàng TikTok Shop?

Nên dùng cả hai. Webhook giúp nhận đơn nhanh, nhưng sự kiện có thể bị trùng hoặc thất lạc. Vì vậy, một job đối soát theo lịch, có nhiệm vụ lấy danh sách đơn hàng vừa thay đổi, là cách đảm bảo không bỏ sót dữ liệu.

Nên lưu access token và refresh token của TikTok Shop ở đâu?

Chỉ lưu trên server, mã hóa khi lưu trữ và tuyệt đối không đưa vào code frontend hoặc log. Hãy refresh token theo từng shop với cơ chế khóa để các job chạy song song không ghi đè token mới bằng token cũ.

Mất bao lâu để kết nối một TikTok Shop với website riêng?

Với một shop, việc xác thực cùng đồng bộ đơn hàng và thông tin vận chuyển thường mất vài ngày đối với backend developer có kinh nghiệm. Đồng bộ danh mục ở nhiều thị trường, tồn kho hai chiều và xử lý lỗi là những yếu tố khiến các dự án lớn mất nhiều thời gian hơn.

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.