# Integration overview

Authenticate, choose an environment, and follow the complete Metfone Express shipping workflow.

Company: Metfone Express
API version: v1
Requested language: en
Content language: en
Source: https://mfexpress-partner-docs.zhst.app/mfexpress/en/overview


## Authentication and environments



| Header | Requirement | Value / meaning |
| --- | --- | --- |
| X-Api-Token | Required | `${API_TOKEN}`: environment-specific token issued by TMS |
| X-Client-Source | Required | `${PARTNER_CODE}`: partner code paired with the token |
| Content-Type | With a JSON body | application/json |
| Accept | Required by source | application/json |
| Accept-Language | Optional | `vn`, `en`, `my`, `km`, `lo` |

Contact TMS technical support for separate token/partner-code pairs for sandbox and production. Do not mix environments. The portal locale is `vi`, but the declared `Accept-Language` value is `vn`; several source examples use `vi`, so confirm provider behavior. Khmer, Lao, and Burmese have translated interfaces; missing document translations disclose the actual page language and fallback.

```bash
export BASE_URL="https://dev-gw.metfone.com.kh/tms-partner/api/v1"
# API_TOKEN and PARTNER_CODE must be supplied by your private environment.
# Never put production secrets into examples or AI prompts.
```

## Integration journey

1. [Load provinces](provinces), then [districts/villages](administrative-divisions); retain current IDs/codes.
2. [Find a post office](post-offices) if branch drop-off/collection is needed.
3. [Discover services](available-services) for the route and goods.
4. [Calculate prices](calculate-pricing) for selected service codes.
5. [Create the order](create-order), **resend moneyCollection**, compare cod, and save the response.
6. [Create a template](create-label), then [retrieve HTML](print-label) before expiry.
7. [Receive webhooks](webhook-status), [look up status](order-status) as needed; [cancel](cancel-order) only when eligible.

```mermaid
flowchart LR
  A["Addresses"] --> B["Services"]
  A --> P["Optional post office"]
  B --> C["Pricing"]
  C --> D["Order and COD"]
  D --> E["Label template"]
  E --> F["Printable HTML"]
  D --> G["Journey webhooks"]
  D --> H["Status lookup"]
```

## Request sequence


```mermaid
sequenceDiagram
  participant P as Partner
  participant T as TMS Partner
  P->>T: GET address levels 1, 2, 3
  T-->>P: IDs and codes
  P->>T: POST pricing/get-service
  T-->>P: Service codes and selection flags
  P->>T: POST pricing/get-all
  T-->>P: Pre-VAT fee breakdown
  P->>T: POST order with moneyCollection
  T-->>P: id, cod, full creation response
  P->>T: POST order/label/presigned
  T-->>P: securePath, exp
  P->>T: GET order/label/securePath
  T-->>P: text/html
  T->>P: POST status webhook
  P-->>T: HTTP 200 receipt acknowledgement
```