Track parcels with 17TRACK

Resolve SKILL_DIR to this skill's installation directory. Use the bundled CLI rather than recreating storage or signature handling. Commands return JSON; non-zero exit status means failure or an incomplete sync.

Setup

Set TRACK17_TOKEN through the host's secret store/environment; never print it. Set TRACK17_DATA_DIR to a private absolute directory outside the repository. Then run:

python3 "$SKILL_DIR/scripts/track17.py" init
python3 "$SKILL_DIR/scripts/track17.py" --help

This revision uses a new local schema. An old database containing packages is rejected without modification. Choose a new data directory, inspect/export the old records locally, and register only the parcels the user still wants. Do not delete the old database or automatically re-register everything: provider quota can be consumed.

Normal workflow

Prefer polling unless push delivery is needed. Read the current parcel list before adding or removing anything. Resolve parcel identity by tracking number plus carrier code, not a guessed local ID.

python3 "$SKILL_DIR/scripts/track17.py" list
python3 "$SKILL_DIR/scripts/track17.py" carriers-search DHL
python3 "$SKILL_DIR/scripts/track17.py" add RR123456789CN --label "Headphones"
python3 "$SKILL_DIR/scripts/track17.py" sync
python3 "$SKILL_DIR/scripts/track17.py" status RR123456789CN --carrier 3011 --refresh
python3 "$SKILL_DIR/scripts/track17.py" quota

Carrier numbers above are examples, not universal defaults. Use --carrier when automatic detection cannot resolve the carrier; use --param only when that carrier requires additional information. Registration success does not imply that tracking events are already available.

stop, retrack, and remove require the tracking number and --carrier. remove is local unless --delete-remote is explicitly supplied. Clarify remote deletion before executing it. After an ambiguous network failure, reconcile provider state before retrying a mutation; the client does not replay writes automatically.

Authenticated webhooks

17TRACK signs the original body bytes followed by / and the API security key with SHA-256. The signature arrives in the sign header. The helper uses TRACK17_TOKEN as that key; never invent a separate unrelated webhook secret or substitute HMAC for the provider's algorithm.

For captured deliveries, preserve the body unchanged and supply its real signature:

python3 "$SKILL_DIR/scripts/track17.py" ingest-webhook --file delivery.json --signature "$DELIVERY_SIGN"

For push delivery:

python3 "$SKILL_DIR/scripts/track17.py" webhook-server --port 8789

The receiver binds to loopback. Put an intentionally configured TLS reverse proxy in front of it, preserving sign and the raw body. Do not expose a development server casually. Missing, invalid, or duplicate authentication headers fail; accepted delivery is acknowledged only after the database transaction commits. Storage failures return a failure response so the provider can retry. There is no unsigned import path or deferred inbox processor.

Identical deliveries are idempotent. Older dated updates cannot overwrite a newer dated snapshot. This is not universal ordering: timestamps do not resolve same-time corrections or prove the freshness of undated updates. Report event time separately from local receipt time.

Report

Prioritise delivered, out-for-delivery, pickup, failed delivery, and exceptions. Include the carrier, event time, and last successful refresh; distinguish saved state from a fresh provider response. Treat partial syncs and missing events as incomplete evidence, not “no changes”. Never infer a delivery date from an unrelated parcel or a stale snapshot.

Sources and checks

17TRACK API documentation, reviewed 2026-09-13, documents the signing scheme and explicitly keeps v2.2 online. This helper deliberately retains that supported response contract; v2.4 is not a drop-in version-string change because additional registration fields differ.

Run offline and loopback HTTP regressions:

python3 -m unittest discover -s "$SKILL_DIR/tests" -v

updated_at records snapshot changes; last_refreshed_at records the most recent accepted polling response, including an unchanged snapshot. Neither is the carrier event time. Webhook receipt/deduplication does not count as a successful poll.