17TRACK

📄️Test Connection

Validate a 17TRACK API key WITHOUT persisting an instance — powers the connect-modal `Test Connection` button.

Persist the singleton 17TRACK instance for this tenant. The `WebhookRoutable` trait mints a unique `wh_*` token as part of the create flow — the resulting webhook URL is returned in the response so it can be copied into the tenant's 17TRACK dashboard.

📄️Get 17TRACK Instance

Return the 17TRACK instance enriched with the LIVE dashboard summary — quota, per-status counts, the webhook URL, and the most recent webhook + event timestamps. This is the payload that powers the connect dashboard.

📄️Update 17TRACK Instance

Patch any combination of `name`, `api_key`, per-entity `auto_track` toggles, or the `is_automatic_sync_enabled` flag on the singleton instance. All fields are optional; only the keys present in the request body are applied.

📄️Disconnect 17TRACK Instance

Disconnect 17TRACK. Per the PRD edge-case spec:

📄️Get Trackable Channels

List every connected sales channel together with its sub-channels. 17TRACK auto-tracking is scoped per (sales channel, sub-channel) pair — fulfillment type (e.g. Amazon FBA vs merchant-fulfilled, or Shopify Web vs POS) is represented as a sub-channel. Channels with no sub-channels are tracked at the channel level and return an empty `sub_channels` array.

📄️List Instance Trackings

Paginated list of shipment_trackings rows scoped to a single 17TRACK integration instance. Powers the 'Trackings' sub-page of the 17TRACK integration UI.

📄️List Instance Webhook Events

Paginated audit log of every 17TRACK webhook received for this integration instance. One row per inbound webhook, persisted by a background job BEFORE processing.

📄️List Instance Activity Log

Paginated activity log entries scoped to a single 17TRACK integration instance. Surfaces both (1) rows where the instance itself is the activity subject (connect / settings update / disconnect) and (2) rows where `properties.integration_instance_id` matches (webhook ingest, backfill, quota threshold).

📄️List Shipment Trackings

Paginated cross-entity listing of shipment tracking rows. Powers the Delivery Exceptions view, the global Trackings table, and per-entity filtered subsets.

📄️Get Shipment Tracking

Single tracking row with the FULL event timeline + integration instance descriptor. Powers the per-row timeline detail view in the Delivery Exceptions view and on entity detail pages.

📄️Refresh Shipment Tracking

On-demand refresh — hits 17TRACK's `/gettrackinfo` synchronously and re-hydrates the local row (events, status, sub_status, estimated_delivery_at, etc.). Returns the same shape as `GET /shipment-trackings/{id}` so the timeline detail view can swap the payload in-place.

📄️Register Shipment Tracking

Manual `Track this shipment` trigger from an entity detail page. Resolves the entity, creates a pending `shipment_trackings` row via the manager, and kicks off a background job so the row gets pushed to 17TRACK promptly.

📄️Backfill Shipment Trackings

Kick off a background job that scans recent rows of the selected entity types and registers any that have a `tracking_number` but no `shipment_trackings` row yet.

📄️Re-track Shipment Tracking

Re-activate tracking for an expired or stopped number via 17TRACK's `/retrack` endpoint. 17TRACK auto-stops tracking ~30 idle days after the last event; this asks it to resume pushing updates.

📄️Change Shipment Tracking Carrier

Correct a mis-detected carrier via 17TRACK's `/changecarrier` endpoint and re-hydrate the row under the new carrier. 17TRACK auto-detects the carrier from the number format when registering and sometimes picks wrong — this fixes it without stopping/re-registering.

📄️Register Parcel Trackings (Multi-Parcel)

Register additional parcel tracking numbers against ONE entity — the multi-parcel path for shipments split across several cartons (each with its own carrier number). The entity's primary `tracking_number` is registered by the save observer; this endpoint covers the remaining boxes so every carton tracks independently.