Hướng dẫn cài đặt và sử dụng WooSync - WooCommerce Sync Hub

Last updated on Aug 23, 2026 10:33 AM 10:33 AM 641.94 ms

WooSync cho Perfex CRM. Cầu nối tối ưu giữa WooCommerce và Perfex CRM. Đồng bộ hóa Sản phẩm, Đơn hàng và Khách hàng an toàn theo thời gian thực.

Tổng quan

Chào mừng bạn đến với tài liệu hướng dẫn kỹ thuật chính thức của WooSync. Mô-đun này hỗ trợ đồng bộ hóa tự động và an sau hệ sinh thái WooCommerce vào cơ sở dữ liệu Perfex CRM thông qua Webhooks và logic Delta Cron chạy ngầm.

Dù bạn đang quản lý một cửa hàng đơn lẻ hay một mạng lưới không giới hạn các cửa hàng WooCommerce (multi-store), WooSync hoạt động như một đường ống tự động kết nối liền mạch hai hệ thống.

Trang Demo các tính năng của WooSync:

Địa chỉ trang: https://woosync.polyxgo.com/admin

Khởi động nhanh

Nếu bạn muốn thiết lập hệ thống hoạt động nhanh chóng trong chưa đầy 3 phút:

Tải thư mục woosync lên thư mục perfex_crm/modules/ và kích hoạt nó.
In your WordPress/WooCommerce site, generate a REST API Key with Read/Write permissions.
Trong Perfex CRM, truy cập WooSync -> Stores -> Add Store và điền thông số kết nối. Tiến hành kiểm tra kết nối (Test connection).
Chọn chỉnh sửa cửa hàng vừa tạo để lấy thông tin Webhook Delivery URL và mã bảo mật Webhook Secret.
Trong WooCommerce, truy cập Settings -> Advanced -> Webhooks. Tạo mới các webhook (ví dụ: Order created, Product updated) trỏ về các thông số ở Bước 4. Dữ liệu từ nay sẽ được đồng bộ ngay lập tức.

Hướng dẫn Cài đặt & Thiết lập chi tiết

Để cài đặt và cấu hình an toàn WooSync mà không gây ảnh hưởng đến dữ liệu hiện tại:

Tải gói tập tin woosync.zip từ Codecanyon.
Truy cập mục Hệ thống (Setup) > Modules (Mô-đun) trong Perfex CRM.
Tải tệp zip lên qua khung Install Module và nhấn Kích hoạt (Activate).
Hệ thống sẽ tự động khởi tạo các bảng dữ liệu (ví dụ: tblwoosync_stores, tblwoosync_logs) cần thiết để vận hành.

Cấu hình kết nối (API & Webhooks)

1. Thiết lập WooCommerce REST API

REST API được sử dụng cho các lượt đồng bộ gia tăng (Delta Syncs), kiểm tra kết nối và chạy ngầm qua Cron.

Trong WordPress, truy cập WooCommerce > Cấu hình (Settings) > Nâng cao (Advanced) > REST API.
Tạo một API Key mới với quyền Read/Write (Đọc/Ghi).
Trong Perfex CRM, truy cập WooSync > Stores và thêm khóa vừa tạo. Nhấp "Test Connection" để xác thực kết nối hoạt động bình thường.

2. Thiết lập Webhooks (Khuyến nghị)

Webhooks truyền tải dữ liệu tức thì theo thời gian thực, loại bỏ sự phụ thuộc vào lịch chạy của máy chủ (cronjobs) và giảm thiểu độ trễ dữ liệu về mức bằng 0.

Nhấp vào biểu tượng chỉnh sửa cửa hàng của bạn trong Perfex để lấy URL nhận dữ liệu (Delivery URL) và chuỗi bảo mật Webhook Secret.
Trong WooCommerce, truy cập Settings > Advanced > Webhooks và tạo các webhook mới trỏ đến URL nhận đó.
Chúng tôi khuyến nghị theo dõi các sự kiện sau: product.created, product.updated, order.created, order.updated, customer.updated.

Tìm hiểu sâu các tính năng cốt lõi

1. Cơ chế đồng bộ im lặng (Silent Customer Automation)

Khi có đơn hàng mới đồng bộ về, WooSync tự động tạo hồ sơ Khách hàng (Client) và Người liên hệ (Contact) trong Perfex CRM tương ứng với thông tin người mua trên WooCommerce.

Giao thức đồng bộ im lặng: Tài khoản Contact được tạo ra sẽ được gán thuộc tính donotsendwelcomeemail = true và mật khẩu được tạo ngẫu nhiên bảo mật dài 20 ký tự. Cơ chế này đảm bảo khách hàng của bạn SẼ KHÔNG nhận được các email tự động mặc định của Perfex CRM khi đồng bộ đơn hàng sang.

2. Tự động hóa tạo Hóa đơn

Chỉ với một nút bật cấu hình trong thiết lập cửa hàng, các đơn hàng WooCommerce đã xử lý sẽ tự động chuyển đổi thành các hóa đơn Perfex CRM hợp lệ. Thuế và các dòng sản phẩm được ánh xạ tương ứng ngay lập tức.

Điều kiện kích hoạt thông minh: Để đảm bảo tính chính xác của dữ liệu kế toán, WooSync chỉ tạo hóa đơn khi đơn hàng WooCommerce đạt trạng thái Đã hoàn thành (Completed).

3. Biểu đồ lưới xử lý phía máy chủ (Server-Side Data Grids)

Để đảm bảo CRM luôn hoạt động mượt mà, bảng điều khiển WooSync sử dụng hoàn toàn cơ chế Ajax Server-Side. Việc lọc dữ liệu theo Store ID sẽ can thiệp trực tiếp vào câu lệnh SQL để truy xuất chính xác những gì bạn yêu cầu. Được thử nghiệm thành công với hơn 50.000 bản ghi đồng bộ mà không gây hiện tượng đơ lag trình duyệt.

4. Giả lập Cron Job trên localhost

Nếu bạn đang chạy môi trường phát triển cục bộ không có Linux Crontab (ví dụ dùng XAMPP) hoặc muốn kiểm thử thủ công các tiến trình nền: hãy bật Chế độ gỡ lỗi (Debug Mode) trong phần cài đặt. Hệ thống sẽ chèn một lệnh gọi pseudo_cron() thông qua trình duyệt của bạn để tự động chạy đồng bộ Delta Sync tương tự như trên máy chủ thật.

Tham chiếu kỹ thuật

Cấu trúc thư mục mô-đun

Cơ chế bảo mật

WooSync bảo vệ hệ thống Perfex CRM của bạn trước các cuộc gọi Webhook giả mạo.

Chữ ký HMAC-SHA256: Mọi dữ liệu gửi đến đều được mã hóa hash đối chiếu với chuỗi Secret được lưu trữ cục bộ. Nếu chữ ký trong tiêu đề X-WC-Webhook-Signature không trùng khớp, hệ thống sẽ trả về mã lỗi HTTP 401 Unauthorized ngay lập tức.
Giới hạn tần suất (Rate Limiting): Thuật toán cửa sổ trượt (Sliding Window) tự động ngăn chặn spam, chặn các yêu cầu gửi đến từ một IP nếu vượt quá 120 yêu cầu trong vòng một phút.

Các câu hỏi thường gặp (FAQs)

+Tôi có thể đồng bộ nhiều cửa hàng WooCommerce khác nhau bằng mô-đun này không?

Có, WooSync hỗ trợ đồng bộ đa cửa hàng không giới hạn. Bạn có thể kết nối nhiều shop WooCommerce tại menu WooSync > Stores và quản lý toàn bộ dữ liệu tập trung trên một giao diện Perfex CRM duy nhất.

+Mô-đun có hỗ trợ đồng bộ toàn bộ danh mục sản phẩm, đơn hàng và hóa đơn không?

Hoàn toàn có thể. Mô-đun bao phủ toàn bộ luồng dữ liệu, cho phép đồng bộ sản phẩm (danh mục, thẻ tag, thuộc tính), hồ sơ khách hàng, đơn hàng và tự động tạo hóa đơn Perfex tương ứng.

+Tôi có thể tắt tính năng tự động tạo hóa đơn không?

Có. Trong phần cấu hình cửa hàng, bạn chỉ cần bỏ chọn cấu hình “Auto-Create Invoice”. Khi đó đơn hàng chỉ đồng bộ dạng bản ghi thông thường vào CRM mà không tự động tạo hóa đơn tài chính.

+Nếu dữ liệu trên WooCommerce thay đổi sau đó, Perfex CRM có cập nhật theo không?

Có. Trình đồng bộ được thiết kế để theo dõi các thay đổi trạng thái dữ liệu. Dù thông qua Cron job chạy ngầm hay Webhook thời gian thực, mọi thay đổi (như cập nhật trạng thái đơn hàng sang 'completed' hoặc điều chỉnh giá sản phẩm) đều sẽ tự động đồng bộ đè lên và cập nhật lại trong Perfex CRM.

+Các đơn hàng hoặc sản phẩm mới có được đồng bộ ngay lập tức không?

Có. Bằng cách thiết lập Webhooks trên WooCommerce, WooSync sẽ lắng nghe các sự kiện thời gian thực. Các thao tác tạo đơn hàng mới, cập nhật sản phẩm hay khách hàng sẽ được CRM tiếp nhận xử lý ngay lập tức mà không phải chờ chu kỳ chạy của cron job.

+Việc đồng bộ khách hàng WooCommerce cũ có gửi các email "Chào mừng" làm phiền họ từ CRM không?

No. WooSync áp dụng Giao thức đồng bộ im lặng (Silent Sync Protocol). Toàn bộ hồ sơ khách hàng và liên hệ được tạo ẩn trong nền, gán mật khẩu ngẫu nhiên độ bảo mật cao và các sự kiện gửi mail chào mừng mặc định của Perfex CRM sẽ bị chặn hoàn toàn để tránh làm phiền khách mua hàng.

Tài liệu hướng dẫn & Hỗ trợ

Gói tải về đi kèm tài liệu hướng dẫn cài đặt chi tiết và hướng dẫn sử dụng các tính năng để bạn có thể cấu hình WooSync nhanh nhất.

Nếu cần hỗ trợ kỹ thuật, vui lòng gửi yêu cầu hỗ trợ qua phần bình luận trên Codecanyon. Đội ngũ của chúng tôi sẽ phản hồi sớm nhất kèm theo các hướng dẫn chi tiết.

Lịch sử các phiên bản

...

Kiến Trúc Hệ Thống & Luồng Quy Trình Đồng Bộ WooSync

graph TD
    subgraph WooCommerce Store ["WooCommerce Store (E-Commerce Platform)"]
        WC_Order["Order Placed / Updated"]
        WC_Customer["Customer Registered"]
        WC_Product["Product / Category Created"]
        WC_Refund["Order Refund Triggered"]
        WC_HPOS["HPOS (High-Performance Order Storage)"]
    end

    subgraph SyncEngine ["WooSync Synchronization Hub Engine"]
        WH_Receiver["Inbound Webhook Receiver<br/>(HMAC-SHA256 Signature Verification)"]
        Cron_Runner["Cron Delta Sync Fallback<br/>(Scheduled Polling Runner)"]
        Queue_Log["Queue & Audit Logger<br/>(Payload Tracking & Retries)"]
        AES_Enc["AES-256-CBC Encrypted Store API Keys"]
    end

    subgraph PerfexCRM ["Perfex CRM (Enterprise Platform)"]
        CRM_Client["Clients & Contacts Database"]
        CRM_Invoice["Invoices & Line Items"]
        CRM_Item["Products, Categories & Attributes"]
        CRM_Credit["Credit Notes & Refund Records"]
        CRM_Payment["Invoice Paid Status Event"]
    end

    WC_Order -->|Real-time Inbound Webhook| WH_Receiver
    WC_Customer -->|Real-time Inbound Webhook| WH_Receiver
    WC_Product -->|Real-time Inbound Webhook| WH_Receiver
    WC_Refund -->|Real-time Inbound Webhook| WH_Receiver

    WC_HPOS -.->|Scheduled Delta Poll| Cron_Runner
    WH_Receiver --> Queue_Log
    Cron_Runner --> Queue_Log

    Queue_Log -->|Auto-Create / Link Contact| CRM_Client
    Queue_Log -->|Auto-Generate Invoice| CRM_Invoice
    Queue_Log -->|Hierarchical Catalog Sync| CRM_Item
    Queue_Log -->|Generate Credit Note| CRM_Credit

    CRM_Payment -->|Reverse Sync Engine| WC_Order

Quy Trình Reverse Sync Engine

graph TD
    A["Perfex CRM Invoice Marked Paid"] --> B["Woosync_reverse_sync Engine Triggered"]
    B --> C{"Check Status Mapping Configuration"}
    C --> D["Resolve WooCommerce Store ID & Order ID"]
    D --> E["Decrypt API Secret Key via OpenSSL AES-256-CBC"]
    E --> F["Initialize WooCommerce REST API Client (wc/v3)"]
    F --> G["Send PUT Request to /wp-json/wc/v3/orders/{id}"]
    G --> H{"HTTP Response 200 OK?"}
    H -->|"Success"| I["Update Store Order Status (Processing -> Completed)"]
    H -->|"Failure"| J["Log Status Exception & Enqueue into Retry Queue"]

Chuyển Đổi Đơn Hàng Thành Hóa Đơn & Ánh Xạ HPOS

graph TD
    A["New Order Placed on WooCommerce Store (HPOS Order)"] --> B["Inbound Webhook order.created Listener"]
    B --> C["Verify HMAC-SHA256 Signature Secret"]
    C --> D{"Customer Email Exists in Perfex CRM?"}
    D -->|"No"| E["Auto-Create New Client Profile & Contact"]
    D -->|"Yes"| F["Link Order to Existing Client Profile"]
    E --> G["Map Billing & Shipping Location Addresses"]
    F --> G
    G --> H["Convert Store Currency & Sales Tax"]
    H --> I["Auto-Generate Perfex CRM Invoice (Unpaid)"]
    I --> J["Record Item Lines, Shipping Fee & Coupon Adjustments"]

Kết Nối Đa Cửa Hàng & Bảo Mật OpenSSL AES-256

graph TD
    A["Admin Adds New WooCommerce Store"] --> B["Input Store URL, Consumer Key, Consumer Secret & Webhook Secret"]
    B --> C["Encrypt Credentials using OpenSSL AES-256-CBC"]
    C --> D["Persist Record in woosync_stores Table"]
    D --> E["Auto-Register Inbound Webhook Endpoints"]
    E --> F["Test Connection via WooCommerce REST Client v3"]
    F --> G{"Connection Status 200 OK?"}
    G -->|"Success"| H["Activate Store Status & Start Real-Time Sync"]
    G -->|"Failure"| I["Log Alert Error & Display Credential Warnings"]