合作夥伴 REST API

合作夥伴領取 API

整合合作夥伴帳戶的取貨申請和已儲存的取貨地址 (client_type: partner)。取件申請和國際貨運都使用相同的 shipmentCrud 端點。當您使用取貨專用欄位或設定 api_scope 時,系統會自動轉接取貨電話。

端點

生產環境網址(僅限 POST):

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

Request envelope

FieldDescription
api_tokenRequired. Partner token from Profile > API tab (tnx_...). Bearer header also works.
actionRequired. e.g. verify_account, create, list, get
api_scopeRequired for pickup list/get ("pickup") and address CRUD ("address")
dataRequired for create/update. Pickup fields go inside data, not at top level

Identifiers

FieldDescription
pickup_numberPU-XXXXXX format. From create response or list. Use for get, cancel, get_tracking.
id (pickup)24-char hex. Alternative to pickup_number for get.
destination_selectiontnx:{branchId} or partner:{warehouseId}. Copy exactly from list_destinations.
id (address)24-char hex from address list or create. Use for address get, update, delete.
waybill_numberYour reference string. You provide it on create.

建議的工作流程

  1. verify_account - confirm token works and account is partner
  2. allowed_cities - (optional) confirm pickup city is served
  3. list_destinations - get a real destination_selection value
  4. quote_fee - (optional) estimate fee before create
  5. create - submit pickup using values from list_destinations
  6. list / get - read back pickup_number for tracking or cancel
  7. get_tracking - only after staff approval assigns tracking code
  • Set api_scope: pickup for list and get pickup requests.
  • Set api_scope: address for all saved address CRUD calls.
  • Pickup routing also triggers when action is verify_account, allowed_cities, list_destinations, quote_fee, get_tracking, or cancel.
  • If you see shipper_address required on create, pickup was not routed. Include data.pickup_location, data.destination_selection, and data.waybill_number.

身份認證

  1. 01

    Partner account required

    Pickup API is available only to partner accounts (client_type: partner). Standard client tokens return HTTP 403.

  2. 02

    Generate an API token

    In the client app, open Profile > API tab and copy your tnx_... token. Keep it secret. Do not embed tokens in public frontend code.

  3. 03

    Authenticate requests

    Include api_token in every JSON body, or send Authorization: Bearer tnx_... . All calls use POST with Content-Type: application/json.

API 測試環境

透過此網站代理伺服器,對生產環境的 shipmentCrud 執行即時呼叫。請在下方貼上您的合作夥伴 tnx_ 權杖。權杖只會保留在您的瀏覽器工作階段中。

領取預約操作

verify_account

POST /shipmentCrud

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

Confirms token and partner account type.

Auth: api_token in body or Bearer header

Example request

{
  "api_token": "tnx_...",
  "action": "verify_account"
}

Example response

{
  "success": true,
  "account": {
    "user_email": "partner@example.com",
    "partner_id": "abc123",
    "partner_name": "Example Partner",
    "client_type": "partner"
  }
}

list_destinations

POST /shipmentCrud

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

Returns read-only destination options. Copy destination_selection exactly from tnx_branches[] or partner_branches[].

Auth: api_token

Example request

{
  "api_token": "tnx_...",
  "action": "list_destinations"
}

quote_fee

POST /shipmentCrud

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

Estimate pickup fee before creating a request.

Auth: api_token

Request fields

FieldDescription
cityPickup city (must be in allowed cities)
items[]Parcel lines with description, quantity, weight_kg, length_cm, width_cm, height_cm

Example request

{
  "api_token": "tnx_...",
  "action": "quote_fee",
  "city": "Bangkok",
  "items": [{
    "description": "Box",
    "quantity": 1,
    "weight_kg": 2.5,
    "length_cm": 30,
    "width_cm": 20,
    "height_cm": 15
  }]
}

create

POST /shipmentCrud

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

Creates a pickup request. Run list_destinations first and copy a real destination_selection.

Auth: api_token

Request fields

FieldDescription
data.pickup_location or data.pickup_address_idInline contact + address, or saved address id
data.destination_selectionFrom list_destinations (tnx:... or partner:...)
data.waybill_numberYour reference / waybill number
data.items[] or data.parcels[]At least one parcel with weight and all dimensions

Example request

{
  "api_token": "tnx_...",
  "action": "create",
  "data": {
    "pickup_location": {
      "contact_name": "John Doe",
      "contact_phone": "+66812345678",
      "address_line1": "123 Sukhumvit Road",
      "city": "Bangkok",
      "postal_code": "10110"
    },
    "destination_selection": "tnx:69a5bdade602b67c968f2ef6",
    "waybill_number": "WB123456789",
    "items": [{
      "description": "Electronics box",
      "quantity": 1,
      "weight_kg": 2.5,
      "length_cm": 30,
      "width_cm": 20,
      "height_cm": 15
    }]
  }
}

list

POST /shipmentCrud

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

Paginated list of your partner account pickup requests. Always set api_scope: pickup.

Auth: api_token + api_scope: pickup

Example request

{
  "api_token": "tnx_...",
  "api_scope": "pickup",
  "action": "list",
  "page": 1,
  "limit": 20
}

get

POST /shipmentCrud

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

Fetch one pickup by pickup_number (preferred) or internal id.

Auth: api_token + api_scope: pickup

Example request

{
  "api_token": "tnx_...",
  "api_scope": "pickup",
  "action": "get",
  "pickup_number": "PU-NWU19Y"
}

cancel

POST /shipmentCrud

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

Cancel an open pickup (pending, requested, or confirmed). reason is required.

Auth: api_token

Example request

{
  "api_token": "tnx_...",
  "action": "cancel",
  "pickup_number": "PU-ABC123",
  "reason": "Customer rescheduled"
}

get_tracking

POST /shipmentCrud

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

Live tracking after staff approval assigns a tracking code.

Auth: api_token

Example request

{
  "api_token": "tnx_...",
  "action": "get_tracking",
  "pickup_number": "PU-ABC123"
}

已儲存的上車地址

針對所有地址的 CRUD 呼叫,請使用 api_scope 地址。建立時參考 pickup_address_id,以重複使用已儲存的地點。

list

POST /shipmentCrud

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

List saved pickup addresses for your partner account.

Example request

{
  "api_token": "tnx_...",
  "api_scope": "address",
  "action": "list",
  "page": 1,
  "limit": 20
}

create

POST /shipmentCrud

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

Create a saved pickup address. City must be in the allowed service area.

Example request

{
  "api_token": "tnx_...",
  "api_scope": "address",
  "action": "create",
  "data": {
    "address_name": "Bangkok Warehouse",
    "contact_name": "John Doe",
    "contact_phone": "+66812345678",
    "address_line1": "456 Warehouse Lane",
    "city": "Bangkok",
    "postal_code": "10110"
  }
}

服務區

僅限在泰國取車。取車城市必須位於允許的服務區域內。

  • Bangkok
  • Hua Hin
  • Pran Buri
  • Cha-am
  • Tha Yang
  • Ban Lat
  • Phetchaburi
  • Khao Yoi
  • Pak Tho
  • Samut Songkhram
  • Samut Sakhon

錯誤

HTTP status codes

FieldDescription
400Validation error (missing field, invalid city, bad destination_selection)
401Missing or invalid api_token
403Token valid but account is not a partner
404Pickup request or address not found
502Tracking app temporarily unavailable (get_tracking)

合作夥伴取餐常見問答

誰可以使用合作夥伴自取 API?
僅限合作夥伴帳戶 (client_type: partner)。標準客戶端權杖接收 HTTP 403 取件 API 僅適用於合作夥伴帳戶。
什麼是合作夥伴自取 API 端點?
所有取貨和已儲存地址的呼叫都使用 POST https://app.thainexus.co.th/functions/shipmentCrud,並採用 Content-Type application/json。當未觸發取貨路線時,同一個端點會處理國際貨運的 CRUD。
如何取得用於建立的 destination_selection?
呼叫 list_destinations 並從 tnx_branches 或 partner_branches 精確複製 destination_selection。請勿自行編造像 tnx:test-branch 這樣的數值。
什麼時候需要 api_scope?
為取貨清單和取得設定 api_scope pickup。為已儲存地址的 CRUD 設定 api_scope address。其他取貨動作會自動導向。