TrackMe Developer API Documentation (v1 Reference)

🔑 Authentication & Security

All requests to TrackMe's protected API endpoints require your Secret Merchant API Key. You can obtain your key from your Merchant Dashboard > Developer API tab.

Authenticate by passing your secret key in the x-api-key HTTP header or as a Bearer token:

HTTP Header Authentication

x-api-key: YOUR_SECRET_API_KEY_HERE
# Or alternatively:
Authorization: Bearer YOUR_SECRET_API_KEY_HERE

🔒

CRITICAL SECURITY RULE: Never place or commit your x-api-key in client-side frontend code (such as plain browser JavaScript, React/Vue SPAs, or public HTML). Always call TrackMe server-to-server from your backend (PHP, Node.js, Python, Ruby, Java). This guarantees your API key is 100% hidden from customers and browser DevTools Network tabs.

🛡️ Rate Limits & Infrastructure Protection

TrackMe implements multi-tiered rate limiting to protect system concurrency and carrier network pipeline stability:

Endpoint Scope	Rate Limit	Target Scope
/api/v1/shipments/*	120 requests / minute	Per API Key
/api/v1/track (Carrier Telemetry)	60 requests / minute	Per API Key
/api/v1/notifications/send	30 dispatches / minute	Per API Key (Protects SMS balance & WhatsApp health)

If you exceed the rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header.

POST Create / Register Shipment

Register a parcel when an order is placed or packed in your ecommerce store. Automatically detects the courier company, initializes tracking, computes an AI estimated delivery date (ETA), and optionally dispatches an instant custom notification.

POST https://track.socialzync.com.au/api/v1/shipments

Request Body Parameters (JSON)

Field	Type	Description
trackingNumber REQUIRED	string	Waybill / Tracking number issued by courier (e.g. `EC123456789`, `D10795332`, `88776655`).
company OPTIONAL	string	Courier service (`"domex"`, `"prontolanka"`, `"koombiyo"`, `"citypack"`, `"fardardomestic"`, `"sandbox"`). If omitted or `"auto"`, TrackMe auto-detects based on the waybill format.
customerPhone RECOMMENDED	string	Customer mobile (e.g. `0771234567`). Mandatory for Koombiyo tracking. Used for SMS/WhatsApp alerts.
orderNumber OPTIONAL	string	Your store's order ID (e.g. `#1042`, `ORD-9988`). Enables tracking by order number.
customerName OPTIONAL	string	Recipient's full name (e.g. `"Kasun Perera"`).
shippingCity OPTIONAL	string	Delivery destination city (e.g. `"Kandy"`, `"Colombo 03"`). Used for ETA calculation.
orderTotal OPTIONAL	number	Cash on Delivery (COD) or order total amount in LKR.
sendNotification OPTIONAL	boolean	If `true`, immediately sends a dispatch alert to the customer. Default: `false`.
customMessage OPTIONAL	string	Custom notification text. Supports placeholders: `{customerName}`, `{orderNumber}`, `{trackingUrl}`, `{company}`.

Request Sample (cURL)

curl -X POST "https://track.socialzync.com.au/api/v1/shipments" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "trackingNumber": "EC998877665",
    "company": "auto",
    "customerName": "Kasun Perera",
    "customerPhone": "0771234567",
    "orderNumber": "#1042",
    "shippingCity": "Kandy",
    "orderTotal": 4500,
    "sendNotification": true,
    "customMessage": "Hi {customerName}! Your order {orderNumber} has been dispatched with {company}. Track doorstep delivery: {trackingUrl}"
  }'

Response Sample (201 Created)

{
  "success": true,
  "message": "Shipment created and synchronized with live courier status.",
  "data": {
    "id": "trk_99812401-ae32",
    "trackingNumber": "EC998877665",
    "company": "domex",
    "status": "In Transit - Out for Delivery",
    "standardizedStatus": "IN_TRANSIT",
    "isDelivered": false,
    "estimatedDeliveryDate": "2026-10-21T18:00:00.000Z",
    "order": {
      "orderNumber": "#1042",
      "customerName": "Kasun Perera",
      "customerPhone": "94771234567",
      "shippingCity": "Kandy",
      "orderTotal": 4500,
      "currency": "LKR"
    },
    "trackingUrl": "https://track.socialzync.com.au/track/YOUR_MERCHANT_ID/EC998877665",
    "whatsappShareUrl": "https://wa.me/94771234567?text=...",
    "events": [
      {
        "timestamp": "10:30 AM",
        "location": "Central Sorting Hub Peliyagoda",
        "description": "Parcel arrived at provincial hub and sorted for Kandy dispatch."
      }
    ],
    "notificationDispatched": {
      "channel": "WHATSAPP",
      "success": true
    }
  }
}

POST Send Custom Alert (SMS / WhatsApp / Email)

Dispatch a completely customized message to any Sri Lankan recipient. Developers can customize the exact text, include dynamic variables, and select channel routing ("AUTO", "WHATSAPP", "SMS", or "EMAIL").

POST https://track.socialzync.com.au/api/v1/notifications/send

Request Body Parameters

Field	Type	Description
recipient REQUIRED	string	Customer 10-digit mobile phone (e.g. `0771234567`) or valid email address.
message REQUIRED	string	Your custom message content. You can write any text or template variables like `{customerName}`.
channel OPTIONAL	string	`"AUTO"` (Tries WhatsApp first, fallback to SMS), `"WHATSAPP"`, `"SMS"`, or `"EMAIL"`. Default: `"AUTO"`.
subject OPTIONAL	string	Subject line (only applicable when channel is `"EMAIL"`).
variables OPTIONAL	object	Key-value map to replace placeholders (e.g. `{"customerName": "Kamal", "otp": "4921"}`).

Request Sample: Custom Delivery WhatsApp Alert

curl -X POST "https://track.socialzync.com.au/api/v1/notifications/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "recipient": "0771234567",
    "channel": "AUTO",
    "message": "👋 Hello {customerName}!\n\nYour parcel ({trackingNumber}) is currently Out for Delivery with the rider today.\nPlease prepare LKR {codAmount} in cash for the rider.\n\nLive tracking: {trackingUrl}",
    "variables": {
      "customerName": "Nadeesha",
      "trackingNumber": "EC998877665",
      "codAmount": "3,400",
      "trackingUrl": "https://track.socialzync.com.au/track/YOUR_MERCHANT_ID/EC998877665"
    }
  }'

Response Sample (200 OK)

{
  "success": true,
  "channel": "WHATSAPP",
  "recipient": "94771234567",
  "message": "Custom WhatsApp message delivered successfully.",
  "data": {
    "key": { "remoteJid": "[email protected]", "id": "3EB0912A" }
  }
}

POST Universal Real-Time Tracking Telemetry

Perform instant, on-demand real-time tracking across any supported courier in Sri Lanka without having to register a shipment ahead of time. TrackMe automatically detects the carrier gateway, connects through our proprietary logistics protocol, and delivers the live status, normalized milestones, and branded customer tracking page URL.

POST https://track.socialzync.com.au/api/v1/track

Request Body Parameters (JSON)

Field	Type	Description
trackingNumber REQUIRED	string	Waybill or tracking identifier (e.g. `EC123456789`, `88776655`, `CC06310743`).
company OPTIONAL	string	Courier service identifier (`"domex"`, `"prontolanka"`, `"koombiyo"`, `"citypack"`, `"fardardomestic"`, `"sandbox"`). Omit or set to `"auto"` to let TrackMe auto-detect.
customerPhone OPTIONAL	string	Customer phone number (e.g. `0771234567`). Mandatory for Koombiyo tracking.

Request Sample (cURL)

curl -X POST "https://track.socialzync.com.au/api/v1/track" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_SECRET_API_KEY" \
  -d '{
    "trackingNumber": "EC998877665",
    "company": "auto",
    "customerPhone": "0771234567"
  }'

Response Sample (200 OK)

{
  "success": true,
  "data": {
    "trackingNumber": "EC998877665",
    "company": "domex",
    "status": "In Transit - Out for Delivery",
    "standardizedStatus": "IN_TRANSIT",
    "isDelivered": false,
    "trackingUrl": "https://track.socialzync.com.au/track/YOUR_MERCHANT_ID/EC998877665",
    "events": [
      {
        "timestamp": "10:30 AM",
        "location": "Peliyagoda Hub",
        "description": "Out for delivery with courier rider"
      }
    ]
  }
}

POST Auto-Detect Courier & Validate Waybill

Submit any raw tracking number to detect the courier company, verify format validity, and check if a customer phone number is required.

POST https://track.socialzync.com.au/api/v1/couriers/detect

Request Sample

curl -X POST "https://track.socialzync.com.au/api/v1/couriers/detect" \
  -H "Content-Type: application/json" \
  -d '{ "trackingNumber": "88776655" }'

Response Sample

{
  "success": true,
  "data": {
    "trackingNumber": "88776655",
    "detectedCompany": "koombiyo",
    "displayName": "Koombiyo Delivery",
    "isValidFormat": true,
    "requiresCustomerPhone": true,
    "courierMetadata": {
      "name": "Koombiyo Delivery",
      "format": "8 numeric digits",
      "requiresPhone": true
    }
  }
}

⚡ Webhook Event Stream & HMAC Verification

TrackMe delivers real-time HTTP POST callbacks whenever a shipment status updates. Every webhook payload is signed with your Secret API Key using HMAC-SHA256.

The signature is delivered in the X-TrackMe-Signature header. Verify it on your server to guarantee the payload originated from TrackMe:

HMAC-SHA256 Verification Sample (Node.js)

const crypto = require('crypto');

app.post('/api/webhooks/trackme', (req, res) => {
    const signature = req.headers['x-trackme-signature'];
    const expected = crypto
        .createHmac('sha256', process.env.TRACKME_API_KEY)
        .update(JSON.stringify(req.body))
        .digest('hex');

    if (signature !== expected) {
        return res.status(401).send('Invalid signature');
    }

    const { event, data } = req.body;
    console.log(`Package ${data.trackingNumber} is now ${data.standardizedStatus}`);
    res.status(200).send('Webhook processed');
});

🛒 Tutorial: Custom PHP & WooCommerce Integration

Here is a complete, production-ready PHP snippet showing how to integrate TrackMe with a custom PHP ecommerce site, Laravel application, or WordPress/WooCommerce:

PHP Integration Snippet (functions.php or custom order handler)

<?php
/**
 * Register shipment in TrackMe when order is dispatched
 */
function trackme_dispatch_order($order_id, $tracking_number, $courier_name = 'auto') {
    $api_key = 'YOUR_SECRET_API_KEY_HERE';
    $endpoint = 'https://track.socialzync.com.au/api/v1/shipments';

    // 1. Gather order details from your platform
    $order = wc_get_order($order_id); // Or your custom database model
    $payload = [
        'trackingNumber'   => $tracking_number,
        'company'          => $courier_name,
        'orderNumber'      => '#' . $order_id,
        'customerName'     => $order->get_billing_first_name() . ' ' . $order->get_billing_last_name(),
        'customerPhone'    => $order->get_billing_phone(),
        'customerEmail'    => $order->get_billing_email(),
        'shippingCity'     => $order->get_shipping_city(),
        'orderTotal'       => $order->get_total(),
        'sendNotification' => true,
        'customMessage'    => "Hi {customerName}! Your order {orderNumber} has been handed to {company}.\nTrack doorstep delivery: {trackingUrl}"
    ];

    // 2. Dispatch server-to-server HTTP POST
    $ch = curl_init($endpoint);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($payload),
        CURLOPT_HTTPHEADER     => [
            'Content-Type: application/json',
            'x-api-key: ' . $api_key
        ],
        CURLOPT_TIMEOUT        => 10
    ]);

    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    $data = json_decode($response, true);
    if ($http_code === 201 && !empty($data['data']['trackingUrl'])) {
        // Save branded tracking URL to order metadata
        update_post_meta($order_id, '_trackme_tracking_url', $data['data']['trackingUrl']);
        return $data['data']['trackingUrl'];
    }

    return false;
}

🚀 Tutorial: Node.js & Next.js Integration

Integrating with a custom React/Next.js checkout or Express backend:

Node.js Async/Await Service

import fetch from 'node-fetch'; // Or native fetch in Node 18+

export async function createTrackMeShipment({ trackingNumber, orderNumber, customerName, phone, city, total }) {
    const res = await fetch('https://track.socialzync.com.au/api/v1/shipments', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'x-api-key': process.env.TRACKME_API_KEY
        },
        body: JSON.stringify({
            trackingNumber,
            orderNumber,
            customerName,
            customerPhone: phone,
            shippingCity: city,
            orderTotal: total,
            sendNotification: true
        })
    });

    const json = await res.json();
    if (!res.ok) throw new Error(json.error || 'Failed to create shipment');

    return {
        trackingUrl: json.data.trackingUrl,
        eta: json.data.estimatedDeliveryDate,
        status: json.data.standardizedStatus
    };
}

📦 Courier Auto-Detection Reference

Courier Name	API Key Identifier	Format Pattern	Recipient Phone
Domex	`"domex"`	Starts with `EC` or 9 digits	Optional
Pronto Lanka	`"prontolanka"`	2 letters + digits (e.g. `CC06310743`)	Optional
Koombiyo	`"koombiyo"`	8 digits (e.g. `88776655`)	Required
Citypak Express	`"citypack"`	Starts with `D` + 7-8 digits (e.g. `D10795332`)	Optional
Fardar Domestic	`"fardardomestic"`	Starts with `API` + 6-7 digits	Optional
TrackMe Sandbox	`"sandbox"`	Starts with `TEST-` or `MOCK-`	Optional

TrackMe Developer API (v1)

🔑 Authentication & Security

🛡️ Rate Limits & Infrastructure Protection

POST Create / Register Shipment

Request Body Parameters (JSON)

POST Send Custom Alert (SMS / WhatsApp / Email)

Request Body Parameters

POST Universal Real-Time Tracking Telemetry

Request Body Parameters (JSON)

POST Auto-Detect Courier & Validate Waybill

⚡ Webhook Event Stream & HMAC Verification

🛒 Tutorial: Custom PHP & WooCommerce Integration

🚀 Tutorial: Node.js & Next.js Integration

📦 Courier Auto-Detection Reference