Hướng Dẫn Tích Hợp API

Lấy Danh Sách Địa Phương (Tỉnh/Huyện/Xã)

API lấy danh sách địa phương (tỉnh thành, quận huyện, phường xã) của Việt Nam. Hỗ trợ phân trang, tìm kiếm theo từ khóa, và lọc theo cấp địa phương. Sử dụng JWT token để xác thực người dùng.

GET https://api.socdo.vn/mini-app/v1/locations

Request Headers

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
Content-Type: application/json

Query Parameters

GET /locations?type=province&page=1&limit=500

GET /locations?type=district&tinh=1&keyword=Hà Nội&page=1&limit=100

GET /locations?type=ward&huyen=1&tinh=1&keyword=Ba Đình&page=1&limit=100

Tham số

Tham số	Loại	Bắt buộc	Mô tả
`Authorization`	header	✓	JWT token từ API login (Bearer token)
`type`	query	-	Loại địa phương: 'province' (tỉnh/thành), 'district' (quận/huyện), 'ward' (phường/xã) (mặc định: 'province')
`tinh`	query	Conditional*	ID tỉnh/thành phố (bắt buộc nếu type=district hoặc type=ward)
`huyen`	query	Conditional*	ID quận/huyện (bắt buộc nếu type=ward)
`keyword`	query	-	Từ khóa tìm kiếm (tìm trong tên, code, slug)
`page`	query	-	Trang hiện tại (mặc định: 1)
`limit`	query	-	Số bản ghi mỗi trang (1-1000, mặc định: 500)

Lưu ý:

Khi type=district: Tham số tinh là bắt buộc
Khi type=ward: Tham số huyen là bắt buộc, tinh là tùy chọn
Kết quả được sắp xếp theo thu_tu (thứ tự) và id

Response thành công (200) - Lấy danh sách tỉnh/thành

{
    "success": true,
    "message": "Lấy danh sách địa phương thành công",
    "data": {
        "type": "province",
        "items": [
            {
                "id": 1,
                "code": "01",
                "name": "Thành phố Hà Nội",
                "slug": "ha-noi",
                "region": "Bắc Bộ",
                "area": "Đồng bằng sông Hồng",
                "order": 1
            },
            {
                "id": 2,
                "code": "48",
                "name": "Thành phố Hồ Chí Minh",
                "slug": "ho-chi-minh",
                "region": "Nam Bộ",
                "area": "Đông Nam Bộ",
                "order": 2
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 2,
            "total_records": 63,
            "limit": 500,
            "has_next": true,
            "has_prev": false
        },
        "filters": {
            "tinh": 0,
            "huyen": 0,
            "keyword": ""
        }
    }
}

Response thành công (200) - Lấy danh sách quận/huyện

{
    "success": true,
    "message": "Lấy danh sách địa phương thành công",
    "data": {
        "type": "district",
        "items": [
            {
                "id": 1,
                "province_id": 1,
                "code": "001",
                "name": "Quận Ba Đình",
                "slug": "ba-dinh",
                "order": 1
            },
            {
                "id": 2,
                "province_id": 1,
                "code": "002",
                "name": "Quận Hoàn Kiếm",
                "slug": "hoan-kiem",
                "order": 2
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 1,
            "total_records": 30,
            "limit": 500,
            "has_next": false,
            "has_prev": false
        },
        "filters": {
            "tinh": 1,
            "huyen": 0,
            "keyword": ""
        }
    }
}

Response thành công (200) - Lấy danh sách phường/xã

{
    "success": true,
    "message": "Lấy danh sách địa phương thành công",
    "data": {
        "type": "ward",
        "items": [
            {
                "id": 1,
                "province_id": 1,
                "district_id": 1,
                "code": "00001",
                "name": "Phường Phúc Xá",
                "slug": "phuc-xa",
                "order": 1
            },
            {
                "id": 2,
                "province_id": 1,
                "district_id": 1,
                "code": "00004",
                "name": "Phường Trúc Bạch",
                "slug": "truc-bach",
                "order": 2
            }
        ],
        "pagination": {
            "current_page": 1,
            "total_pages": 1,
            "total_records": 18,
            "limit": 500,
            "has_next": false,
            "has_prev": false
        },
        "filters": {
            "tinh": 1,
            "huyen": 1,
            "keyword": ""
        }
    }
}

Response lỗi (401 - Token không hợp lệ)

{
    "success": false,
    "message": "Token không hợp lệ",
    "error": "Invalid token or issuer mismatch"
}

Response lỗi (401 - Không tìm thấy token)

{
    "message": "Không tìm thấy token"
}

Response lỗi (400 - Thiếu tham số)

{
    "success": false,
    "message": "Thiếu tham số tinh (province id) cho type=district"
}

Response lỗi (400 - Type không hợp lệ)

{
    "success": false,
    "message": "Giá trị type không hợp lệ. Hỗ trợ: province, district, ward"
}

Response lỗi (405 - Method không được phép)

{
    "success": false,
    "message": "Chỉ hỗ trợ phương thức GET"
}

Response lỗi (500 - Lỗi database)

{
    "success": false,
    "message": "Lỗi truy vấn database: count"
}

Ví dụ sử dụng

1. Lấy danh sách tất cả tỉnh/thành phố:

GET /locations?type=province&page=1&limit=500

2. Lấy danh sách quận/huyện của một tỉnh:

GET /locations?type=district&tinh=1&page=1&limit=500

3. Lấy danh sách phường/xã của một quận/huyện:

GET /locations?type=ward&huyen=1&tinh=1&page=1&limit=500

4. Tìm kiếm tỉnh/thành phố theo từ khóa:

GET /locations?type=province&keyword=Hà Nội&page=1&limit=100

Mô tả Response Fields

Field	Type	Mô tả
`data.type`	string	Loại địa phương: 'province', 'district', 'ward'
`data.items[].id`	integer	ID của địa phương trong database
`data.items[].code`	string	Mã code của địa phương (id_tinh, id_huyen, id_xa)
`data.items[].name`	string	Tên địa phương
`data.items[].slug`	string	URL slug của địa phương
`data.items[].province_id`	integer	ID tỉnh/thành (chỉ có khi type=district hoặc ward)
`data.items[].district_id`	integer	ID quận/huyện (chỉ có khi type=ward)
`data.items[].region`	string	Miền (Bắc Bộ, Trung Bộ, Nam Bộ) - chỉ có khi type=province
`data.items[].area`	string	Vùng (VD: Đồng bằng sông Hồng) - chỉ có khi type=province
`data.items[].order`	integer	Thứ tự hiển thị (thu_tu)
`data.pagination`	object	Thông tin phân trang
`data.filters`	object	Thông tin filters đã áp dụng