REST API

API documentation

View endpoint documentation for quotation, shipping services, and shipment CRUD. Production APIs use a personal token from Profile Settings. A separate UAT host is available for integration testing. Tracking API access requires a short registration form and has no UAT environment.

API 基本網址

Production base URL: https://app.thainexus.co.th/functions

Append the function name to this URL. Examples:

  • POSThttps://app.thainexus.co.th/functions/apiQuote
  • POSThttps://app.thainexus.co.th/functions/shipmentCrud
  • POSThttps://app.thainexus.co.th/functions/apiShippingServices

Interactive live tests live in the client app. Get your production token from Profile Settings.

UAT(測試)環境

Use the UAT host to build and verify integrations before switching to production. Request and response shapes match production for quotation, shipping services, and shipment CRUD. Tracking events and the Tracking API are production-only; there is no UAT for tracking.

UAT base URL: https://uat-dev.thainexus.co.th/functions

Same function paths as production (apiQuote, apiShippingServices, shipmentCrud). Example:

  • POSThttps://uat-dev.thainexus.co.th/functions/apiQuote
  • POSThttps://uat-dev.thainexus.co.th/functions/shipmentCrud
  • POSThttps://uat-dev.thainexus.co.th/functions/apiShippingServices

如何取得 UAT API 金鑰

  1. 01

    Request a UAT API key

    UAT keys are not self-serve. Email contact@thainexus.co.th (or contact your Thai Nexus account manager) and ask for a UAT API key. Keys use the format uat_tnx_... and only work on the UAT host.

  2. 02

    Call the UAT base URL

    Send the same paths as production, but against https://uat-dev.thainexus.co.th/functions. Do not use a production tnx_... token on UAT, and do not use a uat_tnx_... token on production.

  3. 03

    Authenticate UAT requests

    Send Authorization: Bearer uat_tnx_... or include api_token in the JSON body. shipmentCrud always expects api_token in the body.

UAT 報價申請範例

curl -X POST https://uat-dev.thainexus.co.th/functions/apiQuote \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "uat_tnx_XXXXXXXX_XXXXXXXX_XXXXXXXX",
    "country": "US",
    "actual_weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15,
    "is_document": false
  }'
  • Supported on UAT: apiQuote, apiShippingServices, and shipmentCrud.
  • shipmentCrud on UAT is a sandbox. Creates, updates, and deletes stay on UAT and do not write to production shipments.
  • There is no UAT for tracking events or the Tracking API. Use public tracking or request production Tracking API access below.
  • When your integration is ready, switch the base URL to production and use your Profile Settings tnx_... token.

Need a key? Email contact@thainexus.co.th with subject "UAT API key request".

身份認證

Steps below are for production (tnx_...). For UAT keys, see UAT (test) environment.

  1. 01

    Create a free client account

    Register at https://app.thainexus.co.th/register, verify your email, and sign in.

  2. 02

    Generate an API token

    Open Profile Settings in the client app and generate a token (format tnx_...). Keep it secret. Store integrations (WooCommerce, Shopify, BigCommerce) use the same token.

  3. 03

    Authenticate requests

    Send Authorization: Bearer tnx_... or include api_token in the JSON body. All shipmentCrud endpoints pass api_token in the request body.

Endpoint

Quotation API

POST /apiQuote

Full endpoint: https://app.thainexus.co.th/functions/apiQuote

Returns shipping quotes from all active couriers for a given package. Uses the internal rate table database with the 9-step pricing formula. Formula: Volumetric Weight = (L x W x H) / 5000, Chargeable Weight = max(actual, volumetric). Destination TH / THAILAND is supported when rate tables include it. Unlike the public shipping calculator, this API does not suppress domestic Thailand quotes.

Auth: Pass api_token in the request body (from Profile Settings)

Request fields

FieldDescription
api_tokenstring - Your API token
countrystring - ISO code (US, GB, TH, JP) or full name (UNITED STATES, THAILAND). TH is not suppressed.
actual_weight_kgnumber - Actual weight in kg
length_cmnumber - Package length in cm
width_cmnumber - Package width in cm
height_cmnumber - Package height in cm
is_documentboolean - Optional (default false). If true, returns only document-type quotes. If false, excludes document quotes.

Example request

{
  "api_token": "tnx_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX",
  "country": "US",
  "actual_weight_kg": 2.5,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 15,
  "is_document": false
}

cURL example

curl -X POST https://app.thainexus.co.th/functions/apiQuote \
  -H "Content-Type: application/json" \
  -d '{
    "api_token": "tnx_XXXXXXXX_XXXXXXXX_XXXXXXXX_XXXXXXXX",
    "country": "US",
    "actual_weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15,
    "is_document": false
  }'

Example response

{
  "success": true,
  "country": "US",
  "package": {
    "actual_weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  },
  "quotes_count": 3,
  "quotes": [
    {
      "courier_name": "flex_dap",
      "display_name": "Flex DAP",
      "delivery_type": "pickup",
      "estimated_days": "5-10",
      "final_price_thb": 1250,
      "currency": "THB",
      "chargeable_weight_kg": 2.5,
      "weight_used": "actual",
      "volumetric_weight_kg": 1.8,
      "is_oversize": false
    }
  ]
}

Response fields

FieldDescription
courier_nameInternal courier ID
display_nameHuman-readable name
final_price_thbTotal price in THB
estimated_daysDelivery estimate (e.g. "5-10")
chargeable_weight_kgWeight used for pricing
weight_used"actual" or "volumetric"
  • Unlike the public calculator, domestic Thailand quotes are not suppressed.
  • Live testing is available in the client app under Integrations / API documentation.
  • For pre-production testing, call the same path on https://uat-dev.thainexus.co.th/functions with a uat_tnx_... key (contact us for a UAT key).

Service List API

POST /apiShippingServices

Full endpoint: https://app.thainexus.co.th/functions/apiShippingServices

Returns all active shipping services with their name, logo, and ID. Responses are cached for 24 hours server-side - repeated requests within that window return instantly without any database hit. Uses the same personal API token from Profile Settings (the tnx_... token) as apiQuote and other client APIs.

Auth: Bearer token recommended, or api_token in the request body

Request fields

FieldDescription
api_tokenOptional if Authorization: Bearer tnx_... is set. No other body fields required.

Example request

{
  "api_token": "tnx_xxxxxxxxxxxxxxxxxxxx"
}

cURL example

curl --location 'https://app.thainexus.co.th/functions/apiShippingServices' \
  --header 'Authorization: Bearer tnx_xxxxxxxxxxxxxxxxxxxx'

fetch example

const response = await fetch(
  "https://app.thainexus.co.th/functions/apiShippingServices",
  {
    method: "GET",
    headers: {
      "Authorization": "Bearer tnx_xxxxxxxxxxxxxxxxxxxx"
    }
  }
);
const data = await response.json();

Example response

{
  "success": true,
  "cached": false,
  "cache_expires_at": "2026-06-12T10:00:00.000Z",
  "total": 10,
  "data": [
    {
      "id": "swift_dap",
      "service_name": "Thai Nexus Express Swift DAP",
      "logo": "https://..."
    }
  ]
}

Response fields

FieldDescription
idstring - Unique service identifier (e.g. swift_dap)
service_namestring - Full display name
logostring | null - URL to the service logo image
cachedboolean - Whether this response was served from the 24h cache
cache_expires_atISO datetime - When the current cache entry expires
  • The service list is cached in-memory on the server for 24 hours after the first request.
  • Subsequent requests within that window return cached: true with no database query.
  • Cache resets when the 24-hour TTL expires or when the server restarts.
  • Use service IDs when creating shipments from your store integration.
  • UAT: same path on https://uat-dev.thainexus.co.th/functions with a uat_tnx_... key.

Shipment CRUD API

POST /shipmentCrud

Full endpoint: https://app.thainexus.co.th/functions/shipmentCrud

All endpoints use the shipmentCrud backend function. Pass the action field to select the operation. Soft-delete is used - records remain in the database for audit but are excluded from standard queries.

Auth: Pass your api_token in the request body (get it from Profile Settings)

Request fields

FieldDescription
api_tokenYour personal API token
actioncreate | update | get | list | delete | restore
request_numberRequired for get / update / delete / restore
dataObject with shipment fields (create / update)
page / limit / statusOptional list filters
reasonOptional delete reason

Example request

{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "create",
  "data": {
    "shipper_address": {
      "name": "John Doe",
      "phone": "+66812345678",
      "address_line1": "123 Sukhumvit",
      "city": "Bangkok",
      "country": "TH"
    },
    "consignee_address": {
      "name": "Jane Smith",
      "phone": "+12025551234",
      "address_line1": "456 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "actual_weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15,
    "shipment_type": "parcel",
    "shipment_description": "Electronics"
  }
}

Actions

Create shipment
action: create

Create a new shipment request with origin/destination/dimensions. Volumetric weight is auto-calculated from dimensions. Status defaults to pending.

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "create",
  "data": {
    "shipper_address": {
      "name": "John Doe",
      "phone": "+66812345678",
      "address_line1": "123 Sukhumvit",
      "city": "Bangkok",
      "country": "TH"
    },
    "consignee_address": {
      "name": "Jane Smith",
      "phone": "+12025551234",
      "address_line1": "456 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001",
      "country": "US"
    },
    "actual_weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15,
    "shipment_type": "parcel",
    "shipment_description": "Electronics"
  }
}
Response
{
  "success": true,
  "action": "create",
  "data": {
    "id": "abc123",
    "request_number": "SR-X9K2F7",
    "status": "pending",
    "volumetric_weight_kg": 1.8,
    "submitted_date": "2026-04-24T10:00:00Z"
  }
}
Update shipment
action: update

Update a shipment's details. Blocked for shipped/completed shipments. Updates are blocked when status is: in_transit, delivered, confiscated, returned, lost. Staff can bypass this restriction.

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "update",
  "request_number": "SR-X9K2F7",
  "data": {
    "actual_weight_kg": 3.0,
    "shipment_description": "Updated description"
  }
}
Response
{
  "success": true,
  "action": "update",
  "data": {
    "id": "abc123",
    "request_number": "SR-X9K2F7",
    "updated_fields": ["actual_weight_kg", "shipment_description", "volumetric_weight_kg"]
  }
}
Get shipment
action: get

Get a single shipment by ID or request number.

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "get",
  "request_number": "SR-X9K2F7"
}
Response
{
  "success": true,
  "action": "get",
  "data": { /* full ShipmentRequest entity */ }
}
List shipments
action: list

Paginated list of shipments for the authenticated user. Staff can list all shipments or filter by client_email. Soft-deleted records are excluded.

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "list",
  "page": 1,
  "limit": 20,
  "status": "pending"
}
Response
{
  "success": true,
  "action": "list",
  "data": [ /* summary shipment objects */ ],
  "pagination": { "page": 1, "limit": 20, "total": 45, "total_pages": 3 }
}
Delete shipment
action: delete

Soft-delete a shipment. Record remains for audit. Sets is_deleted=true with timestamp. Active/shipped shipments cannot be deleted by clients.

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "delete",
  "request_number": "SR-X9K2F7",
  "reason": "Created by mistake"
}
Response
{
  "success": true,
  "action": "delete",
  "data": {
    "id": "abc123",
    "request_number": "SR-X9K2F7",
    "deleted_at": "2026-04-24T10:30:00Z"
  }
}
Restore shipment
action: restore

Restore a soft-deleted shipment (staff only).

Request payload
{
  "api_token": "tnx_YOUR_TOKEN",
  "action": "restore",
  "request_number": "SR-X9K2F7"
}
Response
{
  "success": true,
  "action": "restore",
  "data": { "id": "abc123", "request_number": "SR-X9K2F7" }
}
  • Volumetric weight is auto-calculated from dimensions. Status defaults to pending on create.
  • Updates are blocked when status is in_transit, delivered, confiscated, returned, or lost (staff can bypass).
  • Soft-delete sets is_deleted=true with timestamp. Active/shipped shipments cannot be deleted by clients.
  • Restore is staff only.
  • Staff can list all shipments or filter by client_email. Soft-deleted records are excluded from list.
  • UAT: same actions on https://uat-dev.thainexus.co.th/functions/shipmentCrud with a uat_tnx_... key. UAT shipment data is sandbox-only and does not affect production.

Tracking API

POST /Tracking API (registration required)

Programmatic access to Thai Nexus Express tracking events for TNX references and linked carrier updates. Access is provisioned after you submit the registration form on this page. There is no UAT environment for tracking events.

Auth: Issued after registration approval

Request fields

FieldDescription
trackingNumberTNX reference or supported carrier/ref number
refreshOptional boolean to force a fresh pull

Example request

{
  "trackingNumber": "TNX1783820599067POM",
  "refresh": true
}
  • Public browser tracking stays on tracking.thainexus.co.th without an API key.
  • API access is for platforms, marketplaces, and internal tools that need structured event data.
  • Rate limits apply; 429 responses mean you should back off and retry.
  • No UAT for tracking events. Test against production tracking only after access is approved.

合作夥伴領取 API

合作夥伴帳戶可以透過 shipmentCrud 提交泰國取貨申請,並管理已儲存的取貨地址。這與國際貨運 CRUD 不同,且需要 client_type partner。

  • 相同的基礎網址:POST https://app.thainexus.co.th/functions/shipmentCrud
  • 動作包括 verify_account、list_destinations、quote_fee、create、list、get、cancel 和 get_tracking。
  • 設定 api_scope 取貨地點或清單地址,並取得 SO 呼叫路由至取貨處理常式。

申請追蹤 API 存取權限

追蹤 API 並非自助式服務。請提交此表單,我們會在一個工作天內回覆,並提供憑證或後續問題。追蹤事件沒有 UAT 環境;通過核准後,只能存取生產環境。

開發者常見問題集

Thai Nexus API 是否屬於付費方案?
報價、配送服務清單和貨件 CRUD 使用客戶端應用程式中「個人資料設定」的免費客戶端帳戶權杖。在合理使用範圍內,標準商店整合不收取每次呼叫費用。在審核註冊表單後,即可授予追蹤 API 存取權限。大量使用追蹤 API 的情況應在表單中揭露。
我該從哪裡取得 Thai Nexus API 權杖?
登入客戶端應用程式,開啟「個人資料設定」,然後產生或複製您的 tnx_ 生產權杖。WooCommerce、Shopify 和 BigCommerce 整合使用相同的權杖。UAT 金鑰使用 uat_tnx_ 前綴,並依申請發放;這些金鑰不會出現在「帳號設定」中。切勿將權杖嵌入公開的前端程式碼中。
什麼是 Thai Nexus UAT API 環境?
在您上線之前,UAT 會在 uat-dev.thainexus.co.th 上執行,以提供報價、配送服務和貨件 CRUD。向 Thai Nexus 申請 UAT API 金鑰;此金鑰並非自助式。追蹤事件沒有 UAT;追蹤 API 獲得批准後,追蹤仍僅限於生產環境。
Thai Nexus 追蹤 API 和公開追蹤有何差別?
任何人都可以透過 tracking.thainexus.co.th 追蹤 TNX 號碼,無需驗證。追蹤 API 會為系統傳回結構化 JSON 事件,且需要註冊。追蹤功能沒有 UAT。適用速率限制;HTTP 429 表示暫停並重試。
Thai Nexus API 的速率限制為何?
公開追蹤和追蹤 API 端點的速率會依 IP 和權杖受到限制。HTTP 429 回應代表需要等待,並以退避機制重試。大流量輪詢應改為合理的間隔,或在可行時改用 Webhook。請在追蹤 API 註冊表單上揭露預期數量。
Thai Nexus 是否與 Shopify 整合?
可以,透過已發布的 Shopify 整合,使用您的客戶端 API 權杖取得即時結帳費率並建立出貨。從整合頁面安裝。與 WooCommerce 和 BigCommerce 使用相同的權杖。追蹤 API 需另外註冊。
Thai Nexus 是否與 WooCommerce 整合?
是的。WooCommerce 外掛程式使用「個人資料設定」中的相同 tnx_ 權杖。將起運地址設定為您的華欣或曼谷倉庫。費率報價會呼叫開發人員頁面上記載的報價端點。
如何從泰國在結帳時顯示即時運費?
從商店後台呼叫報價端點,並提供重量、尺寸和目的地國家/地區。Thai Nexus、Shopify、WooCommerce 和 BigCommerce 整合包含相同的呼叫。在確認內容之前,費率僅供參考;具有約束力的報價可能需要對受管制商品進行人工審核。
誰提供來自泰國的配送 API?
Thai Nexus Point Co., Ltd. 提供報價、出貨與追蹤的 REST 端點。登記/稅務編號 {reg}。配送業者原生 API (DHL、FedEx) 為獨立合約;Thai Nexus 將多個配送業者的預訂整合在單一權杖之下。