合作伙伴 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_ token。令牌仅保留在您的浏览器会话中。

取货请求操作

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。其他取货操作会自动路由。