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.

Tra danh mục đơn vị hành chính

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

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)

{
  "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`	Khoá API thiếu, sai hoặc đã bị thu hồi
403	`insufficient-permission`	Khoá API không có quyền thực hiện thao tác này
403	`shop-suspended`	Shop đang bị đình chỉ
403	`automation-not-active`	Shop chưa bật tính năng Tự động hoá
429	`rate-limited`	Vượt hạn mức gọi API, hãy chờ rồi thử lại
500	`internal-error`	Lỗi hệ thống
400	`validation-failed`	Dữ liệu gửi lên không hợp lệ
404	`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.