# Tham chiếu: Địa giới hành chính

Danh mục tỉnh, huyện, xã để lấy mã đơn vị cho địa chỉ giao hàng. Mọi đường dẫn dưới `https://danix.vn/api/open/v1`. Đặc tả máy đọc: [openapi.json](/openapi.json).

## Tra danh mục đơn vị hành chính {#listGeoUnits}

`GET /geo/units`

Duyệt cây tỉnh → (huyện) → xã của một hệ địa giới, mỗi lượt một tầng: vắng `parentId` là các tỉnh, có `parentId` là các đơn vị con của nó. Không phân trang (mỗi tầng tối đa vài trăm dòng), sắp theo tên. Dùng `id` của kết quả làm `provinceUnitId`, `districtUnitId`, `wardUnitId` khi tạo đơn hay thêm địa chỉ khách — có mã thì đơn đẩy được sang hãng vận chuyển. `parentId` không có hoặc khác hệ trả `not-found`.

**Quyền cần có:** không cần quyền nào ngoài khoá hợp lệ.

**Tham số query**

| Tên | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `system` | "old" \| "new" | có | Hệ địa giới cần tra: `old` hoặc `new`. Bắt buộc. |
| `parentId` | string (uuid) | không | Mã đơn vị cha. Vắng thì trả các tỉnh, thành phố của hệ. |
| `search` | string | không | Lọc theo tên, không phân biệt hoa thường và dấu, trong tầng đang tra. |

**Ví dụ yêu cầu**

```bash
curl -X GET "https://danix.vn/api/open/v1/geo/units?system=old" \
  -H "Authorization: Bearer dnx_live_…"
```

**Phản hồi mẫu (200)**

```json
{
  "data": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
      "system": "old",
      "level": 1,
      "parentId": null,
      "name": "Đà Nẵng"
    }
  ]
}
```

**Trường của phản hồi**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `data` | array<object> | có | Các đơn vị của tầng. |
| `data[].id` | string (uuid) | có | Mã (UUID) của đơn vị trong danh mục của DANIX. |
| `data[].system` | "old" \| "new" | có | Hệ địa giới: `old` (tỉnh, huyện, xã — trước 01/07/2025) hoặc `new` (tỉnh, xã). |
| `data[].level` | integer | có | Cấp: 1 tỉnh hoặc thành phố, 2 quận hoặc huyện (chỉ hệ `old`), 3 phường hoặc xã. |
| `data[].parentId` | string (uuid) hoặc null | có | Đơn vị cấp trên; `null` với cấp tỉnh. |
| `data[].name` | string | có | Tên đơn vị. |

**Lỗi**

| Trạng thái | Mã `code` | Ý nghĩa |
| --- | --- | --- |
| 401 | [`invalid-api-key`](/developers/errors#invalid-api-key) | Khoá API thiếu, sai hoặc đã bị thu hồi |
| 403 | [`insufficient-permission`](/developers/errors#insufficient-permission) | Khoá API không có quyền thực hiện thao tác này |
| 403 | [`shop-suspended`](/developers/errors#shop-suspended) | Shop đang bị đình chỉ |
| 403 | [`automation-not-active`](/developers/errors#automation-not-active) | Shop chưa bật tính năng Tự động hoá |
| 429 | [`rate-limited`](/developers/errors#rate-limited) | Vượt hạn mức gọi API, hãy chờ rồi thử lại |
| 500 | [`internal-error`](/developers/errors#internal-error) | Lỗi hệ thống |
| 400 | [`validation-failed`](/developers/errors#validation-failed) | Dữ liệu gửi lên không hợp lệ |
| 404 | [`not-found`](/developers/errors#not-found) | Không tìm thấy tài nguyên |

Định dạng lỗi và bảng mọi mã `code`: [Lỗi](/developers/errors).