Hướng dẫn API Nhà cung cấp: Xử lý Đơn hàng Thủ công

Điều kiện tiên quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

• Tài khoản nhà cung cấp có quyền truy cập API
• Khóa API của bạn (bạn có thể tạo từ bảng điều khiển nhà cung cấp)
• Quyền truy cập vào các điểm cuối Admin API v2

Bước 1: Lấy Khóa API của Bạn

1. Đăng nhập vào bảng điều khiển nhà cung cấp của bạn
2. Điều hướng đến Cài đặt API (/api-settings)
3. Nhấp vào "Tạo Khóa API" nếu bạn chưa có
4. Sao chép khóa API của bạn và giữ an toàn

Quan trọng: Khóa API của bạn phải được giữ bí mật. Không bao giờ chia sẻ nó công khai hoặc đưa vào hệ thống kiểm soát phiên bản.

Bước 2: Lấy Đơn hàng Thủ công

Sử dụng điểm cuối GET /api/admin/v2/orders để lấy các đơn hàng thủ công đang chờ xử lý và đang xử lý.

Yêu cầu API

curl -X GET "https://your-domain.com/api/admin/v2/orders?status=pending,processing&productType=manual&limit=50&offset=0" \
  -H "X-Api-Key: YOUR_API_KEY"

Tham số Yêu cầu

• status (tùy chọn): Bộ lọc trạng thái đơn hàng. Hỗ trợ các giá trị phân tách bằng dấu phẩy: pending,processing
• productType (bắt buộc cho đơn hàng thủ công): Đặt thành manual
• entityType (tùy chọn): Lọc theo product hoặc smm_service
• subCategory (tùy chọn): Lọc theo tên danh mục phụ
• limit (tùy chọn): Số lượng đơn hàng trả về (tối đa 500, mặc định 50)
• offset (tùy chọn): Độ lệch phân trang (mặc định 0)

Phản hồi Ví dụ

{
  "orders": [
    {
      "id": 12345,
      "order": 12345,
      "status": "pending",
      "paymentStatus": "completed",
      "quantity": 10,
      "user": {
        "id": "507f1f77bcf86cd799439011",
        "email": "customer@example.com",
        "name": "John Doe"
      },
      "items": [
        {
          "product": {
            "id": "507f1f77bcf86cd799439012",
            "name": "Instagram Followers",
            "type": "product"
          },
          "quantity": 10,
          "unitPrice": 5.00,
          "totalPrice": 50.00
        }
      ],
      "createdAt": "2024-01-01T10:00:00.000Z"
    }
  ],
  "count": 1,
  "total": 1
}

Lưu ý Quan trọng

• Chỉ các đơn hàng có paymentStatus: "completed" được trả về
• Đơn hàng được lọc để ngăn xử lý trùng lặp (khoảng thời gian 30 phút)
• Bạn chỉ có thể xem các đơn hàng cho sản phẩm/dịch vụ thuộc về bạn với tư cách là nhà cung cấp

Bước 3: Xử lý Đơn hàng và Gửi Tài khoản

Sau khi có đơn hàng, hãy xử lý chúng và chuẩn bị thông tin đăng nhập tài khoản. Sau đó sử dụng điểm cuối POST /api/admin/v2/orders-update để gửi tài khoản và cập nhật trạng thái đơn hàng.

Yêu cầu API

curl -X POST "https://your-domain.com/api/admin/v2/orders-update" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "order": 12345,
    "status": "completed",
    "accounts": [
      "username1:password1",
      "username2:password2",
      "username3:password3"
    ],
    "supplierOrderId": "SUP-ORDER-12345"
  }'

Tham số Nội dung Yêu cầu

• order (bắt buộc): ID đơn hàng (số)
• status (tùy chọn): Trạng thái đơn hàng mới. Giá trị hợp lệ: pending, processing, completed, partial, cancelled, error
• accounts (tùy chọn, cho đơn hàng sản phẩm): Mảng thông tin đăng nhập tài khoản theo định dạng "username:password" hoặc "email:password"
• supplierOrderId (tùy chọn): ID đơn hàng nội bộ của bạn để theo dõi

Định dạng Tài khoản

Đối với đơn hàng sản phẩm, tài khoản nên được cung cấp dưới dạng một mảng chuỗi. Mỗi chuỗi đại diện cho một tài khoản:

• Định dạng: "username:password" hoặc "email:password"
• Ví dụ: ["user1:pass123", "user2:pass456"]
• Số lượng: Cung cấp số lượng tài khoản khớp với số lượng đơn hàng

Ví dụ Quy trình Hoàn chỉnh

Đây là một ví dụ hoàn chỉnh sử dụng JavaScript/Node.js:

const axios = require('axios');

const API_BASE_URL = 'https://your-domain.com/api/admin/v2';
const API_KEY = 'YOUR_API_KEY';

// Bước 1: Lấy các đơn hàng thủ công đang chờ xử lý và đang xử lý
async function getOrders() {
  try {
    const response = await axios.get(`${API_BASE_URL}/orders`, {
      params: {
        status: 'pending,processing',
        productType: 'manual',
        limit: 50,
        offset: 0
      },
      headers: {
        'X-Api-Key': API_KEY
      }
    });
    
    return response.data.orders;
  } catch (error) {
    console.error('Lỗi khi lấy đơn hàng:', error.response?.data || error.message);
    throw error;
  }
}

// Bước 2: Xử lý đơn hàng và gửi tài khoản
async function updateOrder(orderId, accounts, supplierOrderId) {
  try {
    const response = await axios.post(
      `${API_BASE_URL}/orders-update`,
      {
        order: orderId,
        status: 'completed',
        accounts: accounts,
        supplierOrderId: supplierOrderId
      },
      {
        headers: {
          'X-Api-Key': API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('Lỗi khi cập nhật đơn hàng:', error.response?.data || error.message);
    throw error;
  }
}

// Quy trình chính
async function processOrders() {
  try {
    // Lấy đơn hàng
    const orders = await getOrders();
    console.log(`Tìm thấy ${orders.length} đơn hàng cần xử lý`);
    
    // Xử lý từng đơn hàng
    for (const order of orders) {
      console.log(`Đang xử lý đơn hàng ${order.id}...`);
      
      // Chuẩn bị tài khoản (đây là nơi bạn sẽ lấy từ hệ thống của mình)
      const accounts = [
        'user1:pass1',
        'user2:pass2',
        // ... thêm tài khoản khớp với order.quantity
      ];
      
      // Cập nhật đơn hàng với tài khoản và đánh dấu là đã hoàn thành
      const updatedOrder = await updateOrder(
        order.id,
        accounts,
        `SUP-${order.id}`
      );
      
      console.log(`Đơn hàng ${order.id} đã hoàn thành thành công`);
    }
  } catch (error) {
    console.error('Lỗi trong quy trình:', error);
  }
}

// Chạy quy trình
processOrders();

Xử lý Lỗi

Lỗi Thường gặp

1. Khóa API Không hợp lệ

   {
         "error": "INVALID_API_KEY",
         "message": "Khóa API không hợp lệ"
       }

   Giải pháp: Kiểm tra xem khóa API của bạn có chính xác và đang hoạt động không.

2. Không tìm thấy Đơn hàng

   {
         "error": "ORDER_NOT_FOUND",
         "message": "Không tìm thấy đơn hàng"
       }

   Giải pháp: Xác minh ID đơn hàng tồn tại và thuộc về bạn.

3. Truy cập Bị từ chối

   {
         "error": "ACCESS_DENIED",
         "message": "Bạn không có quyền truy cập vào đơn hàng này"
       }

   Giải pháp: Đảm bảo đơn hàng chứa sản phẩm/dịch vụ thuộc về bạn.

4. Tài khoản Không hợp lệ

   {
         "error": "INVALID_ACCOUNTS",
         "message": "Không có tài khoản hợp lệ nào được cung cấp sau khi loại bỏ trùng lặp"
       }

   Giải pháp: Đảm bảo mảng tài khoản không trống và chứa các chuỗi hợp lệ.

Thực hành Tốt nhất

1. Tần suất Kiểm tra: Không kiểm tra quá thường xuyên. API ngăn chặn xử lý trùng lặp với khoảng thời gian 30 phút.
2. Xử lý Lỗi: Luôn triển khai xử lý lỗi và logic thử lại phù hợp.
3. Xác thực Tài khoản: Xác thực tài khoản trước khi gửi để đảm bảo chúng đúng định dạng.
4. Theo dõi Đơn hàng: Sử dụng supplierOrderId để theo dõi đơn hàng trong hệ thống của bạn.
5. Cập nhật Trạng thái: Bạn có thể cập nhật trạng thái theo từng bước:
   • Đầu tiên đặt thành processing khi bạn bắt đầu xử lý
   • Sau đó đặt thành completed khi tài khoản đã sẵn sàng
6. Đơn hàng Một phần: Nếu bạn chỉ có thể đáp ứng một phần đơn hàng, hãy đặt trạng thái thành partial và gửi các tài khoản có sẵn.

Tóm tắt

Quy trình làm việc hoàn chỉnh là:

1. Nhận Đơn hàng: GET /api/admin/v2/orders?status=pending,processing&productType=manual
2. Xử lý Đơn hàng: Chuẩn bị tài khoản cho mỗi đơn hàng
3. Gửi Tài khoản: POST /api/admin/v2/orders-update với tài khoản và status: "completed"

Quy trình ba bước đơn giản này cho phép bạn tự động hóa hoàn toàn quy trình xử lý đơn hàng!

Cả hai đều là tài liệu hướng dẫn cốt lõi cho nhà cung cấp. Liên kết chúng giúp nhà cung cấp điều hướng từ thiết lập sản phẩm đến xử lý đơn hàng, tạo ra một quy trình làm việc hợp lý. hướng dẫn quản lý sản phẩm.