Guide to Install an Use WooSync - WooCommerce Sync Hub

WooSync for Perfex CRM. The ultimate bridge between WooCommerce and Perfex CRM. Synchronize Products, Orders, and Customers securely in real-time.

...

Overview

Welcome to the official technical manual for WooSync. This module synchronizes WooCommerce ecosystems securely and automatically into Perfex CRM databases via Webhooks and Delta Cron logic.

Whether you are managing a single shop or an unlimited network of multi-store WooCommerce environments, WooSync acts as an automated pipeline bridging the gap seamlessly.

Demo of WooSync features:

Site: https://woosync.polyxgo.com/admin

Quick Start

If you’re in a hurry to get everything running in under 3 minutes:

• Upload the woosync folder to your perfex_crm/modules/ directory and activate it.

• In your WordPress/WooCommerce site, generate a REST API Key with Read/Write permissions.

• Inside Perfex CRM, head to WooSync -> Stores -> Add Store and plug in the credentials. Test the connection.

• Edit the Store to reveal your generated Webhook Delivery URL and Webhook Secret.

• In WooCommerce, go to Settings -> Advanced -> Webhooks. Add webhooks (e.g. Order created, Product updated) using the details from step 4. Data will now arrive instantly.

Full Installation & Setup

To safely install and configure WooSync without data interruption:

• Download the woosync.zip package from codecanyon.

• Go to Setup > Modules in the Perfex CRM admin area.

• Upload the zip file via the Install Module prompt and click Activate.

• This will automatically mount database tables (e.g. tblwoosync_stores, tblwoosync_logs) required for operation.

Configuration (API & Webhooks)

1. Setting up WooCommerce REST API

We use REST API for initial Delta Syncs, connection tests, and Background Cron retrieval.

• In WordPress, navigate to WooCommerce > Settings > Advanced > REST API.

• Generate an API Key with Read/Write permissions.

• In Perfex CRM, go to WooSync > Stores and add the keys. Run the “Test Connection” tool to verify viability.

2. Setting up Webhooks (Recommended)

Webhooks transmit data in real-time, removing reliance on periodic server tasks (cronjobs) while keeping traffic latency strictly zero.

• Click the “Edit” icon on your Store in Perfex to reveal your Delivery URL and Webhook Secret hash.

• In WooCommerce, head to Settings > Advanced > Webhooks and add new hooks pointing to that URL.

• We recommend tracking the following topics: product.created, product.updated, order.created, order.updated, customer.updated.

Core Features Deep Dive

1. Silent Customer Automation

When an order arrives, WooSync naturally builds a Perfex CRM Client and Contact associated with the WooCommerce Customer data.

Silent Sync Protocol: The Contact is explicitly generated with donotsendwelcomeemail = true and given a highly-secure randomized 20-character hash password, guaranteeing the client is NEVER spammed or accidentally notified via native Perfex logic when migrating.

2. Automated Invoicing

Enable a single toggle on your store config to transform WooCommerce processed orders straight into legally compliant Perfex Invoices. Tax and Line Items are mapped instantaneously.

Smart Trigger: To ensure accounting accuracy, WooSync strictly generates invoices only when a WooCommerce order reaches the Completed status.

3. Server-Side Data Grids

To keep the CRM ultra-responsive, the WooSync dashboard operates purely on Ajax-powered Server-Side processing. Sorting by WooCommerce Store ID immediately intercepts the SQL queries to output precisely what you request. Tested successfully with 50,000+ synchronized components without browser lag.

4. Localhost Pseudo-Cron

If you lack a Linux Crontab (e.g. XAMPP usage) or just want to manually test background processes natively: toggle Debug Mode in the settings. This injects a delayed pseudo_cron() request via your browser window, running Delta Sync automatically just like a production server.

Technical Reference

Directory Structure

modules/woosync/
├── controllers/          # Webhook logic & Ajax Tables
├── libraries/            # Synchronization Engines & HMAC verification
├── models/               # Perfex CRUD abstractions
├── views/                # Settings, Modals, Forms
└── woosync.php           # Hooks, Actions, Module Genesis

Security Mechanisms

WooSync actively protects the Perfex application from maliciously crafted Webhook pings.

• HMAC-SHA256 Signatures: Every incoming payload is hashed against the locally stored Secret. If the signature in the X-WC-Webhook-Signature header fails the check, an HTTP 401 Unauthorized is returned outright.

• Rate Limiting: A Sliding Window threshold dynamically shields against spam, stopping requests from an IP if it bursts above 120 triggers a minute.

Troubleshooting & FAQ

+Can I sync multiple different WooCommerce stores using this module?

Yes, WooSync fully supports multi-store synchronization. You can connect an unlimited number of WooCommerce stores from the WooSync > Stores menu and manage all their data centrally within a single Perfex CRM dashboard.

+Can I sync the entire catalog including products, categories, orders, and invoices?

Absolutely. The module provides complete coverage. It synchronizes your product catalog (products, categories, tags, and attributes), customer profiles, WooCommerce orders, and can automatically generate corresponding Perfex Invoices.

+Can I disable the automated invoice creation?

Yes. When adding or configuring a store, simply uncheck the “Auto-Create Invoice” setting. Orders will then sync normally into the CRM as standalone records without spawning any financial invoices.

+If data is modified on the WooCommerce store later, will it update in Perfex CRM?

Yes. The sync engine is designed to track state changes. Whether through the scheduled Delta Cron or real-time Webhooks, any updates (such as an order status changing to ‘completed’ or a product price adjustment) will be automatically overwritten and reflected in Perfex CRM.

+Are new orders or products synced instantly when created on the store?

Yes. By configuring Webhooks in your WooCommerce dashboard, WooSync listens to real-time events. Actions like order.created, product.updated, or customer.updated are instantly caught and processed by the CRM without waiting for periodic cron jobs.

+Will syncing existing WooCommerce customers send them annoying “Welcome” emails from the CRM?

No. WooSync uses a Silent Sync Protocol. During the import, CRM Clients and Contacts are built in the background, assigned highly secure random passwords, and Perfex’s native welcome email triggers are strictly suppressed to avoid spamming your buyers.

Documentation & Support

The downloaded package includes a complete installation guide and feature documentation so you can configure WooSync quickly.

For assistance, submit a support ticket through the Codecanyon comment section. Our team responds as soon as possible with detailed guidance.

Version History

...

System Architecture & Synchronization Data Workflow

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

Reverse Sync Engine Workflow

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"]

Order-to-Invoice Conversion & HPOS Field Mapping

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"]

Multi-Store Connection & Security Workflow

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"]