Claude API + Shopee Open Platform — Tự động hóa nâng cao cho seller

Nếu bạn đã quen với việc dùng Claude Chat để phân tích dữ liệu Shopee, bước tiếp theo là tự động hóa toàn bộ quy trình bằng cách kết nối Claude API trực tiếp với Shopee Open Platform. Bài viết này hướng dẫn bạn xây dựng hệ thống tự động hóa hoàn chỉnh — từ kiến trúc tổng quan đến code mẫu có thể chạy ngay.

Tổng quan Shopee Open Platform

Shopee Open Platform là bộ API chính thức cho phép developer và seller tương tác với hệ thống Shopee thông qua code. Các tính năng chính bao gồm:

• Shop API: Quản lý thông tin shop, lấy danh sách sản phẩm, cập nhật giá và tồn kho
• Product API: Tạo mới, cập nhật, xóa sản phẩm; quản lý biến thể và hình ảnh
• Order API: Lấy danh sách đơn hàng, chi tiết đơn, cập nhật trạng thái vận chuyển
• Chat API: Gửi và nhận tin nhắn với khách hàng qua Shopee Chat
• Logistics API: Quản lý vận chuyển, in nhãn, theo dõi đơn hàng

Để bắt đầu, bạn cần đăng ký tài khoản developer tại open.shopee.com, tạo ứng dụng và lấy Partner ID cùng Partner Key. Sau đó, seller sẽ ủy quyền (authorize) cho ứng dụng của bạn truy cập vào shop của họ.

Kiến trúc tích hợp Claude API + Shopee

Hệ thống tích hợp gồm 3 lớp chính:

• Lớp dữ liệu (Data Layer): Shopee Open Platform cung cấp dữ liệu sản phẩm, đơn hàng, đánh giá thông qua REST API
• Lớp xử lý (Processing Layer): Server Node.js nhận dữ liệu từ Shopee, gửi đến Claude API để phân tích/tạo nội dung, sau đó gửi kết quả ngược lại Shopee
• Lớp điều phối (Orchestration Layer): Webhook từ Shopee kích hoạt quy trình tự động; cron job chạy các tác vụ định kỳ

Chuẩn bị môi trường phát triển

Trước khi bắt đầu code, cài đặt các package cần thiết:

npm init -y
npm install @anthropic-ai/sdk axios crypto-js dotenv express

Tạo file cấu hình môi trường .env:

ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
SHOPEE_PARTNER_ID=your_partner_id
SHOPEE_PARTNER_KEY=your_partner_key
SHOPEE_SHOP_ID=your_shop_id
SHOPEE_ACCESS_TOKEN=your_access_token

Module kết nối Shopee API

Shopee yêu cầu mỗi request phải có chữ ký (signature) để xác thực. Dưới đây là module cơ bản để gọi Shopee API:

const crypto = require('crypto');
const axios = require('axios');
require('dotenv').config();

const SHOPEE_HOST = 'https://partner.shopeemobile.com';

function generateSignature(path, timestamp) {
  const baseString = `${process.env.SHOPEE_PARTNER_ID}${path}${timestamp}${process.env.SHOPEE_ACCESS_TOKEN}${process.env.SHOPEE_SHOP_ID}`;
  return crypto
    .createHmac('sha256', process.env.SHOPEE_PARTNER_KEY)
    .update(baseString)
    .digest('hex');
}

async function callShopeeAPI(path, method = 'GET', data = null) {
  const timestamp = Math.floor(Date.now() / 1000);
  const sign = generateSignature(path, timestamp);

  const url = `${SHOPEE_HOST}${path}`;
  const params = {
    partner_id: Number(process.env.SHOPEE_PARTNER_ID),
    timestamp,
    sign,
    access_token: process.env.SHOPEE_ACCESS_TOKEN,
    shop_id: Number(process.env.SHOPEE_SHOP_ID),
  };

  const config = { method, url, params };
  if (data) config.data = data;

  const response = await axios(config);
  return response.data;
}

module.exports = { callShopeeAPI };

Tự động tạo mô tả sản phẩm khi listing mới

Một trong những ứng dụng giá trị nhất là tự động sinh mô tả sản phẩm chất lượng cao khi seller tạo listing mới. Thay vì viết thủ công, Claude sẽ tạo mô tả tối ưu cho SEO và chuyển đổi.

Quy trình hoạt động

1. Seller tạo sản phẩm mới trên Shopee với thông tin cơ bản (tên, danh mục, giá, hình ảnh)
2. Webhook thông báo có sản phẩm mới
3. Server lấy thông tin sản phẩm qua Shopee API
4. Gửi thông tin cho Claude API để tạo mô tả
5. Cập nhật mô tả vào sản phẩm qua Shopee API

const Anthropic = require('@anthropic-ai/sdk');
const { callShopeeAPI } = require('./shopee-client');

const anthropic = new Anthropic();

async function generateProductDescription(productInfo) {
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1500,
    messages: [
      {
        role: 'user',
        content: `Bạn là chuyên gia viết mô tả sản phẩm trên Shopee Việt Nam.
Viết mô tả sản phẩm hấp dẫn, tối ưu SEO, dựa trên thông tin sau:

Tên sản phẩm: ${productInfo.item_name}
Danh mục: ${productInfo.category_name}
Giá: ${productInfo.price_info.current_price} VND
Thuộc tính: ${JSON.stringify(productInfo.attribute_list)}

Yêu cầu:
- Viết bằng tiếng Việt, giọng điệu thân thiện và chuyên nghiệp
- Bao gồm: mô tả tổng quan, đặc điểm nổi bật, thông số kỹ thuật,
  hướng dẫn sử dụng, chính sách bảo hành
- Tối ưu từ khóa tìm kiếm trên Shopee
- Độ dài 500-800 từ
- Sử dụng ký hiệu Unicode thay cho emoji
- Không dùng tuyên bố tuyệt đối ("tốt nhất", "số 1")`
      }
    ]
  });

  return message.content[0].text;
}

async function autoDescribeNewProduct(itemId) {
  // Lấy thông tin sản phẩm từ Shopee
  const productData = await callShopeeAPI(
    '/api/v2/product/get_item_base_info',
    'GET',
    null
  );
  // Thêm item_id_list vào params khi gọi thực tế

  const productInfo = productData.response.item_list[0];

  // Tạo mô tả bằng Claude
  const description = await generateProductDescription(productInfo);

  // Cập nhật mô tả vào Shopee
  await callShopeeAPI('/api/v2/product/update_item', 'POST', {
    item_id: itemId,
    description: description,
  });

  console.log(`Da cap nhat mo ta cho san pham ${itemId}`);
  return description;
}

Tự động phản hồi đánh giá khách hàng

Phản hồi đánh giá nhanh chóng và chu đáo giúp tăng uy tín shop và tỷ lệ chuyển đổi. Claude có thể tạo phản hồi cá nhân hóa dựa trên nội dung đánh giá.

async function generateReviewResponse(review) {
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 500,
    messages: [
      {
        role: 'user',
        content: `Bạn là chủ shop trên Shopee. Viết phản hồi cho đánh giá sau:

Sản phẩm: ${review.item_name}
Số sao: ${review.rating_star}/5
Nội dung: ${review.comment}

Quy tắc phản hồi:
- Nếu 4-5 sao: Cảm ơn chân thành, mời mua lại
- Nếu 3 sao: Cảm ơn, hỏi thêm để cải thiện
- Nếu 1-2 sao: Xin lỗi, đề xuất giải pháp cụ thể, mời liên hệ trực tiếp
- Luôn gọi khách là "bạn" hoặc "anh/chị"
- Ngắn gọn (50-100 từ), chuyên nghiệp, không dùng template cứng nhắc
- Không bao giờ phủ nhận trải nghiệm của khách
- Đề cập tên sản phẩm cụ thể trong phản hồi`
      }
    ]
  });

  return message.content[0].text;
}

async function autoReplyReviews() {
  // Lấy đánh giá chưa phản hồi
  const reviews = await callShopeeAPI(
    '/api/v2/product/get_comment',
    'GET'
  );

  const unreplied = reviews.response.item_comment_list.filter(
    (r) => !r.reply
  );

  for (const review of unreplied) {
    try {
      const reply = await generateReviewResponse(review);

      await callShopeeAPI('/api/v2/product/reply_comment', 'POST', {
        comment_id: review.comment_id,
        comment: reply,
      });

      console.log(`Da phan hoi danh gia ${review.comment_id}`);

      // Rate limiting: đợi 2 giây giữa mỗi phản hồi
      await new Promise((resolve) => setTimeout(resolve, 2000));
    } catch (error) {
      console.error(`Loi khi phan hoi ${review.comment_id}:`, error.message);
    }
  }
}

Kiểm duyệt trước khi gửi

Trong giai đoạn đầu, bạn nên kiểm duyệt phản hồi trước khi gửi tự động. Thêm một bước phê duyệt vào quy trình:

async function autoReplyWithApproval() {
  const reviews = await getUnrepliedReviews();

  const pendingReplies = [];
  for (const review of reviews) {
    const reply = await generateReviewResponse(review);
    pendingReplies.push({
      review,
      suggestedReply: reply,
      status: 'pending',
    });
  }

  // Lưu vào database để admin duyệt qua dashboard
  await savePendingReplies(pendingReplies);

  // Gửi thông báo cho admin qua Telegram/Slack
  await notifyAdmin(
    `Co ${pendingReplies.length} phan hoi can duyet. Xem tai dashboard.`
  );
}

Xử lý thông báo đơn hàng thông minh

Khi có đơn hàng mới, hệ thống có thể tự động phân tích và tạo báo cáo tóm tắt hàng ngày bằng Claude.

async function processDailyOrders() {
  // Lấy đơn hàng trong ngày
  const timeFrom = Math.floor(
    new Date().setHours(0, 0, 0, 0) / 1000
  );
  const timeTo = Math.floor(Date.now() / 1000);

  const orders = await callShopeeAPI(
    '/api/v2/order/get_order_list',
    'GET'
  );

  // Tổng hợp dữ liệu
  const orderSummary = {
    total_orders: orders.response.order_list.length,
    total_revenue: 0,
    by_status: {},
    by_product: {},
    by_region: {},
  };

  for (const order of orders.response.order_list) {
    const detail = await callShopeeAPI(
      '/api/v2/order/get_order_detail',
      'GET'
    );
    // Xử lý chi tiết đơn hàng...
    orderSummary.total_revenue += detail.response.total_amount;
  }

  // Gửi cho Claude phân tích
  const analysis = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1000,
    messages: [
      {
        role: 'user',
        content: `Phân tích tóm tắt đơn hàng Shopee hôm nay:

${JSON.stringify(orderSummary, null, 2)}

Cho biết:
1. Tổng quan: doanh thu, số đơn, AOV
2. So sánh với ngày hôm qua (nếu có dữ liệu)
3. Sản phẩm bán chạy nhất hôm nay
4. Có bất thường gì không? (tỷ lệ hủy cao, sản phẩm nào đó bán vọt...)
5. 2-3 gợi ý hành động cho ngày mai

Trình bày ngắn gọn, dạng bullet points.`
      }
    ]
  });

  // Gửi báo cáo qua Telegram
  await sendTelegramMessage(analysis.content[0].text);
}

// Chạy mỗi ngày lúc 23:00
const cron = require('node-cron');
cron.schedule('0 23 * * *', processDailyOrders);

Tự động trả lời chat khách hàng

Shopee Chat API cho phép bạn tự động phản hồi tin nhắn khách hàng. Kết hợp với Claude, bạn có thể tạo chatbot thông minh xử lý các câu hỏi thường gặp.

async function handleCustomerMessage(message) {
  const { buyer_id, content, item_id } = message;

  // Lấy thông tin sản phẩm liên quan (nếu có)
  let productContext = '';
  if (item_id) {
    const product = await callShopeeAPI(
      '/api/v2/product/get_item_base_info',
      'GET'
    );
    productContext = `
San pham lien quan: ${product.response.item_list[0].item_name}
Gia: ${product.response.item_list[0].price_info.current_price} VND
Ton kho: ${product.response.item_list[0].stock_info_v2.summary_info.total_available_stock}`;
  }

  const reply = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 300,
    system: `Ban la nhan vien ho tro cua shop tren Shopee.
Quy tac:
- Tra loi ngan gon, than thien, bang tieng Viet
- Neu khach hoi ve san pham, dua thong tin chinh xac tu du lieu
- Neu khach hoi ve van de ngoai kha nang, de nghi chuyen cho quan ly
- Khong bao gio hua nhung gi shop khong dam bao duoc
- Thoi gian xu ly don: 1-2 ngay, giao hang: 3-5 ngay
${productContext}`,
    messages: [
      { role: 'user', content: content.text }
    ]
  });

  // Gửi phản hồi qua Shopee Chat
  await callShopeeAPI('/api/v2/sellerchat/send_message', 'POST', {
    to_id: buyer_id,
    message_type: 'text',
    content: { text: reply.content[0].text },
  });
}

Rate Limiting và quản lý chi phí

Khi tích hợp 2 API, bạn cần quản lý rate limit của cả hai bên:

Shopee API Rate Limits

• Mặc định: 10 requests/giây cho mỗi shop
• Một số endpoint có giới hạn riêng (ví dụ: Chat API: 5 requests/giây)
• Vượt quá giới hạn sẽ bị trả về lỗi 429

Claude API Rate Limits

• Phụ thuộc vào tier của bạn (Free, Build, Scale)
• Tier Build: 4,000 requests/phút, 400,000 tokens/phút
• Tier Scale: giới hạn cao hơn tùy theo hợp đồng

Chiến lược quản lý rate limit

class RateLimiter {
  constructor(maxRequests, windowMs) {
    this.maxRequests = maxRequests;
    this.windowMs = windowMs;
    this.requests = [];
  }

  async waitForSlot() {
    const now = Date.now();
    this.requests = this.requests.filter(
      (t) => now - t < this.windowMs
    );

    if (this.requests.length >= this.maxRequests) {
      const waitTime =
        this.windowMs - (now - this.requests[0]);
      await new Promise((resolve) =>
        setTimeout(resolve, waitTime)
      );
    }

    this.requests.push(Date.now());
  }
}

const shopeeRateLimiter = new RateLimiter(10, 1000);
const claudeRateLimiter = new RateLimiter(50, 60000);

async function rateLimitedShopeeCall(path, method, data) {
  await shopeeRateLimiter.waitForSlot();
  return callShopeeAPI(path, method, data);
}

async function rateLimitedClaudeCall(params) {
  await claudeRateLimiter.waitForSlot();
  return anthropic.messages.create(params);
}

Phân tích chi phí vận hành

Trước khi triển khai, hãy ước tính chi phí để đảm bảo ROI dương:

Chi phí Claude API

• Mô tả sản phẩm: Trung bình 500 input tokens + 800 output tokens = khoảng 0.01 USD/sản phẩm
• Phản hồi đánh giá: Trung bình 300 input tokens + 200 output tokens = khoảng 0.004 USD/phản hồi
• Báo cáo hàng ngày: Trung bình 2000 input tokens + 500 output tokens = khoảng 0.02 USD/báo cáo
• Chat tự động: Trung bình 400 input tokens + 150 output tokens = khoảng 0.005 USD/tin nhắn

Ước tính chi phí hàng tháng

Với một shop trung bình (100 sản phẩm mới/tháng, 500 đánh giá, 1000 tin nhắn chat):

• Mô tả sản phẩm: 100 x 0.01 = 1.00 USD
• Phản hồi đánh giá: 500 x 0.004 = 2.00 USD
• Báo cáo hàng ngày: 30 x 0.02 = 0.60 USD
• Chat tự động: 1000 x 0.005 = 5.00 USD
• Tổng cộng: khoảng 8.60 USD/tháng (khoảng 215,000 VND)

So với chi phí thuê nhân sự viết mô tả và phản hồi đánh giá, đây là khoản đầu tư rất hợp lý.

Xử lý lỗi và retry

Hệ thống production cần xử lý lỗi bền vững để tránh mất dữ liệu hoặc gửi phản hồi sai:

async function withRetry(fn, maxRetries = 3, delayMs = 1000) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      // Phân biệt lỗi có thể retry và không thể retry
      if (error.status === 400) throw error; // Bad request, không retry
      if (error.status === 401) throw error; // Auth lỗi, không retry

      console.log(
        `Attempt ${attempt} that bai, thu lai sau ${delayMs}ms...`
      );
      await new Promise((resolve) =>
        setTimeout(resolve, delayMs * attempt)
      );
    }
  }
}

// Sử dụng
const description = await withRetry(() =>
  generateProductDescription(productInfo)
);

Webhook server nhận thông báo từ Shopee

Để hệ thống phản ứng ngay khi có sự kiện (đơn hàng mới, đánh giá mới), bạn cần thiết lập webhook server:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/shopee', async (req, res) => {
  const { code, data } = req.body;

  try {
    switch (code) {
      case 3: // Cập nhật trạng thái đơn hàng
        await handleOrderUpdate(data);
        break;
      case 5: // Sản phẩm mới được tạo
        await autoDescribeNewProduct(data.item_id);
        break;
      case 12: // Có đánh giá mới
        await handleNewReview(data);
        break;
      case 14: // Tin nhắn chat mới
        await handleCustomerMessage(data);
        break;
      default:
        console.log(`Su kien chua xu ly: code ${code}`);
    }
    res.status(200).json({ message: 'OK' });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Webhook server dang chay tren port 3000');
});

Monitoring và logging

Để vận hành ổn định, bạn cần theo dõi hệ thống liên tục:

• Log mọi request: Ghi lại thời gian, endpoint, input/output, thời gian phản hồi và chi phí token
• Theo dõi tỷ lệ lỗi: Nếu tỷ lệ lỗi vượt quá 5%, gửi cảnh báo ngay
• Kiểm tra chất lượng output: Định kỳ review các mô tả và phản hồi Claude tạo ra để điều chỉnh prompt
• Theo dõi chi phí: Đặt ngưỡng chi phí hàng ngày/tháng và cảnh báo khi gần đạt

Triển khai production

Để triển khai hệ thống này trên production, bạn cần lưu ý:

• Sử dụng PM2 hoặc Docker để quản lý process
• Đặt server ở Singapore hoặc Hồ Chí Minh để giảm latency với Shopee API
• Sử dụng Redis queue (Bull/BullMQ) để xử lý hàng đợi thay vì xử lý trực tiếp
• Backup database token/session Shopee để tránh mất kết nối
• Thiết lập cron job refresh access token trước khi hết hạn (mỗi 4 giờ)

Bước tiếp theo

Bạn đã có toàn bộ kiến thức và code mẫu để xây dựng hệ thống tự động hóa Shopee với Claude API. Bắt đầu với một tính năng đơn giản (ví dụ: tự động tạo mô tả sản phẩm), chạy thử nghiệm, đánh giá chất lượng output rồi mở rộng dần sang các tính năng khác. Khám phá thêm các hướng dẫn thực hành tại Thư viện Ứng dụng Claude.