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

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ữ nó 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ẻ công khai hoặc commit vào hệ thống quản lý 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ợ giá trị phân cách bằng dấu phẩy: pending,processing
• productType (bắt buộc đối với đơ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 con
• 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)

Ví dụ Phản hồi

{
  "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" mới được trả về
• Các đơ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. Các giá trị hợp lệ: pending, processing, completed, partial, cancelled, error
• accounts (tùy chọn, đối với đơ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 các 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 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

Các Lỗi Thường gặp

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

   {
         "error": "INVALID_API_KEY",
         "message": "Invalid API key"
       }

   Giải pháp: Kiểm tra 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": "Order not found"
       }

   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": "You do not have access to this order"
       }

   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": "No valid accounts provided after deduplication"
       }

   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ể hoàn thành 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ổng kết

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

1. Lấy đơ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 từng đơn hàng
3. Gửi tài khoản: POST /api/admin/v2/orders-update kèm 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ủa mình!

Cả hai đều là tài liệu hướng dẫn chính 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.