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.

治疗结点

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 取货地点或地址,并获取,以便将调用路由到取货处理程序。

申请跟踪 API 访问权限

跟踪 API 不是自助式服务。请提交此表单,我们将在一个工作日内回复,提供凭据或提出后续问题。跟踪事件没有 UAT 环境;访问权限仅在获得批准后才可用于生产环境。

开发者 FAQ

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将多承运商预订抽象为一个令牌。