Files
2026-09-15 10:35:56 +08:00

55 lines
3.2 KiB
Markdown

# 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.