# Ali Express Tracking (`sovanza.inc/ali-express-tracking`) Actor AliExpress Tracking Checker tracks shipments using Cainiao, AliExpress logistics, and 17TRACK sources. It returns normalized status, carrier details, delivery flags, event history, locations, and structured tracking data for e-commerce automation. - **URL**: https://apify.com/sovanza.inc/ali-express-tracking.md - **Developed by:** [Sovanza](https://apify.com/sovanza.inc) (community) - **Categories:** E-commerce, Automation, Integrations - **Stats:** 5 total users, 4 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $6.00 / 1,000 tracking results This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ### AliExpress Tracking Checker – Multi-Source Shipment Tracking & Cainiao Scraper Track AliExpress shipments using a multi-source engine: **Cainiao Global**, **AliExpress logistics**, and **17TRACK** public tracking pages. This actor walks a configurable priority list of providers and returns normalized, structured tracking data from the **first source that succeeds**. ### Overview AliExpress Tracking Checker uses **Playwright (Chromium)** to open public tracking pages, intercept JSON responses, and parse DOM content when needed. It normalizes carrier, status, locations, and event history into one consistent schema. **Output is compact:** empty or missing fields are omitted so each row contains only what the tracking sources exposed for that shipment. ### Key benefits - Check **multiple tracking numbers** in one run via `trackingInputs` - **Multi-source fallback** with configurable `sourcePriority` - **Normalized status** (`in_transit`, `delivered`, `exception`, etc.) - Optional **full event timeline** per shipment - Export clean datasets in **JSON, CSV, or Excel** via Apify - Proxy and cookie support for anti-bot tracking sites ### Core features - Cainiao, AliExpress, and 17TRACK web adapters (priority-based) - Bulk tracking input with optional `orderId`, `carrierHint`, `sourceHint`, `countryHint` - Derived status flags: `delivered`, `inTransit`, `exception` - Event history with `maxEventsPerTracking` cap - Optional raw source payload for debugging - Parallel lookups via `maxConcurrency` - Output to dataset, key-value store, or both (`outputMode`) ### How to Use AliExpress Tracking Checker on Apify #### Using the Actor 1. **Open the Actor** on the Apify platform and go to the **Input** tab. 2. **Add tracking numbers** in `trackingInputs` (with optional order IDs and hints). 3. **Enable residential proxy** via `proxyConfiguration` for best reliability. 4. **Start** the run. The actor tries each source in order and pushes **compact items** to the default dataset. 5. **Open the Dataset** tab to browse, download JSON/CSV/Excel, or pull data via the Apify API. 6. **Schedule or integrate** (optional): use schedules, webhooks, Zapier/Make, or your own code against the Apify API. #### Input Configuration Full schema: `INPUT_SCHEMA.json`. Example: ```json { "trackingInputs": [ { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721" }, { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK" } ], "sourcePriority": ["cainiao_web", "aliexpress_web", "seventeen_track_web"], "includeEventHistory": true, "includeDerivedStatus": true, "maxConcurrency": 3, "outputMode": "dataset", "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" } } ```` - **`trackingInputs`** (required): Array of tracking request objects. Each may include `trackingNumber`, `orderId`, `carrierHint`, `sourceHint`, and `countryHint`. Plain strings are accepted as tracking numbers. - **`sourcePriority`** (optional): Ordered list of source adapters. Default: `["cainiao_web", "aliexpress_web", "seventeen_track_web"]`. - **`includeEventHistory`** (optional): Include the full tracking event timeline (default `true`). - **`includeRawSourcePayload`** (optional): Include sanitized raw source HTML for debugging (default `false`). - **`includeDerivedStatus`** (optional): Compute normalized status and delivery flags (default `true`). - **`maxEventsPerTracking`** (optional): Max events per shipment (default `50`, max `500`). - **`outputMode`** (optional): `dataset`, `kv_store`, or `both` (default `dataset`). - **`outputKvStoreKey`** (optional): KV store key when using `kv_store` or `both` (default `TRACKING_OUTPUT`). - **`requestTimeoutSecs`** (optional): Page navigation timeout (default `45`). - **`maxConcurrency`** (optional): Parallel tracking lookups (default `5`, max `20`). - **`retriesPerSource`** (optional): Retries per source before moving on (default `2`). - **`challengeWaitSecs`** (optional): Max wait for Cloudflare/CAPTCHA resolution (default `12`). - **`blockAssets`** (optional): Block non-essential assets for speed (default `true`). - **`debugMode`** / **`saveHtmlSnapshot`** / **`saveScreenshot`** (optional): Debug artifacts for failed pages. - **`proxyConfiguration`** (optional): Apify proxy; **residential** is recommended. - **`cookiesText`** / **`cookiesJson`** (optional): Session cookies. **Secret inputs** — encrypted at rest, not copied to dataset rows. - **`seventeenTrackApiKey`** (optional): Reserved for future 17TRACK API adapter. **Secret input**. ##### Authentication & sensitive input Fields that can hold session credentials use Apify **secret input** (`isSecret: true`): - **`cookiesText`** — Netscape/tab-separated cookie format - **`cookiesJson`** — Playwright cookie array JSON - **`seventeenTrackApiKey`** — future API key storage Secret values are encrypted in storage and are **not** written into dataset rows or logs. ##### Run locally `INPUT.json` is gitignored. Copy `INPUT.example.json` to `INPUT.json`, then: ```bash cd aliexpress-tracking-checker pip install -r requirements.txt playwright install chromium cp INPUT.example.json INPUT.json python main.py ``` ### Output Results are stored in the Actor’s **default dataset** when `outputMode` is `dataset` or `both`. Each item is a **compact** JSON object: fields that are empty or unknown are **not** included. Typical fields (when data is available): - **Identity:** `trackingNumber`, `orderId` - **Carrier & source:** `carrier`, `sourceUsed`, `sourceUrl`, `sourceStatusText` - **Status:** `normalizedStatus`, `delivered`, `exception`, `inTransit` - **Timing:** `lastUpdate`, `estimatedDelivery`, `firstSeenEvent`, `latestEvent` - **Location:** `lastUpdateLocation`, `latestLocation`, `originCountry`, `destinationCountry` - **Events:** `trackingEvents`, `eventCount` - **Quality:** `statusConfidence`, `sourceAttempts`, `warnings` - **Debug:** `rawSourcePayload` (when enabled) - **Errors:** `error` on failure rows - **Meta:** `timestamp` Example item (illustrative — real items only include keys that have values): ```json { "trackingNumber": "LB123456789SG", "orderId": "8182736455463721", "carrier": "Cainiao", "sourceUsed": "cainiao_web", "sourceUrl": "https://global.cainiao.com/detail.htm?mailNoList=LB123456789SG", "sourceStatusText": "Parcel is in transit", "normalizedStatus": "in_transit", "delivered": false, "inTransit": true, "lastUpdate": "2026-03-31T10:22:00Z", "lastUpdateLocation": "Lahore, Pakistan", "estimatedDelivery": "2026-04-07", "eventCount": 6, "statusConfidence": "high", "sourceAttempts": [ { "source": "cainiao_web", "success": true, "reason": "tracking data found" } ], "trackingEvents": [ { "timestamp": "2026-03-21T03:10:00Z", "status": "Shipment accepted by carrier", "location": "Shenzhen, China", "details": "Accepted at sorting center", "sourceEventIndex": 0 } ], "timestamp": "2026-03-31T12:00:00Z" } ``` When `outputMode` is `kv_store` or `both`, a JSON bundle with `records` and `summary` is also written to the key-value store under `outputKvStoreKey` (default `TRACKING_OUTPUT`). #### Normalized statuses | Status | Meaning | |--------|---------| | `pending` | Label created / information received | | `accepted` | Shipment accepted by carrier | | `in_transit` | Package is moving between facilities | | `arrived_at_destination_country` | Customs clearance or arrival at destination | | `out_for_delivery` | Out for final delivery | | `delivered` | Successfully delivered | | `failed_attempt` | Delivery attempt failed | | `exception` | Held, lost, or other exception | | `returned` | Returned to sender | | `expired` | Tracking expired | | `unknown` | Could not determine status | #### Failure output When no source returns valid data (compact — omitted null keys): ```json { "trackingNumber": "LP00123456789012", "normalizedStatus": "unknown", "error": "No source returned valid tracking data", "sourceAttempts": [ { "source": "cainiao_web", "success": false, "reason": "challenge page persisted" }, { "source": "aliexpress_web", "success": false, "reason": "no tracking result" } ], "timestamp": "2026-03-31T12:00:00Z" } ``` ### Use Cases - **Dropshipping order tracking** — monitor AliExpress orders and keep customers updated - **Tracking dashboards** — feed normalized status into internal monitoring tools - **E-commerce automation** — connect tracking data to CRMs and support systems - **Delivery alerts** — detect status changes by diffing scheduled runs - **Logistics analytics** — analyze shipping times, delays, and carrier performance ### Integrations & API - Run and fetch results through the **Apify API** - Use **Python**, **Node.js**, or HTTP clients against run and dataset endpoints - Connect **Zapier**, **Make**, **Google Sheets**, and other Apify integrations - **Webhooks** and **schedules** for recurring tracking checks ### FAQ #### How does AliExpress Tracking Checker work? It tries each source in `sourcePriority` using Playwright, extracts tracking events and status from the first successful source, normalizes the data, and pushes compact rows to the dataset. #### Why use multiple tracking sources? AliExpress shipments often surface updates on Cainiao or 17TRACK before or more completely than on AliExpress pages alone. #### Can I track multiple orders in one run? Yes. Add multiple entries to `trackingInputs`. #### Why am I getting no tracking results? Invalid numbers, shipments not yet registered, or blocked access are common causes. Use **residential proxy** and **cookies** when sources challenge automated traffic. #### What formats can I export? **JSON**, **CSV**, and **Excel** from the Apify dataset UI, plus full access via the **Apify API**. ### SEO Keywords aliexpress tracking checker\ cainiao tracking scraper\ aliexpress shipment tracker\ 17track scraper\ shipment tracking api\ package tracking automation\ apify tracking actor ### Actor permissions This Actor is intended to work with **limited permissions**: it reads your input and writes to its **default dataset** (and uses Apify proxy/KV as configured). It does not require broad access to unrelated account data. **To set limited permissions in Apify Console:** 1. Open your Actor on the Apify platform. 2. Go to **Source** or **Settings**. 3. Open **Review permissions** / **Permissions**. 4. Choose **Limited permissions** and save. ### Limitations - Not all shipments expose the same fields across tracking sources. - Tracking sites may block automated access or require CAPTCHA solving. - Session cookies may be needed for some source flows. - 17TRACK may show limited data for unregistered tracking numbers. - The actor does not invent tracking data — it only returns what sources expose. - Heavy use may require higher Apify memory, concurrency, and proxy budgets. ### License This project is licensed under the MIT License - see the LICENSE file for details. ### Get Started Add your tracking numbers, turn on a residential proxy, and start your first run on Apify. # Actor input Schema ## `trackingInputs` (type: `array`): List of tracking requests. Each item may include trackingNumber, orderId, carrierHint, sourceHint, and countryHint. Plain strings are accepted as tracking numbers. ## `sourcePriority` (type: `array`): Ordered list of tracking sources to try. The actor walks this list top-to-bottom and stops at the first source that returns valid data. ## `includeEventHistory` (type: `boolean`): Include the full timeline of tracking events in the output. ## `includeRawSourcePayload` (type: `boolean`): Include a sanitized raw source payload or extracted HTML text for debugging purposes. ## `includeDerivedStatus` (type: `boolean`): Compute a normalized high-level status from source-specific status strings. ## `maxEventsPerTracking` (type: `integer`): Maximum number of tracking events to return per shipment. ## `outputMode` (type: `string`): Where to write tracking results. dataset: default Apify dataset. kv\_store: key-value store JSON bundle. both: write to both. ## `outputKvStoreKey` (type: `string`): Key name used when writing results to the key-value store. ## `requestTimeoutSecs` (type: `integer`): Maximum time in seconds to wait for a single page navigation to complete. ## `maxConcurrency` (type: `integer`): Maximum number of tracking lookups to run in parallel. ## `retriesPerSource` (type: `integer`): Number of retry attempts per source adapter before moving to the next source. ## `challengeWaitSecs` (type: `integer`): Maximum time in seconds to wait for a Cloudflare or CAPTCHA challenge page to resolve. ## `blockAssets` (type: `boolean`): Block images, fonts, and other non-essential assets to speed up page loads. ## `debugMode` (type: `boolean`): Enable debug mode to save HTML snapshots and screenshots for failed or blocked pages. ## `saveHtmlSnapshot` (type: `boolean`): Save an HTML snapshot to the key-value store when extraction fails. ## `saveScreenshot` (type: `boolean`): Save a page screenshot to the key-value store when extraction fails. ## `useCarrierAutoDetect` (type: `boolean`): Reserved for future use. Carrier auto-detection from tracking number format is not yet implemented. ## `proxyConfiguration` (type: `object`): Apify proxy settings. Residential proxy is recommended for Cainiao, AliExpress, and 17TRACK pages. ## `cookiesText` (type: `string`): Optional browser cookies in Netscape/tab-separated format. Each line: namevaluedomainpath. Stored as a secret input and never written to the dataset. ## `cookiesJson` (type: `string`): Optional Playwright cookie array JSON. Alternative to cookiesText. Stored as a secret input and never written to the dataset. ## `seventeenTrackApiKey` (type: `string`): Optional 17TRACK API key for future API-based tracking. Currently unused; reserved for API adapter expansion. ## Actor input object example ```json { "trackingInputs": [ { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721" }, { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK" } ], "sourcePriority": [ "cainiao_web", "aliexpress_web", "seventeen_track_web" ], "includeEventHistory": true, "includeRawSourcePayload": false, "includeDerivedStatus": true, "maxEventsPerTracking": 50, "outputMode": "dataset", "outputKvStoreKey": "TRACKING_OUTPUT", "requestTimeoutSecs": 45, "maxConcurrency": 3, "retriesPerSource": 2, "challengeWaitSecs": 12, "blockAssets": true, "debugMode": false, "saveHtmlSnapshot": false, "saveScreenshot": false, "useCarrierAutoDetect": true, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } } ``` # Actor output Schema ## `trackings` (type: `string`): Normalized shipment tracking records in the default dataset. ## `kvOutput` (type: `string`): JSON bundle with records and run summary when outputMode is kv\_store or both. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "trackingInputs": [ { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721" }, { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK" } ], "sourcePriority": [ "cainiao_web", "aliexpress_web", "seventeen_track_web" ], "includeEventHistory": true, "includeRawSourcePayload": false, "includeDerivedStatus": true, "maxEventsPerTracking": 50, "outputMode": "dataset", "outputKvStoreKey": "TRACKING_OUTPUT", "requestTimeoutSecs": 45, "maxConcurrency": 3, "retriesPerSource": 2, "challengeWaitSecs": 12, "blockAssets": true, "debugMode": false, "saveHtmlSnapshot": false, "saveScreenshot": false, "useCarrierAutoDetect": true, "cookiesText": "", "cookiesJson": "", "seventeenTrackApiKey": "" }; // Run the Actor and wait for it to finish const run = await client.actor("sovanza.inc/ali-express-tracking").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "trackingInputs": [ { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721", }, { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK", }, ], "sourcePriority": [ "cainiao_web", "aliexpress_web", "seventeen_track_web", ], "includeEventHistory": True, "includeRawSourcePayload": False, "includeDerivedStatus": True, "maxEventsPerTracking": 50, "outputMode": "dataset", "outputKvStoreKey": "TRACKING_OUTPUT", "requestTimeoutSecs": 45, "maxConcurrency": 3, "retriesPerSource": 2, "challengeWaitSecs": 12, "blockAssets": True, "debugMode": False, "saveHtmlSnapshot": False, "saveScreenshot": False, "useCarrierAutoDetect": True, "cookiesText": "", "cookiesJson": "", "seventeenTrackApiKey": "", } # Run the Actor and wait for it to finish run = client.actor("sovanza.inc/ali-express-tracking").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "trackingInputs": [ { "trackingNumber": "LP00123456789012", "orderId": "8182736455463721" }, { "trackingNumber": "CNABC0012345678", "carrierHint": "Cainiao", "countryHint": "PK" } ], "sourcePriority": [ "cainiao_web", "aliexpress_web", "seventeen_track_web" ], "includeEventHistory": true, "includeRawSourcePayload": false, "includeDerivedStatus": true, "maxEventsPerTracking": 50, "outputMode": "dataset", "outputKvStoreKey": "TRACKING_OUTPUT", "requestTimeoutSecs": 45, "maxConcurrency": 3, "retriesPerSource": 2, "challengeWaitSecs": 12, "blockAssets": true, "debugMode": false, "saveHtmlSnapshot": false, "saveScreenshot": false, "useCarrierAutoDetect": true, "cookiesText": "", "cookiesJson": "", "seventeenTrackApiKey": "" }' | apify call sovanza.inc/ali-express-tracking --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=sovanza.inc/ali-express-tracking", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Ali Express Tracking", "description": "AliExpress Tracking Checker tracks shipments using Cainiao, AliExpress logistics, and 17TRACK sources. It returns normalized status, carrier details, delivery flags, event history, locations, and structured tracking data for e-commerce automation.", "version": "0.0", "x-build-id": "UhurKKBHMwrVyfyv2" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/sovanza.inc~ali-express-tracking/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-sovanza.inc-ali-express-tracking", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/sovanza.inc~ali-express-tracking/runs": { "post": { "operationId": "runs-sync-sovanza.inc-ali-express-tracking", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/sovanza.inc~ali-express-tracking/run-sync": { "post": { "operationId": "run-sync-sovanza.inc-ali-express-tracking", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "trackingInputs" ], "properties": { "trackingInputs": { "title": "Tracking inputs", "type": "array", "description": "List of tracking requests. Each item may include trackingNumber, orderId, carrierHint, sourceHint, and countryHint. Plain strings are accepted as tracking numbers.", "items": { "type": "object", "properties": { "trackingNumber": { "title": "Tracking number", "type": "string", "description": "Shipment tracking number.", "editor": "textfield" }, "orderId": { "title": "Order ID", "type": "string", "description": "AliExpress order ID.", "editor": "textfield" }, "carrierHint": { "title": "Carrier hint", "type": "string", "description": "Optional carrier name hint (e.g. Cainiao, DHL).", "editor": "textfield" }, "sourceHint": { "title": "Source hint", "type": "string", "description": "Preferred source adapter to try first (e.g. cainiao_web).", "editor": "textfield" }, "countryHint": { "title": "Country hint", "type": "string", "description": "Destination country code hint (e.g. US, PK).", "editor": "textfield" } } } }, "sourcePriority": { "title": "Source priority", "type": "array", "description": "Ordered list of tracking sources to try. The actor walks this list top-to-bottom and stops at the first source that returns valid data.", "default": [ "cainiao_web", "aliexpress_web", "seventeen_track_web" ] }, "includeEventHistory": { "title": "Include event history", "type": "boolean", "description": "Include the full timeline of tracking events in the output.", "default": true }, "includeRawSourcePayload": { "title": "Include raw source payload", "type": "boolean", "description": "Include a sanitized raw source payload or extracted HTML text for debugging purposes.", "default": false }, "includeDerivedStatus": { "title": "Include derived status", "type": "boolean", "description": "Compute a normalized high-level status from source-specific status strings.", "default": true }, "maxEventsPerTracking": { "title": "Max events per tracking", "minimum": 1, "maximum": 500, "type": "integer", "description": "Maximum number of tracking events to return per shipment.", "default": 50 }, "outputMode": { "title": "Output mode", "enum": [ "dataset", "kv_store", "both" ], "type": "string", "description": "Where to write tracking results. dataset: default Apify dataset. kv_store: key-value store JSON bundle. both: write to both.", "default": "dataset" }, "outputKvStoreKey": { "title": "Output KV store key", "type": "string", "description": "Key name used when writing results to the key-value store.", "default": "TRACKING_OUTPUT" }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 10, "maximum": 120, "type": "integer", "description": "Maximum time in seconds to wait for a single page navigation to complete.", "default": 45 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Maximum number of tracking lookups to run in parallel.", "default": 5 }, "retriesPerSource": { "title": "Retries per source", "minimum": 1, "maximum": 5, "type": "integer", "description": "Number of retry attempts per source adapter before moving to the next source.", "default": 2 }, "challengeWaitSecs": { "title": "Challenge wait (seconds)", "minimum": 5, "maximum": 60, "type": "integer", "description": "Maximum time in seconds to wait for a Cloudflare or CAPTCHA challenge page to resolve.", "default": 12 }, "blockAssets": { "title": "Block assets", "type": "boolean", "description": "Block images, fonts, and other non-essential assets to speed up page loads.", "default": true }, "debugMode": { "title": "Debug mode", "type": "boolean", "description": "Enable debug mode to save HTML snapshots and screenshots for failed or blocked pages.", "default": false }, "saveHtmlSnapshot": { "title": "Save HTML snapshot", "type": "boolean", "description": "Save an HTML snapshot to the key-value store when extraction fails.", "default": false }, "saveScreenshot": { "title": "Save screenshot", "type": "boolean", "description": "Save a page screenshot to the key-value store when extraction fails.", "default": false }, "useCarrierAutoDetect": { "title": "Auto-detect carrier", "type": "boolean", "description": "Reserved for future use. Carrier auto-detection from tracking number format is not yet implemented.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify proxy settings. Residential proxy is recommended for Cainiao, AliExpress, and 17TRACK pages.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ], "apifyProxyCountry": "US" } }, "cookiesText": { "title": "Cookies (text)", "type": "string", "description": "Optional browser cookies in Netscape/tab-separated format. Each line: namevaluedomainpath. Stored as a secret input and never written to the dataset." }, "cookiesJson": { "title": "Cookies JSON (optional)", "type": "string", "description": "Optional Playwright cookie array JSON. Alternative to cookiesText. Stored as a secret input and never written to the dataset." }, "seventeenTrackApiKey": { "title": "17TRACK API key (optional)", "type": "string", "description": "Optional 17TRACK API key for future API-based tracking. Currently unused; reserved for API adapter expansion." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```