55 lines
3.2 KiB
Markdown
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.
|