### Webhook Setup and Verification

Source: https://docs.track123.com/reference/getting-started-with-your-api

Instructions on how to set up webhook URLs in Track123 settings and how to verify the authenticity of incoming webhook data using a signature and timestamp.

```APIDOC
## Webhook Setup and Verification

### Description
This section details the process of configuring webhooks in your Track123 account and the security measures to ensure data integrity.

### Setup
1. Navigate to the [webhooks settings](https://member.track123.com/notification) page.
2. Add your webhook URL where you wish to receive event notifications.
3. Select the specific events for which you want to receive updates.

### Sign Verification
To ensure the data originates from Track123, it is recommended to verify the signature of the received data. Alternatively, you can directly parse the POST data without verification.

**Verification Steps:**
1. Extract the `timestamp` and `signature` parameters from the POST data.
2. Generate a signature using your Track123 API key and the plain text `timestamp`.
3. Compare the generated signature with the `signature` received in the POST data.

**Signature Algorithm:**
- PHP: SHA256
- JAVA: HmacSHA256
```

--------------------------------

### Get Tracking Information with Track123 API (curl)

Source: https://docs.track123.com/reference/request

This example shows how to retrieve the current status and checkpoints for one or more tracking numbers using the Track123 API via a cURL command. It requires your API key and a JSON payload containing an array of tracking numbers.

```curl
curl --request POST \
     --url https://api.track123.com/gateway/open-api/tk/v2/track/query \
     --header 'Track123-Api-Secret: Your_Track123_API_key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "trackNos": [
    "123123122222"
  ]
}'
```

--------------------------------

### Get Ocean Cargo Carriers List (Ruby)

Source: https://docs.track123.com/reference/ocean-cargo

This Ruby snippet demonstrates fetching ocean cargo carriers using the 'net/http' library. It constructs and sends a GET request to the API endpoint and parses the JSON response. No external gems are strictly required for this basic example.

```ruby
require 'net/http'
require 'uri'
require 'json'

url = URI.parse('https://api.track123.com/gateway/open-api/tk/v2.1/ocean/carrier/list')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = (url.scheme == 'https')

request = Net::HTTP::Get.new(url.request_uri)
request['accept'] = 'application/json'

response = http.request(request)

if response.is_a?(Net::HTTPSuccess)
  data = JSON.parse(response.body)
  puts data
else
  puts "Error: #{response.code} #{response.message}"
end
```

--------------------------------

### Get Package Carriers List (PHP)

Source: https://docs.track123.com/reference/carriers

A PHP example for fetching package carriers using cURL. This script sends a GET request to the Track123 API and outputs the JSON response.

```php
<?php

$url = 'https://api.track123.com/gateway/open-api/tk/v2.1/courier/list';

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$headers = array();
$headers[] = 'Accept: application/json';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    echo $result;
}

curl_close($ch);

?>

```

--------------------------------

### Webhook Notification Setup

Source: https://docs.track123.com/reference/request

Set up a webhook to receive automatic notifications whenever the status of a tracking number changes. This is useful for real-time updates.

```APIDOC
## Webhook Notification Setup

### Description
Set up a webhook to receive automatic notifications whenever the status of a tracking number changes. This is useful for real-time updates.

### How to Set Up
1. Navigate to the [Developer > Webhook](https://member.track123.com/notification) section in your Track123 member area.
2. Enter the URL of your server endpoint where you want to receive webhook notifications.
3. Select 'Parcel' for the Webhook Type (unless you are tracking air or ocean cargo).
4. For Webhook Status, it is recommended to select 'All available updates' to ensure you receive all tracking status changes.
5. Save your webhook configuration.

### Request Body (Example for Webhook Payload)
When a tracking status changes, Track123 will send a POST request to your specified endpoint URL with a JSON payload similar to this:

```json
{
  "tracking_number": "YOUR_TRACKING_NUMBER",
  "courier_code": "fedex",
  "previous_status": "Processing",
  "current_status": "In Transit",
  "timestamp": "2023-10-27T12:00:00Z",
  "location": "Distribution Center"
}
```

### Response
Your server should respond with a 2xx status code to acknowledge receipt of the webhook. For example, a `200 OK` response is appropriate.
```

--------------------------------

### Get Package Carriers List (Node.js)

Source: https://docs.track123.com/reference/carriers

Example of fetching package carriers using Node.js. This snippet utilizes the 'node-fetch' library to make an HTTP GET request to the Track123 API endpoint.

```javascript
const fetch = require('node-fetch');

const url = 'https://api.track123.com/gateway/open-api/tk/v2.1/courier/list';

fetch(url, {
  method: 'GET',
  headers: {
    'accept': 'application/json'
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error fetching package carriers:', error);
  });

```

--------------------------------

### POST /tk/v2.1/track/query-realtime

Source: https://docs.track123.com/reference/query-realtime

This endpoint allows you to get instant tracking information for a shipment. You can provide a tracking number, and optionally, the courier code and destination postal code for more accurate results.

```APIDOC
## POST /tk/v2.1/track/query-realtime

### Description
Get instant tracking information for a shipment. This endpoint allows for real-time tracking updates by providing a tracking number and optional details like courier code and postal code.

### Method
POST

### Endpoint
https://api.track123.com/gateway/open-api/tk/v2.1/track/query-realtime

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **RAW_BODY** (object) - Required - The main object containing tracking details.
  - **trackNo** (string) - Required - Tracking number.
  - **courierCode** (string) - Optional - The unique carrier code. If null, the system will auto-detect the carrier based on the tracking number format.
  - **postalCode** (string) - Optional - The postcode of the destination (15 letters or numbers, can contain +, -, and spaces).
  - **extendFieldMap** (object) - Optional - Used to add additional information, such as phone number.
    - **phoneSuffix** (string) - Optional - The last 4 digits of the shipment sender's or recipient's phone number.
  - **lang** (string) - Optional - ISO 639-1 Language Code to specify the customer or order language. Defaults to 'en'. Applies only to carriers supporting multilingual tracking.

### Request Example
```json
{
  "RAW_BODY": {
    "trackNo": "LV209031969CN",
    "courierCode": "denmark-post",
    "postalCode": "000000",
    "extendFieldMap": {
      "phoneSuffix": "2390"
    },
    "lang": "en"
  }
}
```

### Response
#### Success Response (200)
- **code** (string) - Response code.
- **data** (object) - Contains tracking details.
  - **accepted** (object) - Details of the accepted tracking request.
    - **id** (string) - Unique identifier for the tracking request.
    - **trackNo** (string) - Tracking number.
    - **createTime** (string) - Time when the tracking request was created.
    - **nextUpdateTime** (string) - Time for the next scheduled update.
    - **shipFrom** (string) - Origin country code.
    - **shipTo** (string) - Destination country code.
    - **trackingStatus** (string) - Current tracking status code.
    - **transitStatus** (string) - Current transit status.
    - **transitSubStatus** (string) - Current transit sub-status.
    - **orderTime** (string) - Time the order was placed.
    - **receiptTime** (string) - Time the shipment was received.
    - **deliveredTime** (string) - Time the shipment was delivered.

#### Response Example
```json
{
  "code": "00000",
  "data": {
    "accepted": {
      "id": "741660669698387968",
      "trackNo": "84150004443799",
      "createTime": "2025-08-08 14:14:43",
      "nextUpdateTime": "2025-08-11 14:14:44",
      "shipFrom": "DE",
      "shipTo": "PL",
      "trackingStatus": "001",
      "transitStatus": "DELIVERED",
      "transitSubStatus": "DELIVERED_01",
      "orderTime": "2025-08-04 13:39:59",
      "receiptTime": "2025-08-04 13:39:59",
      "deliveredTime": "2025-08-06 09:51:36"
    }
  }
}
```
```

--------------------------------

### Retrack Air Cargo Tracking Request Example (JSON)

Source: https://docs.track123.com/reference/retrack-an-air-cargo-tracking

This example demonstrates the structure of a valid JSON request to retrack an air cargo shipment. It includes the necessary carrier code and tracking number. Ensure the 'Track123-Api-Secret' header is also provided.

```json
{
  "trackingNo": "369-84941043",
  "carrierCode": "atlasair"
}
```

--------------------------------

### GET /gateway/open-api/tk/v2.1/courier/list

Source: https://docs.track123.com/reference/carriers

Retrieves a list of supported package carriers. This endpoint provides carrier codes, names in Chinese and English, and their homepages.

```APIDOC
## GET /gateway/open-api/tk/v2.1/courier/list

### Description
Retrieves a list of supported package carriers. This endpoint provides carrier codes, names in Chinese and English, and their homepages.

### Method
GET

### Endpoint
https://api.track123.com/gateway/open-api/tk/v2.1/courier/list

### Parameters
#### Headers
- **Track123-Api-Secret** (string) - Required - Your API key

### Request Example
```bash
curl --request GET \
     --url https://api.track123.com/gateway/open-api/tk/v2.1/courier/list \
     --header 'accept: application/json' \
     --header 'Track123-Api-Secret: YOUR_API_KEY'
```

### Response
#### Success Response (200)
- **code** (string) - Service status code
- **data** (array of objects) - Array containing carrier information
  - **courierCode** (string) - The unique carrier code
  - **courierNameCN** (string) - Carrier name in Chinese
  - **courierNameEN** (string) - Carrier name in English
  - **courierHomePage** (string) - Carrier website home page
- **msg** (string) - The description information corresponding to the service status code or other auxiliary description information.

#### Response Example
```json
{
  "code": "00000",
  "data": [
    {
      "courierCode": "china-post",
      "courierNameCN": "中国邮政",
      "courierNameEN": "China Post",
      "courierHomePage": "http://yjcx.ems.com.cn/qps/yjcx"
    }
  ],
  "msg": "Success"
}
```
```

--------------------------------

### Get Ocean Cargo Carriers List (PHP)

Source: https://docs.track123.com/reference/ocean-cargo

This PHP snippet shows how to retrieve ocean cargo carriers using cURL. It makes a GET request to the API endpoint and decodes the JSON response. This example assumes the cURL extension is enabled in your PHP installation.

```php
<?php

$url = 'https://api.track123.com/gateway/open-api/tk/v2.1/ocean/carrier/list';
$headers = [
    'accept: application/json'
];

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

$response = curl_exec($ch);

if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
} else {
    $data = json_decode($response, true);
    print_r($data);
}

curl_close($ch);
?>
```

--------------------------------

### Best Practices for Managing Rate Limits

Source: https://docs.track123.com/reference/rate-limit

Recommended strategies for developers to effectively manage API request rates and handle rate limit errors.

```APIDOC
## Best Practices for Managing Rate Limits

### Description
This section provides best practices for developers to implement when interacting with the Track123 API to avoid exceeding rate limits.

### Method
N/A (This is informational, not an endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

### Best Practices
1. **Implement Request Throttling:** Use a queuing mechanism in your application to ensure the request rate stays within the allowed limit.
2. **Monitor Usage:** Track your request rates to proactively avoid hitting the limit.
3. **Handle A0706 Errors Gracefully:** When a A0706 response is received, pause further requests to the API and retry after a delay.
```

--------------------------------

### Get Ocean Cargo Carriers List (Python)

Source: https://docs.track123.com/reference/ocean-cargo

This Python snippet illustrates how to retrieve ocean cargo carriers using the 'requests' library. It sends a GET request to the API endpoint and processes the JSON response. The 'requests' library needs to be installed.

```python
import requests

url = 'https://api.track123.com/gateway/open-api/tk/v2.1/ocean/carrier/list'
headers = {
  'accept': 'application/json'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')
```

--------------------------------

### Register Ocean Cargo Tracking (OpenAPI)

Source: https://docs.track123.com/reference/register-ocean-cargo-tracking

This snippet defines the OpenAPI specification for registering ocean cargo tracking. It includes details on request parameters, request body schema, and example request/response payloads. The endpoint supports batch imports of up to 100 tracking numbers with a rate limit of 3 requests per second.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "api reference",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.track123.com/gateway/open-api"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Track123-Api-Secret"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "tags": [
    {
      "name": "Ocean cargo"
    }
  ],
  "paths": {
    "/tk/v2.1/ocean/track/import": {
      "post": {
        "tags": [
          "Ocean cargo"
        ],
        "summary": "Register ocean cargo tracking",
        "description": "Up to 100 tracking numbers can be imported at a time, the interface frequency limit is 3 requests/sec. The results include both accepted and rejected lists. The accepted list is consist of successful registered trackings and the rejected list is consist of failed ones.",
        "operationId": "register-ocean-cargo-tracking",
        "parameters": [
          {
            "name": "Track123-Api-Secret",
            "in": "header",
            "description": "Your API key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "Request Example": {
                  "value": [
                    {
                      "trackingNo": "MATS5217756000",
                      "carrierCode": "matson",
                      "type": 2,
                      "customerEmail": "support@track123.com"
                    }
                  ]
                }
              },
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "trackingNo": {
                      "type": "string",
                      "required": true,
                      "description": "Tracking number"
                    },
                    "type": {
                      "type": "integer",
                      "required": true,
                      "description": "Tracking number type (1. booking number 2. bill of landing number 3. container number)"
                    },
                    "carrierCode": {
                      "type": "string",
                      "required": true,
                      "description": "The unique carrier code"
                    },
                    "customerEmail": {
                      "type": "string",
                      "description": "The customer email address associated with the order"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "examples": {
                  "Success": {
                    "value": {
                      "code": "00000",
                      "data": {
                        "accepted": [
                          {
                            "trackingNo": "MATS5217756001",
                            "type": 2,
                            "orderNo": "11111112",
                            "carrierCode": "matson",
                            "customerEmail": "support@track123.com"
                          }
                        ],
                        "rejected": [
                          {
                            "trackingNo": "MATS5217756000",
                            "type": 2,
                            "carrierCode": "matson",
                            "error": {
                              "code": "A0400",
                              "msg": "单号已经导入"
                            }
                          }
                        ]
                      },
                      "msg": "Success",
                      "traceId": "N/A"
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Service status code"
                    },
                    "data": {
                      "type": "object",
                      "description": "Object actually returned",
                      "properties": {
                        "accepted": {
                          "type": "array",
                          "description": "Successful registration of tracking number",
                          "items": {
                            "type": "object",
                            "properties": {
                              "trackingNo": {
                                "type": "string"
                              }
                            }
                          }
                        },
                        "rejected": {
                          "type": "array",
                          "description": "Failed registration of tracking number",
                          "items": {
                            "type": "object",
                            "properties": {
                              "trackingNo": {
                                "type": "string"
                              },
                              "error": {
                                "type": "object",
                                "properties": {
                                  "code": {
                                    "type": "string"
                                  },
                                  "msg": {
                                    "type": "string"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "msg": {
                      "type": "string",
                      "description": "Response message"
                    },
                    "traceId": {
                      "type": "string",
                      "description": "Trace ID for request"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Get Ocean Cargo Carriers List (Node.js)

Source: https://docs.track123.com/reference/ocean-cargo

This Node.js snippet shows how to fetch ocean cargo carriers using the 'node-fetch' library. It makes a GET request to the specified API endpoint and handles the JSON response. Ensure 'node-fetch' is installed.

```javascript
import fetch from 'node-fetch';

const url = 'https://api.track123.com/gateway/open-api/tk/v2.1/ocean/carrier/list';
const headers = {
  'accept': 'application/json'
};

fetch(url, {
  method: 'GET',
  headers: headers
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

--------------------------------

### Container Tracking Information

Source: https://docs.track123.com/reference/get-ocean-cargo-trackings

This endpoint provides detailed tracking information for a given container, including its status, location, and estimated times.

```APIDOC
## GET /websites/track123_reference/containers

### Description
Retrieves detailed tracking information for containers.

### Method
GET

### Endpoint
/websites/track123_reference/containers

### Parameters
#### Query Parameters
- **trackingNumber** (string) - Required - The tracking number of the container.

### Request Example
```
GET /websites/track123_reference/containers?trackingNumber=ABC12345678
```

### Response
#### Success Response (200)
- **containerInfo** (array) - The container information.
  - **containerNo** (string) - Container number.
  - **containerSize** (string) - Container size.
  - **containerType** (string) - Container type.
  - **containerDetails** (string) - Container details.
  - **lastTrackingTime** (string) - Time of the last tracking information.
  - **nextUpdateTime** (string) - The next update time of a tracking number, if it is null, this tracking number will not update again.
  - **currentStatus** (object) - The container's current shipping status.
    - **eventDetails** (string) - The description of the latest tracking details.
    - **eventTime** (string) - The time of the event.
    - **eventTimeUTC** (string) - The time of the event in UTC.
    - **locationName** (string) - The location of the event.
    - **locationType** (string) - Location type.
    - **transitStatus** (string) - Transit status.
    - **transitSubStatus** (string) - Transit sub-status.
    - **vesselName** (string) - Vessel name.
    - **voyage** (string) - Voyage.
  - **receipt** (object) - The cargo receipt place information.
    - **locationName** (string) - The location of the event.
    - **estimateDepartTime** (string) - The estimated departure time.

#### Response Example
```json
{
  "containerInfo": [
    {
      "containerNo": "ABC12345678",
      "containerSize": "40FT",
      "containerType": "HC",
      "containerDetails": "Standard High Cube",
      "lastTrackingTime": "2023-10-27T10:00:00Z",
      "nextUpdateTime": "2023-10-28T12:00:00Z",
      "currentStatus": {
        "eventDetails": "Arrived at Port of Los Angeles",
        "eventTime": "2023-10-27T08:30:00-07:00",
        "eventTimeUTC": "2023-10-27T15:30:00Z",
        "locationName": "Port of Los Angeles",
        "locationType": "Port",
        "transitStatus": "In Transit",
        "transitSubStatus": "Port Arrival",
        "vesselName": "Evergreen",
        "voyage": "123N"
      },
      "receipt": {
        "locationName": "Port of Shanghai",
        "estimateDepartTime": "2023-10-20T18:00:00Z"
      }
    }
  ]
}
```
```

--------------------------------

### POST /gateway/open-api/tk/v2/track/query

Source: https://docs.track123.com/reference/request

Retrieves the current status and checkpoints for provided tracking numbers.

```APIDOC
## POST /gateway/open-api/tk/v2/track/query

### Description
Retrieves the current status and checkpoints for provided tracking numbers.

### Method
POST

### Endpoint
https://api.track123.com/gateway/open-api/tk/v2/track/query

### Parameters
#### Headers
- **Track123-Api-Secret** (string) - Required - Your Track123 API key.
- **accept** (string) - Optional - `application/json`
- **content-type** (string) - Optional - `application/json`

#### Request Body
- **trackNos** (array of strings) - Required - A list of tracking numbers to query.

### Request Example
```json
{
  "trackNos": [
    "123123122222"
  ]
}
```

### Response
#### Success Response (200)
- **tracking_status** (object) - Contains the tracking details.
  - **tracking_number** (string) - The tracking number.
  - **status** (string) - The current status of the tracking.
  - **checkpoints** (array of objects) - A list of tracking checkpoints.
    - **timestamp** (string) - The time of the checkpoint.
    - **location** (string) - The location of the checkpoint.
    - **message** (string) - The description of the checkpoint event.

#### Response Example
```json
{
  "tracking_status": {
    "tracking_number": "123123122222",
    "status": "In Transit",
    "checkpoints": [
      {
        "timestamp": "2023-10-27T10:00:00Z",
        "location": "Origin Facility",
        "message": "Package has been processed."
      }
    ]
  }
}
```
```

--------------------------------

### Get Package Carriers List (cURL)

Source: https://docs.track123.com/reference/carriers

This cURL command demonstrates how to make a GET request to the Track123 API to retrieve a list of available package carriers. It requires an 'accept' header for JSON response.

```shell
curl --request GET \
     --url https://api.track123.com/gateway/open-api/tk/v2.1/courier/list \
     --header 'accept: application/json'
```

--------------------------------

### Get Package Carriers List (Ruby)

Source: https://docs.track123.com/reference/carriers

This Ruby code snippet shows how to retrieve a list of package carriers from the Track123 API using the 'net/http' library. It sends a GET request and parses the JSON response.

```ruby
require 'net/http'
require 'uri'
require 'json'

uri = URI.parse('https://api.track123.com/gateway/open-api/tk/v2.1/courier/list')

response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  request = Net::HTTP::Get.new(uri)
  request['accept'] = 'application/json'
  http.request(request)
end

if response.is_a?(Net::HTTPSuccess)
  data = JSON.parse(response.body)
  puts data
else
  puts "Error: #{response.code} #{response.message}"
end

```

--------------------------------

### POST /tk/v2.1/ocean/track/import

Source: https://docs.track123.com/reference/register-ocean-cargo-tracking

Register ocean cargo tracking details. This endpoint allows for bulk import of up to 100 tracking numbers per request, with a rate limit of 3 requests per second. It returns a list of successfully registered trackings and a list of those that were rejected.

```APIDOC
## POST /tk/v2.1/ocean/track/import

### Description
Register ocean cargo tracking details. This endpoint allows for bulk import of up to 100 tracking numbers per request, with a rate limit of 3 requests per second. It returns a list of successfully registered trackings and a list of those that were rejected.

### Method
POST

### Endpoint
https://api.track123.com/gateway/open-api/tk/v2.1/ocean/track/import

### Parameters
#### Header Parameters
- **Track123-Api-Secret** (string) - Required - Your API key

#### Request Body
- **trackingNo** (string) - Required - Tracking number
- **type** (integer) - Required - Tracking number type (1. booking number 2. bill of landing number 3. container number)
- **carrierCode** (string) - Required - The unique carrier code
- **customerEmail** (string) - Optional - The customer email address associated with the order

### Request Example
```json
[
  {
    "trackingNo": "MATS5217756000",
    "carrierCode": "matson",
    "type": 2,
    "customerEmail": "support@track123.com"
  }
]
```

### Response
#### Success Response (200)
- **code** (string) - Service status code
- **data** (object) - Object actually returned
  - **accepted** (array) - Successful registration of tracking number
    - **trackingNo** (string) - Tracking number
    - **type** (integer) - Tracking number type
    - **orderNo** (string) - Order number
    - **carrierCode** (string) - Carrier code
    - **customerEmail** (string) - Customer email
  - **rejected** (array) - Failed registration of tracking number
    - **trackingNo** (string) - Tracking number
    - **type** (integer) - Tracking number type
    - **carrierCode** (string) - Carrier code
    - **error** (object) - Error details
      - **code** (string) - Error code
      - **msg** (string) - Error message
- **msg** (string) - Success message
- **traceId** (string) - Trace ID

#### Response Example
```json
{
  "code": "00000",
  "data": {
    "accepted": [
      {
        "trackingNo": "MATS5217756001",
        "type": 2,
        "orderNo": "11111112",
        "carrierCode": "matson",
        "customerEmail": "support@track123.com"
      }
    ],
    "rejected": [
      {
        "trackingNo": "MATS5217756000",
        "type": 2,
        "carrierCode": "matson",
        "error": {
          "code": "A0400",
          "msg": "单号已经导入"
        }
      }
    ]
  },
  "msg": "Success",
  "traceId": "N/A"
}
```
```

--------------------------------

### POST /gateway/open-api/tk/v2/track/import

Source: https://docs.track123.com/reference/request

Registers new tracking numbers with the Track123 service. You can provide the tracking number and courier code, or let the system attempt to detect the courier.

```APIDOC
## POST /gateway/open-api/tk/v2/track/import

### Description
Registers new tracking numbers with the Track123 service. You can provide the tracking number and courier code, or let the system attempt to detect the courier.

### Method
POST

### Endpoint
https://api.track123.com/gateway/open-api/tk/v2/track/import

### Parameters
#### Headers
- **Track123-Api-Secret** (string) - Required - Your Track123 API key.
- **accept** (string) - Optional - `application/json`
- **content-type** (string) - Optional - `application/json`

#### Request Body
- **Array of Objects** - Required - Each object should contain:
  - **trackNo** (string) - Required - The tracking number.
  - **courierCode** (string) - Optional - The courier code. If not provided, the system will attempt to detect the courier.

### Request Example
```json
[
  {
    "trackNo": "771700723045",
    "courierCode": "fedex"
  }
]
```

### Response
#### Success Response (200)
- **status** (string) - The status of the tracking registration.
- **message** (string) - A message indicating the result of the operation.

#### Response Example
```json
{
  "status": "success",
  "message": "Tracking registered successfully."
}
```
```

--------------------------------

### Get Package Carriers List (Python)

Source: https://docs.track123.com/reference/carriers

This Python script uses the 'requests' library to fetch the list of package carriers from the Track123 API. It handles potential request errors and prints the JSON response.

```python
import requests

url = 'https://api.track123.com/gateway/open-api/tk/v2.1/courier/list'
headers = {
    'accept': 'application/json'
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()  # Raise an exception for bad status codes
    data = response.json()
    print(data)
except requests.exceptions.RequestException as e:
    print(f'Error fetching package carriers: {e}')

```

--------------------------------

### Register Air Cargo Trackings (OpenAPI Definition)

Source: https://docs.track123.com/reference/register-air-cargo-trackings

This OpenAPI definition describes the 'register-air-cargo-trackings' POST endpoint. It allows for batch registration of up to 100 air cargo tracking numbers. The endpoint requires an API key for authentication and returns a response indicating accepted and rejected tracking numbers.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "api reference",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.track123.com/gateway/open-api"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Track123-Api-Secret"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "tags": [
    {
      "name": "Air cargo"
    }
  ],
  "paths": {
    "/tk/v2.1/aviation/track/import": {
      "post": {
        "tags": [
          "Air cargo"
        ],
        "summary": "Register air cargo trackings",
        "description": "Up to 100 tracking numbers can be imported at a time, the interface frequency limit is 3 requests/sec. The results include both accepted and rejected lists. The accepted list is consist of successful registered trackings and the rejected list is consist of failed ones.",
        "operationId": "register-air-cargo-trackings",
        "parameters": [
          {
            "name": "Track123-Api-Secret",
            "in": "header",
            "description": "Your API key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "Request Example": {
                  "value": [
                    {
                      "carrierCode": "atlasair",
                      "trackingNo": "369-84941043"
                    }
                  ]
                }
              },
              "schema": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "carrierCode": {
                      "type": "string",
                      "required": true,
                      "description": "The unique carrier code"
                    },
                    "trackingNo": {
                      "type": "string",
                      "description": "Tracking number"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "examples": {
                  "Success": {
                    "value": {
                      "code": "00000",
                      "data": {
                        "accepted": [
                          {
                            "trackingNo": "369-987654321",
                            "carrierCode": "atlasair"
                          }
                        ],
                        "rejected": [
                          {
                            "trackingNo": "369-84941043",
                            "carrierCode": "atlasair",
                            "error": {
                              "msg": "单号已经注册,请检查",
                              "code": "A0400"
                            }
                          }
                        ]
                      },
                      "msg": "Success",
                      "traceId": "6058fd26a116449899a3b98c6a52547a.147.16709341862880651"
                    }
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Service status code"
                    },
                    "data": {
                      "type": "object",
                      "description": "Object actually returned",
                      "properties": {
                        "accepted": {
                          "type": "array",
                          "description": "Successful registration of tracking number",
                          "items": {
                            "type": "object",
                            "properties": {
                              "trackingNo": {
                                "type": "string",
                                "description": "Tracking number"
                              },
                              "carrierCode": {
                                "type": "string",
                                "description": "The unique carrier code"
                              }
                            }
                          }
                        },
                        "rejected": {
                          "type": "array",
                          "description": "Rejected registration of tracking number",
                          "items": {
                            "type": "object",
                            "properties": {
                              "trackingNo": {
                                "type": "string",
                                "description": "Tracking number"
                              },
                              "carrierCode": {
                                "type": "string",
                                "description": "The unique carrier code"
                              },
                              "error": {
                                "type": "object",
                                "properties": {
                                  "msg": {
                                    "type": "string",
                                    "description": "Error message"
                                  },
                                  "code": {
                                    "type": "string",
                                    "description": "Error code"
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    },
                    "msg": {
                      "type": "string",
                      "description": "Service message"
                    },
                    "traceId": {
                      "type": "string",
                      "description": "Trace ID"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Edit Tracking POST Request Example (JSON)

Source: https://docs.track123.com/reference/edit-a-package-tracking

This snippet demonstrates a sample JSON payload for the POST request to edit tracking information. It includes essential fields like 'courierCode' and 'trackNo', along with optional parameters such as 'country'.

```json
{
  "courierCode": "japan-post",
  "trackNo": "LV209031969JP",
  "country": "GB"
}
```

--------------------------------

### Get Air Cargo Carriers List (Ruby)

Source: https://docs.track123.com/reference/air-cargo

This Ruby snippet illustrates how to fetch air cargo carrier data from the Track123 API using the 'httparty' gem. It sends a GET request to the specified endpoint and prints the JSON response.

```ruby
require 'httparty'

url = 'https://api.track123.com/gateway/open-api/tk/v2.1/aviation/carrier/list'
headers = { 'accept' => 'application/json' }

response = HTTParty.get(url, headers: headers)

puts response.body
```

--------------------------------

### Webhook Sign Verification (PHP & Java)

Source: https://docs.track123.com/reference/getting-started-with-your-api

This snippet demonstrates how to verify the signature of incoming webhook data from Track123. It involves parsing the timestamp and signature from the POST data and generating a signature using your API key and the timestamp. The generated signature is then compared with the received signature to ensure data authenticity. This process is crucial for security and data integrity.

```php
<?php
// Assuming you have your Track123 API key
$apiKey = 'YOUR_TRACK123_API_KEY';

// Parse timestamp and signature from POST data
$timestamp = $_POST['timestamp'];
$signature = $_POST['signature'];

// Generate the signature
$generatedSignature = hash_hmac('sha256', $apiKey . $timestamp, $apiKey);

// Verify the signature
if ($generatedSignature === $signature) {
    echo 'Signature verified successfully!';
    // Process the webhook data
} else {
    echo 'Signature verification failed!';
    // Handle the error
}
?>
```

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class WebhookVerifier {

    public static boolean verifySignature(String apiKey, String timestamp, String receivedSignature) {
        try {
            Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
            SecretKeySpec secret_key = new SecretKeySpec(apiKey.getBytes(), "HmacSHA256");
            sha256_HMAC.init(secret_key);

            String dataToSign = apiKey + timestamp;
            byte[] rawHmac = sha256_HMAC.doFinal(dataToSign.getBytes());
            String generatedSignature = bytesToHex(rawHmac);

            return generatedSignature.equals(receivedSignature);
        } catch (Exception e) {
            e.printStackTrace();
            return false;
        }
    }

    private static String bytesToHex(byte[] hash) {
        StringBuilder hexString = new StringBuilder(2 * hash.length);
        for (byte b : hash) {
            String hex = Integer.toHexString(0xff & b);
            if (hex.length() == 1) {
                hexString.append('0');
            }
            hexString.append(hex);
        }
        return hexString.toString();
    }

    public static void main(String[] args) {
        String apiKey = "YOUR_TRACK123_API_KEY";
        String timestamp = "1632466678868"; // Example timestamp
        String receivedSignature = "e53cf138931ad85d20955dfc6a0355e777f915a4f511e147c9bd2c6942273151"; // Example signature

        if (verifySignature(apiKey, timestamp, receivedSignature)) {
            System.out.println("Signature verified successfully!");
            // Process the webhook data
        } else {
            System.out.println("Signature verification failed!");
            // Handle the error
        }
    }
}
```

--------------------------------

### Get Air Cargo Carriers List (Python)

Source: https://docs.track123.com/reference/air-cargo

This Python snippet shows how to make an HTTP GET request to the Track123 API to obtain a list of air cargo carriers. It uses the 'requests' library to send the request and prints the JSON response.

```python
import requests

url = "https://api.track123.com/gateway/open-api/tk/v2.1/aviation/carrier/list"
headers = {
    'accept': 'application/json'
}

response = requests.get(url, headers=headers)

print(response.json())
```

--------------------------------

### Get Air Cargo Carriers List (Node.js)

Source: https://docs.track123.com/reference/air-cargo

This Node.js snippet shows how to make an HTTP GET request to the Track123 API to fetch a list of air cargo carriers. It utilizes the 'axios' library for making the request and handles the JSON response.

```javascript
const axios = require('axios');

const options = {
  method: 'GET',
  url: 'https://api.track123.com/gateway/open-api/tk/v2.1/aviation/carrier/list',
  headers: {
    'accept': 'application/json'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
```

--------------------------------

### Rate Limit Details

Source: https://docs.track123.com/reference/rate-limit

Information regarding the API's rate limiting policy, including maximum requests per second and the error response for exceeding the limit.

```APIDOC
## Rate Limit Details

### Description
This section details the rate limiting policy for the Track123 API to ensure optimal performance and prevent misuse.

### Method
N/A (This is informational, not an endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Error Response (A0706)
- **A0706** (string) - Indicates that the rate limit has been exceeded.

#### Response Example
```json
{
  "error": "A0706 Too Many Requests"
}
```

### Rate Limit Details
- **Maximum Requests:** 5 requests per second per endpoint.
- **Exceeding the Limit:** If the rate limit is exceeded, the API will return an HTTP **A0706 Too Many Requests** error.
- **Retry Mechanism:** When you receive an A0706 error, reduce the frequency of requests and retry after a short delay.
```