# 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: ```bash 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: ```text 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: ```bash 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.