GHTK MCP by usefulapi

List the pickup addresses saved in the shop, with their ids. Use an id as pick_address_id in ghtk_create_order. Token permission: not named in the GHTK docs; the token needs access to this call. Open API: GET /services/shipment/list_pick_add.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Check a delivery address against GHTK's address data (province, district, ward or street). Use it before ghtk_create_order to get the exact spelling GHTK expects. Token permission: not named in the GHTK docs; the token needs access to this call. Open API: GET /services/address/getAddressLevel4.

{
  "type": "object",
  "properties": {
    "province": {
      "type": "string",
      "minLength": 1,
      "description": "Province or city name, for example \"Hà Nội\"."
    },
    "district": {
      "type": "string",
      "minLength": 1,
      "description": "District name, for example \"Ba Đình\"."
    },
    "ward_street": {
      "type": "string",
      "minLength": 1,
      "description": "Ward or street name."
    },
    "address": {
      "description": "Full level-4 address text, for example \"Đội Cấn\".",
      "type": "string"
    }
  },
  "required": [
    "province",
    "district",
    "ward_street"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get the shipping fee and insurance fee for a route and weight, before an order is created. Token permission: Calculate order fees. Open API: GET /services/shipment/fee.

{
  "type": "object",
  "properties": {
    "pick_province": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup province or city."
    },
    "pick_district": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup district."
    },
    "pick_ward": {
      "description": "Pickup ward.",
      "type": "string"
    },
    "pick_address": {
      "description": "Short pickup address.",
      "type": "string"
    },
    "province": {
      "type": "string",
      "minLength": 1,
      "description": "Delivery province or city."
    },
    "district": {
      "type": "string",
      "minLength": 1,
      "description": "Delivery district."
    },
    "ward": {
      "description": "Delivery ward.",
      "type": "string"
    },
    "address": {
      "description": "Delivery address text.",
      "type": "string"
    },
    "weight_grams": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Total weight of all items in grams (not kilograms)."
    },
    "value": {
      "description": "Declared value in VND, the base for the insurance fee.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "transport": {
      "description": "Shipping method: road (by land) or fly (by air). If omitted, GHTK uses its default.",
      "type": "string",
      "enum": [
        "road",
        "fly"
      ]
    }
  },
  "required": [
    "pick_province",
    "pick_district",
    "province",
    "district",
    "weight_grams"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search the shop's product list by name. Returns product codes you can pass as product_code in ghtk_create_order. Token permission: not named in the GHTK docs; the token needs access to this call. Open API: GET /services/kho-hang/thong-tin-san-pham.

{
  "type": "object",
  "properties": {
    "term": {
      "type": "string",
      "minLength": 1,
      "description": "Product name or keyword, for example \"laptop\"."
    }
  },
  "required": [
    "term"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the GHTK solutions (service add-ons) the shop can attach to an order, with their solution_id values. Token permission: not named in the GHTK docs; the token needs access to this call. Open API: GET /open/api/v1/shop/solution/list.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get the status, fees, pickup and delivery dates, and COD amount of one order. Pass the GHTK label (for example S1.A1.17373471) or your own order code. Token permission: Get order status. Open API: GET /services/shipment/v2/{TRACKING_ORDER}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "minLength": 1,
      "description": "The GHTK label or your own order code (order_id sent at creation)."
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Create a real GHTK shipping order: GHTK schedules a pickup and charges the shipping fee. Re-sending the same order_id is refused by GHTK, so it does not create a second order. Give street or hamlet (use "Other" for hamlet when neither applies). Token permission: Create order. Open API: POST /services/shipment/order (JSON).

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "Your own order code. GHTK refuses an order_id it already has."
    },
    "products": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "description": "Product name."
          },
          "weight": {
            "type": "number",
            "exclusiveMinimum": 0,
            "description": "Weight in kilograms."
          },
          "quantity": {
            "description": "Quantity (default 1).",
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "price": {
            "description": "Unit price in VND.",
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "product_code": {
            "description": "Product code from ghtk_search_products, if the product has one.",
            "type": "string"
          }
        },
        "required": [
          "name",
          "weight"
        ]
      },
      "description": "Items in the order. Weights are in kilograms."
    },
    "pick_address_id": {
      "description": "Pickup address id from ghtk_list_pickup_addresses. If set, GHTK uses it before the pickup fields.",
      "type": "string"
    },
    "pick_name": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup contact name."
    },
    "pick_address": {
      "type": "string",
      "minLength": 1,
      "description": "Short pickup address (house number, street)."
    },
    "pick_province": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup province or city."
    },
    "pick_district": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup district."
    },
    "pick_ward": {
      "description": "Pickup ward.",
      "type": "string"
    },
    "pick_tel": {
      "type": "string",
      "minLength": 1,
      "description": "Pickup contact phone number."
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient full name."
    },
    "address": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient detailed address."
    },
    "province": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient province or city."
    },
    "district": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient district."
    },
    "ward": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient ward."
    },
    "street": {
      "description": "Recipient street. Give this or hamlet.",
      "type": "string"
    },
    "hamlet": {
      "description": "Recipient hamlet, village or cluster. Give this or street; \"Other\" if neither applies.",
      "type": "string"
    },
    "tel": {
      "type": "string",
      "minLength": 1,
      "description": "Recipient phone number."
    },
    "email": {
      "description": "Recipient email address.",
      "type": "string"
    },
    "pick_money": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Cash on delivery (COD) amount the courier collects, in VND. 0 = no COD."
    },
    "value": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991,
      "description": "Declared value in VND. The base for the insurance fee and compensation."
    },
    "is_freeship": {
      "description": "1 = recipient pays only the COD amount; 0 = recipient pays COD plus the shipping fee (default 0).",
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        }
      ]
    },
    "transport": {
      "description": "Shipping method: road (by land) or fly (by air). If omitted, GHTK uses its default.",
      "type": "string",
      "enum": [
        "road",
        "fly"
      ]
    },
    "note": {
      "description": "Order note, up to 120 characters.",
      "type": "string",
      "maxLength": 120
    }
  },
  "required": [
    "order_id",
    "products",
    "pick_name",
    "pick_address",
    "pick_province",
    "pick_district",
    "pick_tel",
    "name",
    "address",
    "province",
    "district",
    "ward",
    "tel",
    "pick_money",
    "value"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Cancel an order that GHTK has not picked up yet. GHTK refuses a cancel after pickup. Pass the GHTK label, or set id_type to partner_order_id to pass your own order code. Token permission: not named in the GHTK docs; the token needs access to order cancellation. Open API: POST /services/shipment/cancel/{TRACKING_ORDER}.

{
  "type": "object",
  "properties": {
    "order_id": {
      "type": "string",
      "minLength": 1,
      "description": "The GHTK label (for example S1.A1.17373471) or your own order code."
    },
    "id_type": {
      "description": "What order_id holds: ghtk_label (default) or partner_order_id (your own order code).",
      "type": "string",
      "enum": [
        "ghtk_label",
        "partner_order_id"
      ]
    }
  },
  "required": [
    "order_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}