# Lấy Phường/Xã (Mới)

> Lấy danh sách phường/xã của một tỉnh/thành theo mô hình hành chính 2 cấp.

> **NOTE**
> **Mô hình địa chỉ 2 cấp (mới).** Phường/xã thuộc thẳng tỉnh/thành, không còn cấp quận/huyện. `name` trả về là giá trị truyền thẳng vào `to_ward_name` khi [Tạo đơn](https://developer.ghn.dev/vi/docs/order/create.md) với `is_new_to_address: true`. Danh mục theo quận/huyện cũ vẫn ở [Lấy Phường/Xã](https://developer.ghn.dev/vi/docs/master-data/get-ward.md).

## Endpoint

| Môi trường | URL |
| --- | --- |
| Production | `https://online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id` |
| Staging | `https://dev-online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id` |

**Method**: `GET`

## Headers

| Header | Bắt buộc | Mô tả |
| --- | --- | --- |
| `Token` | Có | Token của bạn (do GHN cấp) — [lấy token](https://developer.ghn.dev/vi/docs/token/get-token.md) |
| `ShopId` | Có | Shop ID (số nguyên) |

## Tham số

- **province_id** (Int): Mã tỉnh/thành hệ 2 cấp, lấy từ [Lấy Tỉnh/Thành (Mới)](https://developer.ghn.dev/vi/docs/master-data/get-province-new.md) (trường `_id`). Thiếu hoặc sai mã thì API vẫn trả HTTP 200 nhưng `data` là `null` — hãy coi `data` rỗng là dấu hiệu sai mã tỉnh
- **offset** (Int): Vị trí bắt đầu khi phân trang. Mặc định: `0`
- **limit** (Int): Số phần tử tối đa, không quá `200`. Tỉnh nhiều phường/xã nhất hiện là TP. Hồ Chí Minh với 168 — một lần gọi `limit=200` là đủ

## Ví dụ Request

```bash
curl -X GET "https://dev-online-gateway.ghn.vn/shiip/public-api/v3/master-data/ward/all-by-province-id?province_id=1000001&offset=0&limit=200" \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837"
```

## Response

### Thành công (HTTP 200)

_Lấy từ một lần gọi thật trên môi trường Staging với `province_id=1000001` (TP. Hồ Chí Minh — rút gọn còn một trong 168 phường/xã, bỏ các trường quản trị nội bộ)._

```json
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "_id": 1003646,
      "name": "Phường Vũng Tàu",
      "extension_names": [
        "phường vũng tàu",
        "p.vũng tàu",
        "vũng tàu",
        "vung tau",
        "phuong vung tau"
      ],
      "type": "ward",
      "parent_id": 1000001,
      "status": 1
    }
  ]
}
```

### Các trường Response

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `data[]._id` | Int | Mã phường/xã hệ 2 cấp (định danh nội bộ của GHN) |
| `data[].name` | String | Tên chuẩn của phường/xã — dùng nguyên văn cho `to_ward_name` khi [Tạo đơn](https://developer.ghn.dev/vi/docs/order/create.md) hệ mới |
| `data[].extension_names` | String[] | Các biến thể tên (không dấu, viết tắt…) — dùng để so khớp hoặc gợi ý khi người dùng gõ tự do |
| `data[].type` | String | Luôn là `ward` |
| `data[].parent_id` | Int | Mã tỉnh/thành chứa phường/xã này (`_id` bên [Lấy Tỉnh/Thành (Mới)](https://developer.ghn.dev/vi/docs/master-data/get-province-new.md)) |
| `data[].status` | Int | Là `1` nếu đang hoạt động, là `2` nếu ngưng sử dụng, là `10` nếu đã xoá |

## Bảng mã lỗi

| Điều kiện | HTTP | Ý nghĩa |
| --- | --- | --- |
| `Authorization header is required!` | 401 | Thiếu `Token` |
| `data` là `null` | 200 | `province_id` thiếu hoặc không tồn tại (API không trả lỗi riêng) |
| IP không được phép | 401 | Tài khoản của bạn có whitelist IP và request đến từ IP khác |
| `SERVER_ERROR_COMMON` | 500 | Lỗi hệ thống |