home / skills / openclaw / skills / track17

track17 skill

safe

This skill tracks parcels via the 17TRACK API, stores updates in a local SQLite DB, and summarizes changes for quick status.

npx playbooks add skill openclaw/skills --skill track17

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.4 KB

---
name: track17
description: Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion)
user-invocable: true
metadata: {"clawdbot":{"emoji":"📦","requires":{"anyBins":["python3","python"],"env":["TRACK17_TOKEN"]},"primaryEnv":"TRACK17_TOKEN"}}
---

# track17 (17TRACK parcel tracking)

This skill lets Clawdbot keep a local list of your parcels, track their state via the **17TRACK Tracking API v2.2**, and summarise changes.

It stores everything in a small **SQLite DB** under your **workspace** (by default: `<workspace>/packages/track17/track17.sqlite3`).

`<workspace>` is auto-detected as the parent directory of the nearest `skills/` directory that contains this skill.
For example, if you install it at `/clawd/skills/track17/`, data will be stored at `/clawd/packages/track17/`.

## Requirements

- `TRACK17_TOKEN` must be set (17TRACK API token; used as the `17token` header).
- Python (`python3` preferred).

Optional:
- `TRACK17_WEBHOOK_SECRET` if you want to verify webhook signatures.
- `TRACK17_DATA_DIR` to override where the DB/inbox live.
- `TRACK17_WORKSPACE_DIR` to override what this tool considers the workspace directory.

## Quick start

1) Initialise storage (safe to run multiple times):

```bash
python3 {baseDir}/scripts/track17.py init
```

2) Add a package (registers it with 17TRACK and stores it locally):

```bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones"
```

If carrier auto-detection fails, specify a carrier code:

```bash
python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..."
```

3) List tracked packages:

```bash
python3 {baseDir}/scripts/track17.py list
```

4) Poll for updates (recommended if you don't want webhooks):

```bash
python3 {baseDir}/scripts/track17.py sync
```

5) Show details for one package:

```bash
python3 {baseDir}/scripts/track17.py status 1
# or
python3 {baseDir}/scripts/track17.py status "RR123456789CN"
```

## Webhooks (optional)

17TRACK can push updates to a webhook URL. This skill supports webhook ingestion in two ways:

### A) Run the included webhook server

```bash
python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789
```

Then point 17TRACK's webhook URL at that server (ideally via a reverse proxy or Tailscale Funnel).

### B) Ingest webhook payloads from stdin/file

```bash
cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook
# or
python3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json
```

If you saved webhook deliveries to the inbox directory, process them:

```bash
python3 {baseDir}/scripts/track17.py process-inbox
```

## Common actions

- Stop tracking:

```bash
python3 {baseDir}/scripts/track17.py stop 1
```

- Retrack a stopped parcel:

```bash
python3 {baseDir}/scripts/track17.py retrack 1
```

- Delete a parcel from local DB (does not delete at 17TRACK unless you also call `delete-remote`):

```bash
python3 {baseDir}/scripts/track17.py remove 1
```

- Show API quota:

```bash
python3 {baseDir}/scripts/track17.py quota
```

## Operating guidance for the agent

- Prefer **sync** (polling) for simplicity unless the user explicitly wants webhooks.
- After adding a package, run `status` once to confirm a valid carrier/status was returned.
- When summarising, prioritise:
  - delivered/out for delivery
  - exception/failed delivery
  - customs holds
  - carrier handoffs
- Never echo `TRACK17_TOKEN` or `TRACK17_WEBHOOK_SECRET`.

Overview

This skill tracks parcels using the 17TRACK Tracking API v2.2 and keeps a local SQLite database of registered shipments. It stores tracking state and history under your workspace so the agent can summarise changes, detect delivery events, and surface exceptions. The tool supports polling (sync) and optional webhook ingestion for near-real-time updates.

How this skill works

The skill registers parcel numbers with 17TRACK, stores metadata and status updates in a small SQLite DB located in your workspace, and fetches updates via the API. You can poll the API with the sync command or accept webhook deliveries using the built-in webhook server or an inbox/ingest workflow. Summaries prioritise delivery, out-for-delivery, exceptions, customs holds, and carrier handoffs.

When to use it

You want a local, persistent view of parcel status for multiple shipments.
You need periodic polling rather than a full webhook infrastructure.
You want to ingest webhook payloads saved to files or delivered to a local server.
You need concise summaries highlighting deliveries, exceptions, or customs holds.
You require a small, embedable tracker that stores data inside a workspace.

Best practices

Set TRACK17_TOKEN in the environment; never share or echo the token.
Prefer sync (polling) for simplicity unless you explicitly want webhooks.
After adding a package, run status once to confirm carrier detection and initial state.
Use the inbox + ingest pattern if you save webhook payloads for offline processing.
Store workspace under a backed-up directory to keep the SQLite DB safe.

Example use cases

Maintain a running list of purchases and receive summed delivery/exception alerts.
Run a cron job that calls sync to update all tracked parcels and notify users of changes.
Expose a local webhook endpoint behind a reverse proxy or Tailscale Funnel to receive push updates.
Save webhook deliveries to disk and process them later with ingest-webhook or process-inbox.
Audit historical tracking events stored in the SQLite DB for support or reporting.

FAQ

What environment variables are required?

TRACK17_TOKEN is required. TRACK17_WEBHOOK_SECRET, TRACK17_DATA_DIR, and TRACK17_WORKSPACE_DIR are optional.

Should I use polling or webhooks?

Use polling (sync) for simplicity and reliability. Use webhooks for faster updates if you can expose a stable endpoint or use the inbox/ingest workflow.