WooCommerce Order Sync Pronto API

WooCommerce Order Sync Pronto API Plugin

This plugin automatically syncs WooCommerce orders with the Pronto API upon successful processing. The plugin includes features like a manual sync button, order status sync logs, a sync status page, and automatic status checks to retrieve Pronto Order numbers.

Installation

1. Upload the wcospa folder to the /wp-content/plugins/ directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Configure your API credentials in the wcospa-credentials.php file located in includes/.

Order Processing Workflow

1. Order Sync Initiation

   • Triggered by handle_order_sync() method
   • Sync request sent to Pronto API
   • On success, order status updated to 'Preparing to Ship'
   • Scheduled task created to fetch Pronto order number after 120 seconds

2. Pronto Order Number Retrieval

   • Scheduled task scheduled_fetch_pronto_order() executes
   • Checks for existing Pronto order number in meta data
   • If no number exists, fetches from API
   • Stores number using: update_post_meta($order_id, '_wcospa_pronto_order_number', $pronto_order_number)

3. Order Meta Data Storage

   • Pronto order number stored with key: _wcospa_pronto_order_number
   • Visible in WooCommerce order admin interface
   • Displayed in custom column in orders list

Key Configurations

Time Intervals and Limits

The plugin operates with the following configured time intervals:

• Initial Wait Period: 120 seconds before first Pronto order number fetch
• Retry Interval: 30 seconds between retry attempts
• Request Delay: 3 seconds between different orders
• Maximum Retry Count: 5 attempts
• Pending Order Cron: Legacy 3-second/60-second cron removed in 1.6.10b; processing now relies on per-order single events scheduled during sync

Order Status Management

The following order statuses are excluded from processing:

• Shipped
• Delivered
• Cancelled
• On Hold
• Completed
• Refunded
• Failed

Meta Data Fields

The plugin utilises these meta fields for order tracking:

• _wcospa_transaction_uuid: Transaction identifier
• _wcospa_sync_time: Synchronisation timestamp
• _wcospa_fetch_retry_count: Number of fetch attempts
• _wcospa_pronto_order_number: Pronto order reference
• _wcospa_shipment_number: Shipping tracking number

Debtor Code Configuration

The plugin automatically assigns the correct Pronto debtor code based on the site domain:

Site Domain	Debtor Code
zerotech.com.au / store.zerotechoptics.com	210942 (default)
zerotechoutdoors.com.au	211027
nitecoreaustralia.com.au	211023
skywatcheraustralia.com.au	211026
pulsaroutdoors.com.au	211035
pulsarvision.com.au	211036
pulsarwildlife.com.au	211037

Debtor codes can be manually overridden via WooCommerce > Sync Status admin page.

Shipment Tracking

Advanced Shipment Tracking integration:

• Provider Name: "Australia Post"
• Automatic status update to "Completed" upon tracking number receipt
• Tracking information added automatically after successful fetch

Supported Payment Methods

The plugin supports the following payment gateways with automatic mapping to Pronto API:

Payment Gateway	WooCommerce ID	Pronto Code	Bank Code	Description
PayPal	ppcp	PP	PAYPAL	PayPal
AfterPay	afterpay	CC	Dynamic*	AfterPay
Stripe Credit Card	stripe_cc	CC	STRIPE	Stripe - Credit Card
ZIP	stripe_zip	CC	STRIPE	ZIP
Apple Pay	stripe_applepay	CC	STRIPE	Apple Pay

*AfterPay bank code is dynamically determined based on the site domain (configured in admin settings).

All payment methods automatically add a descriptive line item to the order for accountant reference.

Key Action Hooks

The plugin responds to these WordPress hooks:

• woocommerce_order_status_processing: Triggers order synchronisation
• wcospa_fetch_pronto_order_number: Initiates Pronto order number fetch
• wcospa_process_pending_orders: Legacy fallback hook retained for manual invocation (automatic 3-second cron removed in 1.6.10b)
• wcospa_pronto_order_number_received: Handles successful order number receipt

The plugin introduces a custom order status:

• Status Name: "Preparing to Ship" (wc-preparing-to-ship)
• Visual Indicator: Orange background with white text
• Automatically applied after successful API synchronisation

Core Functionality Flow

1. Order Synchronisation:

   • Triggered when order status changes to "processing"
   • Obtains transaction UUID
   • Initiates 120-second wait period
   • Attempts to fetch Pronto order number
   • Immediately attempts to fetch shipment number upon success

2. Pronto Order Number Retrieval:

   • Maximum of 5 retry attempts
   • 30-second interval between retries
   • 3-second delay between different orders

3. Shipment Number Processing:

   • Automatic retrieval upon Pronto order number receipt
   • Manual retrieval via "Get Shipping" button
   • Automatic integration with Advanced Shipment Tracking
   • Updates order status upon successful tracking addition

License

This plugin is licensed under the GPLv2 or later. For more information, see https://www.gnu.org/licenses/gpl-2.0.html.

Changelog

1.6.12

• Feature: Implemented GitHub-based automatic update notification system
  • Added WCOSPA_Updater class (includes/class-wcospa-updater.php) that integrates with WordPress's native plugin update UI — no third-party plugin required
  • Checks GitHub Releases API every 12 hours (cached via transient) and compares the latest release tag against the installed version
  • When a newer version is available, injects a standard WordPress update record so the Plugins screen displays the familiar "Update available" notice and "View version details" thickbox link
  • Administrators can update directly from the WordPress Plugins screen; WordPress downloads the release ZIP from GitHub and replaces plugin files automatically
  • Optional WCOSPA_GITHUB_TOKEN constant (defined in wp-config.php) supports private repositories and raises GitHub API rate limit from 60 to 5,000 requests per hour
  • Optional WCOSPA_GITHUB_REPO constant overrides the default repository slug
  • Release cache is cleared automatically after a successful update
  • All check results (new version found, up to date, API errors) are written to the plugin log

1.6.11

• Refactor: Simplified per-order log file structure from nested subdirectories to flat files
  • Order log files are now written directly to logs/order-{order_id}.log instead of logs/orders/{subdir}/order-{order_id}.log
  • Removed subdirectory grouping logic (sprintf('%04d', $order_id % 100)) and associated wp_mkdir_p() calls in flush_order_buffer()
  • Updated cleanup_old_logs() to scan order-*.log* in the flat logs directory instead of recursively traversing subdirectories
  • Updated get_log_stats() to use flat globs; order_directories stat is always 0 and retained for backward compatibility
  • Updated get_logged_orders() to use a flat glob($logs_dir . '/order-*.log') instead of glob($orders_dir . '/**/order-*.log', GLOB_NOSORT)
  • Updated admin Sync Status page log path display to reflect the new flat structure
  • Reduces filesystem operations, eliminates empty directory cleanup, and makes order log files easier to locate and manage

1.6.10f

• Configuration Update: Added support for three new Pulsar websites
  • Added debtor code mapping for pulsaroutdoors.com.au (211035)
  • Added debtor code mapping for pulsarvision.com.au (211036)
  • Added debtor code mapping for pulsarwildlife.com.au (211037)
  • Updated admin interface to display all site-specific debtor code mappings
  • Updated documentation with complete debtor code configuration table

1.6.10e

• Compatibility Fix: Prevent Pronto sync failures caused by emoji / invalid UTF-8 in customer-provided text
  • Sanitises all string fields in the outgoing Pronto order payload before JSON encoding (removes non-BMP characters such as emoji, strips invalid UTF-8/control characters)
  • Logs a warning on the order when sanitisation occurs, while preserving the rest of the content

1.6.10d

• Capacity Increase: Increased scheduled shipment processing batch size
  • Increased process_pending_shipments() batch size from 10 to 30 orders per scheduled run

1.6.10c

• Reliability Fix: Bulk "Obtain Shipping Number" no longer skips eligible orders
  • Switched bulk shipment processing to sequential processing (one order per request) with stable "next eligible order" selection
• Simplification: Removed weekend marker logic and legacy shipment queue gating
  • Removed weekend-related marker logic from bulk sync
  • Removed legacy shipment queue time gate (WCOSPA_Utils::is_shipment_check_time() and related shipment queue path) so shipment processing follows WCOSPA_Shipment_Handler scheduled events and manual buttons only
• Behaviour Change: Removed per-order shipment retry throttle
  • Removed the per-order 1-hour shipment retry throttle (WCOSPA_Shipment_Handler::RETRY_INTERVAL = 3600 and _wcospa_last_tracking_attempt) so scheduled shipment runs always attempt eligible orders
• Docs: Updated 条件触发.md to reflect the above changes

1.6.10b

• Performance Fix: Removed legacy 3-second cron job that repeatedly hit wcospa_process_pending_orders
  • Eliminated every_three_seconds cron schedule and associated custom interval registration
  • Added automatic cleanup that clears the legacy schedule on init and activation, preventing future CPU spikes
  • Pending orders now rely solely on per-order single events created during sync (no recurring polling)
  • Significantly reduces server load (28,800 daily executions removed) while keeping retry safeguards
  • Documentation updated to reflect the removal of the cron-based queue

1.6.10

• Critical Fix: Payment verification and failure detection to prevent syncing orders with failed payments
  • Payment verification added: Orders must pass is_paid() check before syncing to Pronto
  • Race condition protection: Additional status checks prevent syncing orders in failed/on-hold/cancelled/refunded states
  • Payment failure detection: Automatic detection when orders are cancelled or fail after being synced
  • Email notifications: Sends alerts to sales@tsaoutdoors.com.au, warehouse@tsaoutdoors.com.au, mj@tsaoutdoors.com.au, and jli@tsaoutdoors.com.au
  • Comprehensive email details: Includes WooCommerce order number, Pronto order number, customer details, payment info, and required actions
  • Smart notifications: Only sends emails if order was actually synced to Pronto (prevents false alerts)
  • Complete logging: All payment verification failures and cancellations logged with order context
  • Prevents Stripe 3D Secure failures, fraud detection holds, and authorization/capture mismatches from creating orphaned Pronto orders

1.6.9b

• Fix: Improved API response logging quality and completeness
  • Replaced print_r() with wp_json_encode() for structured logging
  • Fixed truncated log entries for large API responses
  • Updated all deprecated self::log() calls to use new WCOSPA_Logger with order context
  • JSON-formatted logs are easier to read and won't be cut off mid-response
  • Better debugging capability for API communication issues

1.6.9a

• Fix: Reduced excessive debug logging in production
  • Removed verbose DEBUG logs from init() method that were being called on every page load
  • Now only logs when actually setting up new schedules (INFO level)
  • Eliminated "Shipment tracking events already scheduled, skipping setup" repetitive messages
  • Significantly reduced log file size and improved performance
  • Only meaningful events are now logged (schedule creation, processing runs, errors)

1.6.9

• Performance Enhancement: Increased shipment tracking processing capacity and speed
  • Doubled processing capacity: Increased from 5 to 10 orders per scheduled run
  • Faster processing: Reduced delay between orders from 3 seconds to 1 second
  • Improved throughput: Can now process up to 10 orders in ~10 seconds (vs 5 orders in ~15 seconds previously)
  • Better handling of backlogs: Weekly capacity increased from 90 orders to 180 orders maximum
  • Monday-Thursday capacity: 40 orders per day (4 runs × 10 orders) vs previous 20 orders
  • Friday capacity: 20 orders per day (2 runs × 10 orders) vs previous 10 orders
  • API rate compliance: Still well within 10 calls/second limit (~1 call/second during processing)
  • All orders still benefit from automatic recovery, retry mechanisms, and comprehensive logging