REST API
Package Tracking API
Track shipments across 3,000+ carriers worldwide via 17Track.
Full event timeline, batch tracking, quota monitoring, and more.
Base URL:
https://tracking.tandu.dev
Authentication
POST
/api/auth/login
Admin sign-in
›
Returns a session token valid for 7 days. Pass the token in the
X-Admin-Token header for protected endpoints.Request Body
| password | string | Admin password |
Response
{ "token": "YWRtaW46MTc4MDg5NzI4..." }
Example
curl -X POST https://tracking.tandu.dev/api/auth/login \
-H "Content-Type: application/json" \
-d '{"password": "Tandu1710@"}'
GET
/api/auth/check
Check token validity
›
Pass
X-Admin-Token header to verify the current token.Example
curl https://tracking.tandu.dev/api/auth/check \
-H "X-Admin-Token: YOUR_TOKEN"
Response
{ "authenticated": true }
GET
/api/admin/config
Get API key status
›
Requires
X-Admin-Token header.Response
{ "hasApiKey": true, "apiKey": "xxxx****" }
POST
/api/admin/config
Update API key or password
›
Requires
X-Admin-Token header. currentPassword always required.Request Body
| currentPassword | string | Current admin password (required) |
| apiKey | string | New 17Track API key |
| newPassword | string | New admin password (min 6 chars) |
Example
curl -X POST https://tracking.tandu.dev/api/admin/config \
-H "Content-Type: application/json" \
-H "X-Admin-Token: YOUR_TOKEN" \
-d '{"currentPassword":"Tandu1710@","apiKey":"YOUR_API_KEY"}'
Tracking
POST
/api/track
Full tracking with event timeline
›
Primary endpoint. Auto-detects carrier from tracking number if
carrier is omitted.Request Body
| trackingNumber | string | Tracking number (required) |
| carrier | string | Carrier: fedex, ups, usps, dhl, amazon, china post, ontrac, lasership, speedee, roadie |
Response Fields
| carrier | string | Detected carrier name |
| status | string | In Transit, Delivered, Alert, etc. |
| estimatedDelivery | string | Estimated delivery date |
| events[] | array | Full chronological event timeline |
Example
curl -X POST https://tracking.tandu.dev/api/track \
-H "Content-Type: application/json" \
-d '{"trackingNumber": "521348264090", "carrier": "fedex"}'
Response
{
"carrier": "FedEx",
"trackingNumber": "521348264090",
"status": "Delivered",
"estimatedDelivery": "6/4/2026",
"origin": "US",
"destination": "Ho Chi Minh City, VN",
"events": [
{ "date": "6/4/2026, 10:48 AM", "location": "US", "status": "Delivered", "description": "Signed for by: NGUYEN" },
{ "date": "6/4/2026, 8:12 AM", "location": "Ho Chi Minh City", "status": "Out for delivery", "description": "Out for delivery" }
]
}
POST
/api/track/status
Latest status only — lightweight
›
Fast status check for dashboards or polling. No full timeline.
Request Body
| trackingNumber | string | Tracking number (required) |
Example
curl -X POST https://tracking.tandu.dev/api/track/status \
-H "Content-Type: application/json" \
-d '{"trackingNumber": "521348264090"}'
Response
{
"trackingNumber": "521348264090",
"carrier": "FedEx",
"status": "Delivered",
"latestEvent": { "date": "6/4/2026, 10:48 AM", "location": "US", "description": "Signed for by: NGUYEN" }
}
POST
/api/track/batch
Track up to 40 packages at once
›
Requires API key. Parallel requests — up to 40 items per call.
Request Body
| items[] | array | Array of objects with trackingNumber and optional carrier |
Example
curl -X POST https://tracking.tandu.dev/api/track/batch \
-H "Content-Type: application/json" \
-d '{"items": [
{"trackingNumber": "1Z81A6E00360713159", "carrier": "ups"},
{"trackingNumber": "9361289724248461734109"}
]}'
Response
{
"results": [
{ "carrier": "UPS", "trackingNumber": "1Z81A6E00360713159", "status": "Delivered", "events": [...] },
{ "carrier": "USPS", "trackingNumber": "9361289724248461734109", "status": "In Transit", "events": [...] }
]
}
POST
/api/track/refresh
Force re-fetch from 17Track
›
Requires API key. Useful to get fresh data after a status change.
Request Body
| trackingNumber | string | Tracking number (required) |
| carrier | string | Carrier code (optional) |
Example
curl -X POST https://tracking.tandu.dev/api/track/refresh \
-H "Content-Type: application/json" \
-d '{"trackingNumber": "521348264090", "carrier": "fedex"}'
Quota
GET
/api/quota
Check 17Track API usage
›
Requires API key configured in admin panel.
Response Fields
| quota_total | int | Total monthly quota |
| quota_used | int | Quota used this month |
| quota_remain | int | Remaining quota |
| today_used | int | Tracks used today |
| max_track_daily | int | Maximum tracks per day |
| free_email_quota | int | Free email notification quota |
Example
curl https://tracking.tandu.dev/api/quota
Response
{
"quota_total": 500,
"quota_used": 12,
"quota_remain": 488,
"today_used": 3,
"max_track_daily": 100,
"free_email_quota": 100,
"free_email_quotaused": 0
}
History
GET
/api/history
List all tracked packages
›
Example
curl https://tracking.tandu.dev/api/history
Response
{
"history": [
{ "trackingNumber": "521348264090", "carrier": "FedEx", "lastChecked": "2026-06-08T03:48:00.000Z" }
]
}
DELETE
/api/history
Delete history entries
›
Query Parameters
| trackingNumber | string | Remove a specific entry |
| clearAll | bool | Set true to clear all history |
Example
# Remove single entry
curl -X DELETE "https://tracking.tandu.dev/api/history?trackingNumber=521348264090"
# Clear all
curl -X DELETE "https://tracking.tandu.dev/api/history?clearAll=true"