{ "openapi": "3.1.0", "info": { "title": "Metfone Express API", "version": "v1", "description": "Metfone Express TMS Partner API integration for Cambodia: addresses, pricing, shipment creation, labels, cancellation, and journey updates.\nGenerated from published CMS documentation. Examples are illustrative; do not treat example values as operational." }, "servers": [ { "url": "https://dev-gw.metfone.com.kh/tms-partner/api/v1", "description": "Sandbox" }, { "url": "https://gw-express.metfone.com.kh/tms-partner/api/v1", "description": "Production" } ], "paths": { "/administrativedivision/country/{country-code}": { "get": { "operationId": "listProvinces", "summary": "List provinces", "description": "Use `KH` for Cambodia and `LA` for Laos. The result is an array, not a paginated object. Save both `id` and `code`; `code` is the next request’s `location-code`. `status=1` means active. Names may change with `Accept-Language`.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." }, { "name": "country-code", "in": "path", "required": true, "schema": { "type": "string", "description": "ISO country code: KH Cambodia, LA Laos.", "enum": [ "LA", "KH" ] }, "description": "ISO country code: KH Cambodia, LA Laos." } ], "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "array", "description": "All level-1 divisions for the country.", "items": { "type": "object", "description": "Administrative division.", "properties": { "id": { "type": "number", "description": "Internal location ID." }, "level": { "type": "number", "description": "Administrative level: 1 province, 2 district, 3 village." }, "status": { "type": "number", "description": "1 means active." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "countrycode": { "type": "string", "description": "Country code." }, "name": { "type": "string", "description": "Localized location name." }, "type": { "type": "string", "description": "PROVINCE, DISTRICT or VILLAGE." }, "short_name": { "type": "string", "description": "Short name." }, "parent_code": { "type": "string", "description": "Parent location code; generally country code at level 1." }, "refs": { "type": "array", "description": "References to other systems.", "items": { "type": "object", "description": "External reference.", "properties": { "sys": { "type": "string", "description": "Reference system, e.g. VTP or POSTCODE." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." } } } } } } }, "example": [ { "id": 4025109, "level": 1, "status": 1, "code": "BAN", "countrycode": "KH", "name": "Banteay Meanchey", "type": "PROVINCE", "short_name": "Banteay Meanchey", "parent_code": "KH", "refs": [ { "sys": "VTP", "code": "BAN" }, { "sys": "POSTCODE", "code": "01" } ] } ] } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/administrativedivision/country/{country-code}/{level}/{location-code}": { "get": { "operationId": "listAdministrativeChildren", "summary": "List districts and villages", "description": "For districts, request `/administrativedivision/country/KH/2/BAN`. For villages, use the district code: `/administrativedivision/country/KH/3/0102`. A district example uses `Accept-Language: km`. Store returned IDs/codes for address components in pricing and order creation. All response fields are the same as the province endpoint.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." }, { "name": "country-code", "in": "path", "required": true, "schema": { "type": "string", "description": "ISO country code: KH Cambodia, LA Laos.", "enum": [ "LA", "KH" ] }, "description": "ISO country code: KH Cambodia, LA Laos." }, { "name": "level", "in": "path", "required": true, "schema": { "type": "integer", "description": "Requested child level: 2 districts or 3 villages.", "enum": [ 2, 3 ] }, "description": "Requested child level: 2 districts or 3 villages." }, { "name": "location-code", "in": "path", "required": true, "schema": { "type": "string", "description": "Parent code: province BAN for level 2, district 0102 for level 3." }, "description": "Parent code: province BAN for level 2, district 0102 for level 3." }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "description": "Partial name match (LIKE) at every level of this endpoint." }, "description": "Partial name match (LIKE) at every level of this endpoint." } ], "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "array", "description": "Child divisions.", "items": { "type": "object", "description": "Administrative division.", "properties": { "id": { "type": "number", "description": "Internal location ID." }, "level": { "type": "number", "description": "Administrative level: 1 province, 2 district, 3 village." }, "status": { "type": "number", "description": "1 means active." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "countrycode": { "type": "string", "description": "Country code." }, "name": { "type": "string", "description": "Localized location name." }, "type": { "type": "string", "description": "PROVINCE, DISTRICT or VILLAGE." }, "short_name": { "type": "string", "description": "Short name." }, "parent_code": { "type": "string", "description": "Parent location code; generally country code at level 1." }, "refs": { "type": "array", "description": "References to other systems.", "items": { "type": "object", "description": "External reference.", "properties": { "sys": { "type": "string", "description": "Reference system, e.g. VTP or POSTCODE." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." } } } } } } }, "example": [ { "id": 4059452, "level": 2, "status": 1, "code": "0102", "countrycode": "KH", "name": "មង្គលបូរី", "type": "DISTRICT", "short_name": "មង្គលបូរី", "parent_code": "BAN", "refs": [ { "sys": "VTP", "code": "0102" } ] } ] } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/department/posts": { "get": { "operationId": "searchPostOffices", "summary": "Find post offices", "description": "All query parameters are optional. `query` searches name, address, or phone; `codeLocation` filters by a province, district, or village. `departmentCode` targets one branch. Use `total` for pagination rather than the current `items.length`.\n\nProvide **both** `latDest` and `longDest` to get a meaningful `distance` in kilometers and nearest-first sorting. Without them, do not assume `distance` has a useful value.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string", "description": "Search branch name/address/phone." }, "description": "Search branch name/address/phone." }, { "name": "codeLocation", "in": "query", "required": false, "schema": { "type": "string", "description": "Province/district/village code, e.g. BAN." }, "description": "Province/district/village code, e.g. BAN." }, { "name": "departmentCode", "in": "query", "required": false, "schema": { "type": "string", "description": "Specific branch code, e.g. KOH01." }, "description": "Specific branch code, e.g. KOH01." }, { "name": "latDest", "in": "query", "required": false, "schema": { "type": "number", "description": "Destination latitude; send with longDest to obtain distance and nearest-first ordering." }, "description": "Destination latitude; send with longDest to obtain distance and nearest-first ordering." }, { "name": "longDest", "in": "query", "required": false, "schema": { "type": "number", "description": "Destination longitude used with latDest." }, "description": "Destination longitude used with latDest." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "Page size, default 20.", "default": 20 }, "description": "Page size, default 20." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "description": "Pagination offset, default 0.", "default": 0 }, "description": "Pagination offset, default 0." } ], "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "Paginated branches.", "properties": { "items": { "type": "array", "description": "Current page.", "items": { "type": "object", "description": "Matching branch.", "properties": { "department_id": { "type": "number", "description": "Internal branch ID." }, "type": { "type": "string", "description": "Example: POST." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "phone": { "type": "string", "description": "Branch phone." }, "name": { "type": "string", "description": "Branch name." }, "department_code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "country_code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "province_code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "district_code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "ward_code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "home": { "type": "string", "description": "Local address text." }, "address": { "type": "string", "description": "Full branch address." }, "latitude": { "type": "number", "description": "Branch latitude." }, "longitude": { "type": "number", "description": "Branch longitude." }, "distance": { "type": "number", "description": "Distance in km, meaningful only when latDest/longDest are supplied." }, "address_component": { "type": "object", "description": "Branch address components.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } } } } } }, "total": { "type": "number", "description": "Total matches for pagination." } } }, "example": { "items": [ { "department_id": 900001, "type": "POST", "code": "EXAMPLE-POST", "phone": "${POST_OFFICE_PHONE}", "name": "Example post office", "department_code": "EXAMPLE-POST", "country_code": "KH", "province_code": "BAN", "district_code": "0102", "ward_code": "010201", "home": "Example branch", "address": "Example branch, Cambodia", "latitude": 11.2, "longitude": 103.4, "distance": 3.2, "address_component": { "components": [ { "name": "Example recipient, Street B", "type": "OTHER", "level": 999 }, { "id": "5025109", "code": "010201", "name": "បន្ទាយនាង", "type": "VILLAGE", "level": 3 }, { "id": "4059452", "code": "0102", "name": "មង្គលបូរី", "type": "DISTRICT", "level": 2 }, { "id": "4025109", "code": "BAN", "name": "Banteay Meanchey", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ] } } ], "total": 1 } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/pricing/get-service": { "post": { "operationId": "getAvailableServices", "summary": "Discover available services", "description": "Call this before get-all and create-order. Supply a complete product and route. Missing `fromLocation`, `toLocation`, or `product` can produce HTTP 500 instead of a clean HTTP 400.\n\nSend weight in grams and dimensions in centimeters. `isDomestic` defaults to true. `customerCode` defaults to the token’s customer account. `partnerInfo` is an alternate discount identity and is normally unnecessary because `X-Client-Source` already identifies the partner. `orderService` changes the `isShow`, `isChosen`, and `isChangeable` flags of GTN/NTN/VTT; it does not change the price.\n\nMap `mainPrice.code` to order `service`, and selected `extraPrices[].code` to `vas[]`. Respect automatically included `mainPrice.extraService[]` and `specialService[]`. `isShow=false` marks an internal service, not a selectable requirement. `isCalculated=false` means displayed rather than priced. If `mainPrice.isCalculatedAutomatically=false`, use `manualPrice` when calling get-all. Use **beforeVatPrice**, not VAT-inclusive `price`, for order fee amounts.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Recommended operational inputs; no fields have @NotNull validation. Missing locations/product may cause 500 rather than 400.", "properties": { "product": { "type": "object", "description": "Recommended product object. No @NotNull validation is documented for pricing.", "properties": { "weight": { "type": "number", "description": "Recommended weight in grams." }, "type": { "type": "string", "description": "Recommended goods type.", "enum": [ "GOODS", "DOCUMENT" ] }, "price": { "type": "number", "description": "Declared goods value; currency is not specified for this request in the source." }, "moneyCollection": { "type": "number", "description": "COD influences service selection only; it does not change the quoted amount or persist COD on an order." }, "length": { "type": "number", "description": "Length in cm." }, "width": { "type": "number", "description": "Width in cm." }, "height": { "type": "number", "description": "Height in cm." } } }, "fromLocation": { "type": "array", "description": "Recommended sender components, levels 0–3 and 999.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "toLocation": { "type": "array", "description": "Recommended recipient components, levels 0–3.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "isDomestic": { "type": "boolean", "description": "Domestic=true, international=false. Defaults to true.", "default": true }, "customerCode": { "type": "string", "description": "Internal customer code; defaults to the account associated with X-Api-Token." }, "partnerInfo": { "type": "object", "description": "Optional discount identity; X-Client-Source normally suffices. Uses snake_case.", "properties": { "id": { "type": "number", "description": "Internal partner ID." }, "partner_code": { "type": "string", "description": "Partner code." }, "partner_name": { "type": "string", "description": "Partner name." }, "email": { "type": "string", "description": "Partner email." }, "type": { "type": "string", "description": "Partner type, e.g. PARTNER." } } }, "orderService": { "type": "object", "description": "Service preferences; UNKNOW is the source spelling.", "properties": { "senderService": { "type": "string", "description": "Changes display/default/lock flags of GTN/NTN/VTT, not price.", "enum": [ "GTCH", "VTT", "GTN", "UNKNOW" ] }, "receiverService": { "type": "string", "description": "Recipient preference with the same flag-only effect.", "enum": [ "NTCH", "NTN", "VTT", "UNKNOW" ] } } } } }, "example": { "product": { "weight": 100, "type": "GOODS", "price": 50, "moneyCollection": 50, "length": 10, "width": 10, "height": 10 }, "fromLocation": [ { "name": "Example warehouse, Street A", "type": "OTHER", "level": 999 }, { "id": "5025963", "code": "120211", "name": "Voat Phnum", "type": "VILLAGE", "level": 3 }, { "id": "4059553", "code": "1202", "name": "Doun Penh", "type": "DISTRICT", "level": 2 }, { "id": "4025120", "code": "PNP", "name": "Phnom Penh", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "toLocation": [ { "name": "Example recipient, Street B", "type": "OTHER", "level": 999 }, { "id": "5025109", "code": "010201", "name": "បន្ទាយនាង", "type": "VILLAGE", "level": 3 }, { "id": "4059452", "code": "0102", "name": "មង្គលបូរី", "type": "DISTRICT", "level": 2 }, { "id": "4025109", "code": "BAN", "name": "Banteay Meanchey", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "isDomestic": true, "orderService": { "senderService": "GTN", "receiverService": "NTN" } } } } }, "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "array", "description": "Available service choices.", "items": { "type": "object", "description": "Available service and its price breakdown.", "properties": { "totalPrice": { "type": "number", "description": "Total before the reported discount." }, "totalPriceAfterDiscount": { "type": "number", "description": "Total after discount; difference is totalDiscountAmount." }, "property": { "type": "object", "description": "Calculation inputs returned by pricing.", "properties": { "calculatedWeight": { "type": "number", "description": "Actual weight used for pricing, grams." }, "convertedWeight": { "type": "number", "description": "Volumetric weight, grams." }, "perimeter": { "type": "number", "description": "Parcel perimeter." }, "distance": { "type": [ "number", "null" ], "description": "Distance when a distance-based service applies; otherwise null." } } }, "mainPrice": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } }, "extraPrices": { "type": "array", "description": "Extra-service prices.", "items": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } } }, "specialPrices": { "type": "array", "description": "Special-service prices.", "items": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } } }, "discount": { "type": "number", "description": "Discount value." }, "totalDiscountAmount": { "type": "number", "description": "Total discount amount." }, "discountType": { "type": "string", "description": "AMOUNT: fixed amount; PERCENT: percentage.", "enum": [ "AMOUNT", "PERCENT" ] }, "leadTime": { "type": "number", "description": "Lead-time value shown in the source; unit is unspecified." } } } }, "example": [ { "totalPrice": 20000, "totalPriceAfterDiscount": 18000, "discount": 2000, "totalDiscountAmount": 2000, "discountType": "AMOUNT", "property": { "calculatedWeight": 100, "convertedWeight": 200, "perimeter": 30, "distance": null }, "mainPrice": { "code": "CCN", "name": "Express", "price": 8000, "priceAfterDiscount": 6000, "discount": 2000, "beforeVatPrice": 7273, "vatPrice": 727, "field": "KL", "calculatedWeight": 100, "extraService": [ "GTN" ], "specialService": [], "isCalculatedAutomatically": true }, "extraPrices": [ { "code": "GTN", "name": "Delivery to address", "price": 8000, "beforeVatPrice": 7273, "vatPrice": 727, "priceAfterDiscount": 8000, "discount": 0, "field": "CC", "isShow": true, "isChosen": false, "isChangeable": true, "isCalculated": true }, { "code": "NTN", "name": "Pickup at address", "price": 2000, "beforeVatPrice": 1818, "vatPrice": 182, "priceAfterDiscount": 2000, "discount": 0, "field": "CC", "isShow": true, "isChosen": false, "isChangeable": true, "isCalculated": true } ], "specialPrices": [], "leadTime": 0 } ] } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/pricing/get-all": { "post": { "operationId": "calculatePricing", "summary": "Calculate shipping prices", "description": "Call get-service first to obtain appropriate `mainService`, `extraService`, and `specialService`. Send the route and product to avoid missing-input runtime failures. `manualPrice` applies only when the chosen service is not calculated automatically; `customerCode` and `partnerInfo` follow the service-discovery rules.\n\n**COD does not change the quoted amount.** At this step and at get-service, `product.moneyCollection` only selects service rules for COD greater than zero versus zero in Drools. It does not change `totalPrice`, `mainPrice`, or `extraPrices`, and does not persist COD on an order. You must resend top-level `moneyCollection` in create-order.\n\n`totalPrice` is the final VAT-inclusive amount after discounts. `totalPriceBeforeDiscount` is before discounts. `vat` is a percentage; `vatPrice` is the tax amount; `beforeVatPrice` excludes tax. The response exposes `round`/`roundNum`, the applied rounding rule and precision. `manualPrice` echoes the manual input or is null. `discountType=AMOUNT` means a fixed amount, `PERCENT` means a percentage.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Quote known services. Source table omits orderService but appendix explicitly references section 6; confirm its acceptance.", "properties": { "product": { "type": "object", "description": "Recommended product object. No @NotNull validation is documented for pricing.", "properties": { "weight": { "type": "number", "description": "Recommended weight in grams." }, "type": { "type": "string", "description": "Recommended goods type.", "enum": [ "GOODS", "DOCUMENT" ] }, "price": { "type": "number", "description": "Declared goods value; currency is not specified for this request in the source." }, "moneyCollection": { "type": "number", "description": "COD influences service selection only; it does not change the quoted amount or persist COD on an order." }, "length": { "type": "number", "description": "Length in cm." }, "width": { "type": "number", "description": "Width in cm." }, "height": { "type": "number", "description": "Height in cm." } } }, "fromLocation": { "type": "array", "description": "Recommended sender components, levels 0–3 and 999.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "toLocation": { "type": "array", "description": "Recommended recipient components, levels 0–3.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "isDomestic": { "type": "boolean", "description": "Domestic=true, international=false. Defaults to true.", "default": true }, "customerCode": { "type": "string", "description": "Internal customer code; defaults to the account associated with X-Api-Token." }, "partnerInfo": { "type": "object", "description": "Optional discount identity; X-Client-Source normally suffices. Uses snake_case.", "properties": { "id": { "type": "number", "description": "Internal partner ID." }, "partner_code": { "type": "string", "description": "Partner code." }, "partner_name": { "type": "string", "description": "Partner name." }, "email": { "type": "string", "description": "Partner email." }, "type": { "type": "string", "description": "Partner type, e.g. PARTNER." } } }, "mainService": { "type": "string", "description": "Recommended main service code from get-service, e.g. CCN." }, "extraService": { "type": "array", "description": "Optional extra-service codes.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Optional special-service codes, usually empty.", "items": { "type": "string", "description": "Service code." } }, "manualPrice": { "type": "number", "description": "Self-declared price when mainPrice.isCalculatedAutomatically=false; ignored for automatic services." }, "orderService": { "type": "object", "description": "Service preferences; UNKNOW is the source spelling.", "properties": { "senderService": { "type": "string", "description": "Changes display/default/lock flags of GTN/NTN/VTT, not price.", "enum": [ "GTCH", "VTT", "GTN", "UNKNOW" ] }, "receiverService": { "type": "string", "description": "Recipient preference with the same flag-only effect.", "enum": [ "NTCH", "NTN", "VTT", "UNKNOW" ] } } } } }, "example": { "product": { "weight": 100, "type": "GOODS", "price": 50, "moneyCollection": 50, "length": 10, "width": 10, "height": 10 }, "fromLocation": [ { "name": "Example warehouse, Street A", "type": "OTHER", "level": 999 }, { "id": "5025963", "code": "120211", "name": "Voat Phnum", "type": "VILLAGE", "level": 3 }, { "id": "4059553", "code": "1202", "name": "Doun Penh", "type": "DISTRICT", "level": 2 }, { "id": "4025120", "code": "PNP", "name": "Phnom Penh", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "toLocation": [ { "name": "Example recipient, Street B", "type": "OTHER", "level": 999 }, { "id": "5025109", "code": "010201", "name": "បន្ទាយនាង", "type": "VILLAGE", "level": 3 }, { "id": "4059452", "code": "0102", "name": "មង្គលបូរី", "type": "DISTRICT", "level": 2 }, { "id": "4025109", "code": "BAN", "name": "Banteay Meanchey", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "isDomestic": true, "mainService": "CCN", "extraService": [], "specialService": [] } } } }, "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "Final quote. Do not recompute source-example totals as a tariff specification.", "properties": { "totalPrice": { "type": "number", "description": "Final total after discounts, including VAT." }, "totalPriceBeforeDiscount": { "type": "number", "description": "Total before discounts." }, "vat": { "type": "number", "description": "VAT rate, percent." }, "vatPrice": { "type": "number", "description": "Total VAT amount." }, "beforeVatPrice": { "type": "number", "description": "Total excluding VAT." }, "manualPrice": { "type": [ "number", "null" ], "description": "Echoed manual price, null if omitted/not applicable." }, "round": { "type": "string", "description": "Applied rounding rule; NONE appears in the example. Full enum not supplied." }, "roundNum": { "type": "number", "description": "Rounding precision." }, "property": { "type": "object", "description": "Calculation inputs returned by pricing.", "properties": { "calculatedWeight": { "type": "number", "description": "Actual weight used for pricing, grams." }, "convertedWeight": { "type": "number", "description": "Volumetric weight, grams." }, "perimeter": { "type": "number", "description": "Parcel perimeter." }, "distance": { "type": [ "number", "null" ], "description": "Distance when a distance-based service applies; otherwise null." } } }, "mainPrice": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } }, "extraPrices": { "type": "array", "description": "Extra-service prices.", "items": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } } }, "specialPrices": { "type": "array", "description": "Special-service prices.", "items": { "type": "object", "description": "Fields depend on whether this is mainPrice or an extra/special price.", "properties": { "code": { "type": "string", "description": "Service code; mainPrice.code becomes order.service; extraPrices[].code becomes order.vas[]." }, "name": { "type": "string", "description": "Service name." }, "price": { "type": "number", "description": "Listed service price; extra service list prices include VAT." }, "priceAfterDiscount": { "type": "number", "description": "Service amount after discount." }, "discount": { "type": "number", "description": "Service-specific discount amount." }, "beforeVatPrice": { "type": "number", "description": "Pre-VAT fee to map to detailedFees.serviceFee[].fee." }, "vatPrice": { "type": "number", "description": "VAT amount." }, "field": { "type": "string", "description": "Calculation classification: KL/TH/CC/KG/KC/CV/CV_KL." }, "calculatedWeight": { "type": "number", "description": "Weight used by the main service." }, "extraService": { "type": "array", "description": "Automatically included extra services.", "items": { "type": "string", "description": "Service code." } }, "specialService": { "type": "array", "description": "Automatically included special services.", "items": { "type": "string", "description": "Service code." } }, "isCalculatedAutomatically": { "type": "boolean", "description": "true: automatic Drools calculation; false: provide manualPrice to get-all." }, "isShow": { "type": "boolean", "description": "Extra service visible for selection; false means internal and need not be submitted." }, "isChosen": { "type": "boolean", "description": "Extra service selected by default." }, "isChangeable": { "type": "boolean", "description": "Whether the user may toggle the extra service; otherwise locked by orderService." }, "isCalculated": { "type": "boolean", "description": "Whether the extra service is priced or only displayed." } } } }, "discount": { "type": "number", "description": "Discount value." }, "totalDiscountAmount": { "type": "number", "description": "Total discount amount." }, "discountType": { "type": "string", "description": "AMOUNT: fixed amount; PERCENT: percentage.", "enum": [ "AMOUNT", "PERCENT" ] } } }, "example": { "totalPrice": 1.75, "totalPriceBeforeDiscount": 1.75, "vat": 10, "vatPrice": 0.16, "beforeVatPrice": 1.59, "manualPrice": null, "round": "NONE", "roundNum": 0, "property": { "calculatedWeight": 100, "convertedWeight": 200, "perimeter": 30, "distance": null }, "mainPrice": { "code": "CCN", "name": "Express", "price": 1.59, "priceAfterDiscount": 1.59, "discount": 0, "beforeVatPrice": 1.44, "vatPrice": 0.14, "field": "KL", "calculatedWeight": 100, "extraService": [], "specialService": [], "isCalculatedAutomatically": true }, "extraPrices": [], "specialPrices": [], "discount": 0, "totalDiscountAmount": 0, "discountType": "AMOUNT" } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/order": { "post": { "operationId": "createOrder", "summary": "Create an order", "description": "Send top-level `moneyCollection` on this request. Pricing and creation are independent. If it is absent or null, the recorded response `cod` becomes 0 even if the quote included COD. Negative COD produces `INVALID_PRICE`. Do not send the obsolete request field `cod`: it is not read. Compare the returned `cod` against your intended collection amount.\n\nProvide sender and recipient names, international-format phones, and addresses. The source describes `seller` as the fallback when shipper is empty, `buyer` when consignee is empty, and `returnContact` defaulting to shipper. Each parcel needs weight/weightUnit, dimensions, type, and at least one item with a name and positive weight. `measurementUnit` defaults to the literal `CENTIMET`. Only `payerType=CONSIGNEE` or `SELLER` is accepted; other values produce `PAYER_INVALID`.\n\n`vas` containing GTN/NTN/VTT may override the submitted `receiveType`. `deliveryPostcode` is required unless `vas` contains GTN or VTT; with GTN it is forced to null. Source names and sender/receiver service labels are retained rather than reinterpreted.\n\n`txId` supports partner-side reconciliation/deduplication; the source does **not** establish server-enforced idempotency, a deduplication window, or safe repeat-create behavior. Retain the initial response and reconcile an ambiguous timeout before submitting another create. Do not assume a repeated txId prevents a duplicate shipment.\n\n**Response:** save `id` for label creation, status lookup, and cancellation. Creation uses textual `status=CONFIRMED` and `statusName`; status lookup/webhooks use numeric codes. `totalFees` includes VAT after discounts and `totalTax` is VAT. `estDeliveryTime.date` is DD/MM/YYYY. `partnerInfo` uses snake_case keys inside an otherwise camelCase order response. Addresses are reduced to `components` and `formattedAddress`; no address-level id/code/geometry or component typeName/typeLabel is echoed.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Provide sender/recipient or documented seller/buyer fallback. Requiredness describes source business requirements, not guaranteed validation responses.", "properties": { "receiveType": { "type": "string", "description": "AT_HOME or AT_STORE; GTN/NTN/VTT in vas can cause recalculation and override.", "enum": [ "AT_HOME", "AT_STORE" ] }, "shipper": { "type": "object", "description": "ContactInfo. Sender and recipient need name, phone and address, subject to seller/buyer fallback.", "properties": { "name": { "type": "string", "description": "Contact name. Examples use synthetic people." }, "phone": { "type": "string", "description": "International format, e.g. Cambodia +855; replace the environment placeholder." }, "type": { "type": "string", "description": "Examples: PARTNER_WAREHOUSE, PERSON, HOME, OFFICE; complete enum not supplied." }, "postOffice": { "type": "string", "description": "Post-office code for drop-off at a branch." }, "address": { "type": "object", "description": "Address supplied by the partner.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } }, "required": [ "components" ] } } }, "consignee": { "type": "object", "description": "ContactInfo. Sender and recipient need name, phone and address, subject to seller/buyer fallback.", "properties": { "name": { "type": "string", "description": "Contact name. Examples use synthetic people." }, "phone": { "type": "string", "description": "International format, e.g. Cambodia +855; replace the environment placeholder." }, "type": { "type": "string", "description": "Examples: PARTNER_WAREHOUSE, PERSON, HOME, OFFICE; complete enum not supplied." }, "postOffice": { "type": "string", "description": "Post-office code for drop-off at a branch." }, "address": { "type": "object", "description": "Address supplied by the partner.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } }, "required": [ "components" ] } } }, "seller": { "type": "object", "description": "Optional seller, used if shipper is empty.", "properties": { "name": { "type": "string", "description": "Contact name. Examples use synthetic people." }, "phone": { "type": "string", "description": "International format, e.g. Cambodia +855; replace the environment placeholder." }, "type": { "type": "string", "description": "Examples: PARTNER_WAREHOUSE, PERSON, HOME, OFFICE; complete enum not supplied." }, "postOffice": { "type": "string", "description": "Post-office code for drop-off at a branch." }, "address": { "type": "object", "description": "Address supplied by the partner.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } }, "required": [ "components" ] } } }, "buyer": { "type": "object", "description": "Optional buyer, used if consignee is empty.", "properties": { "name": { "type": "string", "description": "Contact name. Examples use synthetic people." }, "phone": { "type": "string", "description": "International format, e.g. Cambodia +855; replace the environment placeholder." }, "type": { "type": "string", "description": "Examples: PARTNER_WAREHOUSE, PERSON, HOME, OFFICE; complete enum not supplied." }, "postOffice": { "type": "string", "description": "Post-office code for drop-off at a branch." }, "address": { "type": "object", "description": "Address supplied by the partner.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } }, "required": [ "components" ] } } }, "returnContact": { "type": "object", "description": "Return contact; defaults to shipper.", "properties": { "name": { "type": "string", "description": "Contact name. Examples use synthetic people." }, "phone": { "type": "string", "description": "International format, e.g. Cambodia +855; replace the environment placeholder." }, "type": { "type": "string", "description": "Examples: PARTNER_WAREHOUSE, PERSON, HOME, OFFICE; complete enum not supplied." }, "postOffice": { "type": "string", "description": "Post-office code for drop-off at a branch." }, "address": { "type": "object", "description": "Address supplied by the partner.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } } }, "required": [ "components" ] } } }, "parcel": { "type": "object", "description": "Parcel dimensions and goods.", "properties": { "weight": { "type": "number", "description": "Parcel weight." }, "weightUnit": { "type": "string", "description": "Weight unit documented as GRAM." }, "length": { "type": "number", "description": "Length, cm." }, "width": { "type": "number", "description": "Width, cm." }, "height": { "type": "number", "description": "Height, cm." }, "measurementUnit": { "type": "string", "description": "Defaults to CENTIMET (source spelling).", "default": "CENTIMET" }, "type": { "type": "string", "description": "Parcel type.", "enum": [ "GOODS", "DOCUMENT" ] }, "items": { "type": "array", "description": "At least one item.", "items": { "type": "object", "description": "At least name and positive weight are needed.", "properties": { "name": { "type": "string", "description": "Item name." }, "type": { "type": "string", "description": "Item type shown in the example." }, "value": { "type": "number", "description": "Declared item value." }, "weight": { "type": "number", "description": "Item weight; must be greater than zero.", "exclusiveMinimum": 0 }, "quantity": { "type": "number", "description": "Item quantity." } }, "required": [ "name", "weight" ] }, "minItems": 1 } }, "required": [ "weight", "weightUnit", "length", "width", "height", "type", "items" ] }, "payerType": { "type": "string", "description": "Only CONSIGNEE and SELLER accepted; otherwise PAYER_INVALID.", "enum": [ "CONSIGNEE", "SELLER" ] }, "service": { "type": "string", "description": "Main service code from get-service." }, "vas": { "type": "array", "description": "Extra service codes selected from available services.", "items": { "type": "string", "description": "Service code." } }, "moneyCollection": { "type": "number", "description": "COD must be resent here. Omitted/null becomes cod=0. Negative values produce INVALID_PRICE.", "minimum": 0 }, "detailedFees": { "type": "object", "description": "Use the results returned by get-all.", "properties": { "serviceFee": { "type": "array", "description": "Recommended pricing details.", "items": { "type": "object", "description": "Invalid surchargeType rows are silently ignored.", "properties": { "service": { "type": "string", "description": "Service code from pricing." }, "name": { "type": "string", "description": "Service name shown in the example." }, "fee": { "type": "number", "description": "Use main/extra beforeVatPrice, not VAT-inclusive price." }, "surchargeType": { "type": "string", "description": "Only valid values are retained, but the source does not list those values. Ask TMS." }, "type": { "type": "string", "description": "Source example says VAS, conflicting with the prose surchargeType field. Not a confirmed substitute." } } } } } }, "voucher": { "type": "string", "description": "Voucher code." }, "reference": { "type": "string", "description": "Partner internal reference." }, "pickupAppointment": { "type": "object", "description": "Optional appointment. Confirm day/time encoding before use.", "properties": { "dayOfWeek": { "type": "array", "description": "Days of week; item encoding not specified by the source.", "items": {} }, "hours": { "type": "array", "description": "Time slots; item encoding not specified by the source.", "items": {} }, "note": { "type": "string", "description": "Appointment note." } } }, "deliveryAppointment": { "type": "object", "description": "Optional appointment. Confirm day/time encoding before use.", "properties": { "dayOfWeek": { "type": "array", "description": "Days of week; item encoding not specified by the source.", "items": {} }, "hours": { "type": "array", "description": "Time slots; item encoding not specified by the source.", "items": {} }, "note": { "type": "string", "description": "Appointment note." } } }, "note": { "type": "string", "description": "Order note." }, "invoice": { "type": "string", "description": "Invoice requested from sender or receiver.", "enum": [ "NONE", "BY_SENDER", "BY_RECEIVER" ], "default": "NONE" }, "orderScope": { "type": "string", "description": "Order scope.", "enum": [ "DOMESTIC", "INTERNATIONAL" ], "default": "DOMESTIC" }, "deliveryPostcode": { "type": "string", "description": "Required unless vas contains GTN or VTT. GTN forces this field to null." }, "txId": { "type": "string", "description": "Partner transaction ID for reconciliation/client-side deduplication. Server idempotency is NOT established." } }, "required": [ "parcel", "payerType", "service" ] }, "example": { "receiveType": "AT_HOME", "shipper": { "name": "Example Warehouse", "phone": "${SHIPPER_PHONE}", "type": "PARTNER_WAREHOUSE", "address": { "components": [ { "name": "Example warehouse, Street A", "type": "OTHER", "level": 999 }, { "id": "5025963", "code": "120211", "name": "Voat Phnum", "type": "VILLAGE", "level": 3 }, { "id": "4059553", "code": "1202", "name": "Doun Penh", "type": "DISTRICT", "level": 2 }, { "id": "4025120", "code": "PNP", "name": "Phnom Penh", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ] } }, "consignee": { "name": "Example Recipient", "phone": "${CONSIGNEE_PHONE}", "address": { "components": [ { "name": "Example recipient, Street B", "type": "OTHER", "level": 999 }, { "id": "5025109", "code": "010201", "name": "បន្ទាយនាង", "type": "VILLAGE", "level": 3 }, { "id": "4059452", "code": "0102", "name": "មង្គលបូរី", "type": "DISTRICT", "level": 2 }, { "id": "4025109", "code": "BAN", "name": "Banteay Meanchey", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ] } }, "parcel": { "weight": 100, "weightUnit": "GRAM", "length": 10, "width": 10, "height": 10, "measurementUnit": "CENTIMET", "type": "GOODS", "items": [ { "name": "Example product", "type": "GOODS", "value": 50, "weight": 10, "quantity": 8 } ] }, "payerType": "CONSIGNEE", "service": "CCN", "vas": [ "NTN", "VTT" ], "moneyCollection": 50, "invoice": "NONE", "reference": "EXAMPLE-REFERENCE-001", "txId": "00000000-0000-4000-8000-000000000001", "note": "" } } } }, "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "Selected useful fields, not an exhaustive order schema. Other price/postman/cancel/contact fields may be returned.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "status": { "type": "string", "description": "Creation example uses CONFIRMED, unlike numeric lookup/webhook status." }, "statusName": { "type": "string", "description": "Creation status label: awaiting acceptance." }, "service": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "serviceName": { "type": "string", "description": "Main service name." }, "orderScope": { "type": "string", "description": "Order scope." }, "shipper": { "type": "object", "description": "Sender snapshot.", "properties": { "name": { "type": "string", "description": "Sender name." }, "phone": { "type": "string", "description": "Sender phone when returned." }, "address": { "type": "object", "description": "Simplified response address; components do not echo typeName/typeLabel.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "formattedAddress": { "type": "string", "description": "Formatted address; no address-level id, code or geometry." } } } } }, "consignee": { "type": "object", "description": "Recipient snapshot.", "properties": { "name": { "type": "string", "description": "Recipient name." }, "phone": { "type": "string", "description": "Recipient phone." }, "address": { "type": "object", "description": "Simplified response address; components do not echo typeName/typeLabel.", "properties": { "components": { "type": "array", "description": "Use current administrative API IDs and codes.", "items": { "type": "object", "description": "Address component. Order addresses require levels 1, 2 and 3; 0 and 999 are optional.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "code": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "name": { "type": "string", "description": "Location name or street address." }, "type": { "type": "string", "description": "NATIONAL, PROVINCE, DISTRICT, VILLAGE or OTHER according to level." }, "level": { "type": "number", "description": "0 country; 1 province; 2 district; 3 village; 999 street/detail." } } } }, "formattedAddress": { "type": "string", "description": "Formatted address; no address-level id, code or geometry." } } } } }, "parcel": { "type": "object", "description": "Returned parcel may be partial; request requiredness is not a response guarantee.", "properties": { "weight": { "type": "number", "description": "Parcel weight." }, "weightUnit": { "type": "string", "description": "Weight unit documented as GRAM." }, "length": { "type": "number", "description": "Length, cm." }, "width": { "type": "number", "description": "Width, cm." }, "height": { "type": "number", "description": "Height, cm." }, "measurementUnit": { "type": "string", "description": "Defaults to CENTIMET (source spelling).", "default": "CENTIMET" }, "type": { "type": "string", "description": "Parcel type.", "enum": [ "GOODS", "DOCUMENT" ] }, "items": { "type": "array", "description": "Returned goods items.", "items": { "type": "object", "description": "Returned item fields; requiredness is not specified.", "properties": { "name": { "type": "string", "description": "Item name." }, "type": { "type": "string", "description": "Item type shown in the example." }, "value": { "type": "number", "description": "Declared item value." }, "weight": { "type": "number", "description": "Item weight; must be greater than zero.", "exclusiveMinimum": 0 }, "quantity": { "type": "number", "description": "Item quantity." } } } } } }, "cod": { "type": "number", "description": "Persisted COD; compare with request.moneyCollection." }, "totalFees": { "type": "number", "description": "Total fees after discounts including VAT." }, "totalTax": { "type": "number", "description": "Total VAT." }, "originalPrice": { "type": "number", "description": "Original price shown in the source example; calculation not specified." }, "detailedFees": { "type": "object", "description": "Recorded detailed fees.", "properties": { "currency": { "type": "string", "description": "Example uses USD; do not assume every pricing response uses this currency." }, "serviceFee": { "type": "array", "description": "Recorded fees.", "items": { "type": "object", "description": "Recorded fee line.", "properties": { "service": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "fee": { "type": "number", "description": "Pre-VAT fee." }, "feeAfterVat": { "type": "number", "description": "Fee after VAT." }, "vatPrice": { "type": "number", "description": "VAT amount." } } } } } }, "payerType": { "type": "string", "description": "Payer." }, "vas": { "type": "array", "description": "Extra services.", "items": { "type": "string", "description": "Service code." } }, "estDeliveryTime": { "type": "object", "description": "Delivery estimate.", "properties": { "days": { "type": "number", "description": "Estimated day count." }, "date": { "type": "string", "description": "Estimated delivery date, DD/MM/YYYY." } } }, "createdAt": { "type": "string", "description": "Creation timestamp.", "format": "date-time" }, "txId": { "type": "string", "description": "Transaction identifier derived from supplied txId or generated by the system; no server deduplication guarantee." }, "invoice": { "type": "string", "description": "Invoice mode." }, "receiveType": { "type": "string", "description": "Resolved receive type." }, "partnerInfo": { "type": "object", "description": "Optional discount identity; X-Client-Source normally suffices. Uses snake_case.", "properties": { "id": { "type": "number", "description": "Internal partner ID." }, "partner_code": { "type": "string", "description": "Partner code." }, "partner_name": { "type": "string", "description": "Partner name." }, "email": { "type": "string", "description": "Partner email." }, "type": { "type": "string", "description": "Partner type, e.g. PARTNER." } } } } }, "example": { "id": "EXAMPLE-ORDER-001", "status": "CONFIRMED", "statusName": "Awaiting acceptance", "service": "CCN", "serviceName": "Express", "orderScope": "DOMESTIC", "shipper": { "name": "Example Warehouse", "address": { "components": [ { "name": "Example warehouse, Street A", "type": "OTHER", "level": 999 }, { "id": "5025963", "code": "120211", "name": "Voat Phnum", "type": "VILLAGE", "level": 3 }, { "id": "4059553", "code": "1202", "name": "Doun Penh", "type": "DISTRICT", "level": 2 }, { "id": "4025120", "code": "PNP", "name": "Phnom Penh", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "formattedAddress": "Example warehouse, Phnom Penh, Cambodia" } }, "consignee": { "name": "Example Recipient", "phone": "${CONSIGNEE_PHONE}", "address": { "components": [ { "name": "Example recipient, Street B", "type": "OTHER", "level": 999 }, { "id": "5025109", "code": "010201", "name": "បន្ទាយនាង", "type": "VILLAGE", "level": 3 }, { "id": "4059452", "code": "0102", "name": "មង្គលបូរី", "type": "DISTRICT", "level": 2 }, { "id": "4025109", "code": "BAN", "name": "Banteay Meanchey", "type": "PROVINCE", "level": 1 }, { "type": "NATIONAL", "name": "Cambodia", "code": "KH", "level": 0 } ], "formattedAddress": "Example recipient, Banteay Meanchey, Cambodia" } }, "parcel": { "weight": 100, "weightUnit": "GRAM", "length": 10, "width": 10, "height": 10, "measurementUnit": "CENTIMET", "type": "GOODS", "items": [ { "name": "Example product", "type": "GOODS", "value": 50, "weight": 10, "quantity": 8 } ] }, "cod": 50, "totalFees": 1.75, "totalTax": 0.16, "originalPrice": 1.59, "detailedFees": { "currency": "USD", "serviceFee": [ { "service": "CCN", "fee": 1.44, "feeAfterVat": 1.59, "vatPrice": 0.14 } ] }, "payerType": "CONSIGNEE", "vas": [ "NTN", "VTT" ], "estDeliveryTime": { "days": 1.5, "date": "15/10/2026" }, "createdAt": "2026-10-14T09:00:00+00:00", "txId": "00000000-0000-4000-8000-000000000001", "invoice": "NONE", "receiveType": "AT_HOME", "partnerInfo": { "id": 900001, "partner_code": "EXAMPLE-PARTNER", "partner_name": "Example Partner", "type": "PARTNER" } } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/order/label/presigned": { "post": { "operationId": "createLabelTemplate", "summary": "Create a label template", "description": "Use order IDs returned by creation. Both label endpoints use the **same TMS Partner base URL** as every other operation. Always provide `labelId` and `orderIds`, even though the current code lacks required-field validation and missing values can fail at runtime instead of returning a clear 400.\n\n`setting.maskContact`, if omitted, the system configuration applies. `sellerAsShipper=true` displays the seller rather than the warehouse. `securePath` is the next endpoint’s `source-path`; `exp` is a Unix millisecond timestamp. Fetch and print before it expires.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Always supply labelId and orderIds. Current code does not enforce requiredness and omissions can cause runtime errors.", "properties": { "labelId": { "type": "string", "description": "Print format examples: a5, a6, a7; full enum is not supplied." }, "orderIds": { "type": "array", "description": "IDs returned by create-order.", "items": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." } }, "setting": { "type": "object", "description": "Optional print settings.", "properties": { "copy": { "type": "number", "description": "Copies per order." }, "hideFees": { "type": "boolean", "description": "Hide fees on the label." }, "sellerAsShipper": { "type": "boolean", "description": "Show seller name instead of warehouse." }, "maskContact": { "type": "boolean", "description": "Partially hide phone/contact details; defaults to system configuration." } } } }, "required": [ "labelId", "orderIds" ] }, "example": { "labelId": "a7", "orderIds": [ "EXAMPLE-ORDER-001" ], "setting": { "copy": 1, "hideFees": false, "sellerAsShipper": true, "maskContact": false } } } } }, "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "Temporary label location.", "properties": { "securePath": { "type": "string", "description": "Temporary secure token used as source-path." }, "exp": { "type": "number", "description": "Expiry as Unix timestamp in milliseconds; fetch before expiry." } } }, "example": { "securePath": "00000000-0000-4000-8000-000000000002", "exp": 1791972000000 } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/order/label/{source-path}": { "get": { "operationId": "getLabelHtml", "summary": "Retrieve label HTML", "description": "**Always HTML, not PDF.** The response has `Content-Type: text/html`; the source explicitly says no binary PDF is generated and no download `Content-Disposition` is set. The HTML format follows the prior `labelId`. Open it in a browser or an appropriately isolated iframe, print from the browser, or perform HTML-to-PDF conversion in your own system if a PDF is needed. Treat returned HTML as external content, not trusted markup for your application.\n\nUse `Accept: text/html` and both authentication headers. The presigned path still has an expiry. Use the same TMS Partner server.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." }, { "name": "source-path", "in": "path", "required": true, "schema": { "type": "string", "description": "securePath from create-label; use before exp." }, "description": "securePath from create-label; use before exp." } ], "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "text/html": { "schema": { "type": "string", "description": "HTML label in the selected format. Not binary PDF; no download Content-Disposition is documented." }, "example": "

Illustrative label HTML; layout is generated by TMS.

" } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/order/cancel": { "delete": { "operationId": "cancelOrder", "summary": "Cancel an order", "description": "Send a JSON body even though the method is DELETE. `order_code` is the `id` from create-order. Cancellation is permitted only for internal states **110, 120, 200, 220, 230**, the “pickup in progress” group in the webhook table. The guide also says an order already handed over to the courier or in transport cannot be canceled; use the explicit numeric eligibility list rather than guessing from translated labels.\n\n**Do not rely on HTTP success.** If no order matches for the partner, the source describes `{}` (order_code absent/null), not a clear error. Confirm that the returned `order_code` matches the requested one.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Cancellation request with a JSON body.", "properties": { "order_code": { "type": "string", "description": "The id returned by create-order." } }, "required": [ "order_code" ] }, "example": { "order_code": "EXAMPLE-ORDER-001" } } } }, "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "May be {} when not found. HTTP success alone is not confirmation.", "properties": { "order_code": { "type": [ "string", "null" ], "description": "Must match the requested order to confirm cancellation. Absent/null when no partner order matches." } } }, "example": { "order_code": "EXAMPLE-ORDER-001" } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } }, "/order/{order_code}": { "get": { "operationId": "getOrderStatus", "summary": "Look up order status", "description": "**Exactly three fields:** `id`, numeric `status`, and `updated_at`. This endpoint does not return the create-order response, pricing, full addresses, or parcel details. Preserve the create response for full order data; webhook messages provide journey updates, not a replacement full-order snapshot.\n\nCompare numeric `status` with the webhook status table. Do not confuse it with create-order’s textual `CONFIRMED`. `updated_at` records the latest status change.", "tags": [ "Cambodia" ], "parameters": [ { "name": "X-Api-Token", "in": "header", "required": true, "schema": { "type": "string", "description": "Environment-specific token supplied by TMS. Keep secret." }, "description": "Environment-specific token supplied by TMS. Keep secret." }, { "name": "X-Client-Source", "in": "header", "required": true, "schema": { "type": "string", "description": "Partner code paired with the token." }, "description": "Partner code paired with the token." }, { "name": "Accept-Language", "in": "header", "required": false, "schema": { "type": "string", "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS.", "enum": [ "vn", "en", "my", "km", "lo" ] }, "description": "Declared API values use vn, not portal locale vi. Source examples conflict; confirm with TMS." }, { "name": "order_code", "in": "path", "required": true, "schema": { "type": "string", "description": "The id returned by create-order." }, "description": "The id returned by create-order." } ], "responses": { "200": { "description": "Illustrative successful response; check business result fields.", "content": { "application/json": { "schema": { "type": "object", "description": "Exactly these three fields, not a full order response.", "properties": { "id": { "type": "string", "description": "Use the identifier returned by the API, not the illustrative value." }, "status": { "type": "integer", "description": "Current numeric status; use the webhook status table." }, "updated_at": { "type": "string", "description": "Last status update time.", "format": "date-time" } }, "additionalProperties": false }, "example": { "id": "EXAMPLE-ORDER-001", "status": 110, "updated_at": "2026-10-14T09:00:00.000+00:00" } } } }, "400": { "description": "Bad Request. Missing/malformed input; some endpoints instead produce 500." }, "401": { "description": "Unauthorized. Invalid or expired X-Api-Token." }, "403": { "description": "Forbidden. Check token and X-Client-Source pairing." }, "404": { "description": "Not Found. Check URL/location/order identifiers." }, "422": { "description": "Business validation failed; inspect the response message. Error body schema not supplied." }, "500": { "description": "TMS server error or missing inputs on incompletely validated endpoints. Error body schema not supplied." } }, "security": [ { "XApiToken": [], "XClientSource": [] } ] } } }, "webhooks": { "orderStatus": { "post": { "operationId": "receiveOrderStatus", "summary": "Receive status webhooks", "description": "Authenticate incoming journey updates, acknowledge receipt, and handle duplicate states.", "tags": [ "Webhooks" ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string", "description": "Bearer ${WEBHOOK_TOKEN}; token supplied by partner during configuration." }, "description": "Bearer ${WEBHOOK_TOKEN}; token supplied by partner during configuration." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "TMS posts journey updates to one partner-provided webhook URL. Older states can be resent.", "properties": { "order_code": { "type": "string", "description": "Order code." }, "post_code": { "type": "string", "description": "Current branch/unit code." }, "province_code": { "type": "string", "description": "Province code of the current unit." }, "province_name": { "type": "string", "description": "Province name of the current unit." }, "department_address": { "type": "string", "description": "Current unit address." }, "status_code": { "type": "integer", "description": "Numeric journey status from the status table." }, "status_name": { "type": "string", "description": "Journey status label." }, "actor_name": { "type": "string", "description": "Actor name; personal data must be protected." }, "updated_at": { "type": "string", "description": "Current status update time, ISO 8601.", "format": "date-time" }, "note": { "type": [ "string", "null" ], "description": "Current status name and optional note." } }, "required": [ "order_code", "post_code", "province_code", "province_name", "department_address", "status_code", "status_name", "actor_name", "updated_at" ] }, "example": { "order_code": "EXAMPLE-ORDER-001", "post_code": "EXAMPLE-POST", "province_code": "SPE", "province_name": "Kampong Speu", "department_address": "Example branch, Kampong Speu", "status_code": 410, "status_name": "Delivered successfully", "actor_name": "Example Operator", "updated_at": "2026-10-14T14:30:00+07:00", "note": "Delivered successfully" } } } }, "responses": { "200": { "description": "Received; no retry. Response body is not specified." }, "default": { "description": "Non-200 or timeout: TMS retries according to configuration not specified by the source." } }, "x-webhook-name": "orderStatus", "security": [ { "WebhookBearer": [] } ] } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API token sent in the Authorization header as a bearer token. Keep it secret." }, "WebhookBearer": { "type": "http", "scheme": "bearer", "description": "Webhook token configured for event delivery; separate from the API token." }, "XApiToken": { "type": "apiKey", "in": "header", "name": "X-Api-Token", "description": "Environment-specific token supplied by TMS. Keep secret." }, "XClientSource": { "type": "apiKey", "in": "header", "name": "X-Client-Source", "description": "Partner code paired with the token." } } } }