# Track

> Package tracking API: submit a tracking number, get normalized status and
> events across 1,200+ carriers, receive signed webhooks on updates.
> Signup returns an API key in one call. Free tier: 100 trackings/month.

## Quickstart

- Signup (no password): `POST /v1/signup {"email":"you@example.com"}` → `{"api_key":"trk_live_..."}`
- Auth: `Authorization: Bearer trk_live_...`
- Track: `POST /v1/trackings {"tracking_number":"1Z12345E0205271688"}` — carrier auto-detected, pass `"carrier"` to pin (China: `kuaidi100:shunfeng` etc). Optional `"notify_email"` emails the recipient on status changes. 201 = new (1 quota unit), 200 = already tracked (free).
- Public lookup (no auth): `GET /track` (page), `GET /track/{carrier}/{number}` (shareable). Anyone can look up a number without an account.
- Read: `GET /v1/trackings/{id}` (with events), `GET /v1/trackings?limit=50`
- Stop: `DELETE /v1/trackings/{id}`
- Statuses: pending, info_received, in_transit, out_for_delivery, available_for_pickup, delivery_failure, delivered, exception, expired

## Webhooks

- `POST /v1/webhooks {"url":"https://..."}` → signing secret (shown once; requires verified email)
- Header `X-Track-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, t + "." + body); reject if |now-t| > 300s
- Event types: tracking.updated plus tracking.<status> on status change; at-least-once, unordered; dedupe on payload `id`

## MCP

- Streamable HTTP endpoint at `/mcp`, same Bearer auth
- Tools: track_number, get_tracking, list_trackings, list_carriers

## Reference

- OpenAPI spec: /openapi.yaml
- Human docs: /docs
- Errors: `{"error":{"message","code"}}` with codes bad_request, unauthorized, not_found, invalid_number, quota_exceeded, rate_limited, email_unverified
- Billing unit: trackings created per calendar month. Reads/webhooks free. Plans: free 100/mo, pro $9 1000/mo, business $49 10000/mo.