esun3d/app/code/Esun/SeventeenTrack

Esun_SeventeenTrack

Magento 2 integration for 17TRACK v2.4.

Behavior

• The customer order detail page calls YQV5.trackSingle() for each Magento shipment tracking number. There is no search input.
• Every ten minutes, cron registers new and existing Magento shipment tracking numbers in batches of at most 40, then calls gettrackinfo.
• A shipment is signed for when track_info.latest_status.status is Delivered.
• If automatic receipt is enabled, a shipped order changes to received only after all of its tracking numbers are delivered.
• Rejected API rows make the Magento cron record fail instead of appearing successful. Transient failures retry after 30 minutes; quota failures retry after six hours and create a deduplicated critical admin notification.
• Query failures keep an already registered number in the tracking state. Error -18019902 moves it back to registration instead of leaving it in a query-error loop.
• Signed Webhook notifications update the same tracking table immediately; cron remains as a recovery path when a push is delayed or missed.
• Every registration result and every incoming webhook outcome is written to esun_seventeen_track_api_log. API keys, signatures, phone numbers, postal codes, addresses, and similar sensitive fields are redacted before storage.

Configuration

On a new environment, enable and install the module first:

php bin/magento module:enable Esun_SeventeenTrack
php bin/magento setup:upgrade --keep-generated
php bin/magento cache:flush

Go to Stores > Configuration > Esun > 17TRACK:

1. Enter the API key. Magento stores it through the encrypted configuration backend.
2. Set Enabled to Yes.
3. Leave Mark Orders Received Automatically enabled to update delivered orders.

The customer widget is independent of the server API toggle and can be enabled or disabled separately.

In the 17TRACK API dashboard, set Small package tracking push > URL to:

https://www.esun3d.com/seventeentrack/webhook/index

The endpoint accepts POST requests only, verifies the sign header against the exact raw body and encrypted API key, and returns HTTP 200 after successful processing.

Operations

Run one synchronization manually and receive a non-zero exit status when any tracking number fails:

php bin/magento esun:17track:sync

Inspect esun_seventeen_track.error_code, attempt_count, next_attempt_at, and last_error when diagnosing a number. A quota error must be resolved in the 17TRACK account before a later retry can register the shipment.

Go to Esun > 17TRACK > API Logs in Magento Admin to filter logs by time, direction, operation, status, order number, tracking number, webhook event, HTTP status, or error code. Use View Details to inspect the sanitized request and response. Registration rows from the same API batch share a batch ID.

The customer-facing widget is a cross-origin 17TRACK iframe. If Chrome DevTools has Pause on caught exceptions enabled, Chrome can pause inside 17TRACK, Cloudflare, or another third-party script even though this module contains no debugger statement. Disable that DevTools option or add the third-party script to the Ignore List; this cannot be reliably controlled by Magento code inside the parent page.