# Thông tin tỉnh/huyện/xã

Trong trường hợp cần gán địa chỉ khách hàng và phân cấp Tỉnh/Huyện thì sử dụng các api dưới đây để đồng bộ danh bạ tỉnh/thành, quận/huyện về ứng dụng.

{% hint style="info" %}
Dữ liệu tỉnh/thành phố, quận/huyện, xã/phường chỉ áp dụng cho các địa phương ở Việt Nam 
{% endhint %}

## Lấy danh sách tỉnh/thành phố

Dữ liệu đã được cập nhật trạng thái chính quyền 2 cấp đối với các tỉnh được giữ nguyên tên và tỉnh được sát nhập sẽ có thêm trạng thái chỉ thị.

<figure><img src="/files/GYJdXZyfuJC77vWw0NtX" alt=""><figcaption><p>Mô phỏng dữ liệu tỉnh thành từ POSTMAN</p></figcaption></figure>

## Lấy danh sách tỉnh/thành phố&#x20;

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/cities`

#### Headers

| Name                                     | Type   | Description                                                           |
| ---------------------------------------- | ------ | --------------------------------------------------------------------- |
| \*\*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung.md#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "data": [
        {
            "id": "01",
            "name": "Thành phố Hà Nội",
            "type": "Thành phố Trung ương",
            "status": 1
        },
        {
            "id": "02",
            "name": "Tỉnh Hà Giang",
            "type": "Tỉnh",
            "status": 0
        },
....
```

{% endtab %}

{% tab title="Cấu trúc thông tin" %}

<table><thead><tr><th width="83">STT</th><th width="140">Trường dữ liệu</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy</td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu chứa các đối tượng thông tin từng tỉnh thành có cấu trúc<br>- <code>id</code>: ID tỉnh thành, tương ứng với <strong><code>city_id</code></strong> khi tạo mới/cập nhật khách hàng hoặc lấy chi tiết các huyện/quận của 1 tỉnh<br>- <code>name</code>: Tên thành phố/Tỉnh<br>- <code>type</code>: Phân loại cấp thành phố/tỉnh</p><p>- <code>status</code>: Trạng thái sử dụng trong chính quyền 2 cấp: 0 ngưng sử dụng, 1: Đang sử dụng </p><p></p></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}
{% endtabs %}

## Lấy danh sách quận/huyện&#x20;

<figure><img src="/files/X1CHMXmVBTIN4gWFuFQr" alt=""><figcaption><p>Chi tiết các quận/huyện theo city_id</p></figcaption></figure>

## Danh sách quận/huyện theo ID của tỉnh/thành phố

<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/districts`

#### Query Parameters

| Name                                       | Type   | Description                                       |
| ------------------------------------------ | ------ | ------------------------------------------------- |
| city\_id<mark style="color:red;">\*</mark> | String | ID của tỉnh/thành phố dựa theo api Danh sách tỉnh |

#### Headers

| Name                                   | Type   | Description                                                           |
| -------------------------------------- | ------ | --------------------------------------------------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung.md#phuong-thuc-xac-thuc) |
|                                        |        |                                                                       |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{
    "code": "ok",
    "numFound": 30,
    "data": [
        {
            "id": "001",
            "name": "Quận Ba Đình",
            "type": "Quận",
            "city_id": "01"
        },
        {
            "id": "002",
            "name": "Quận Hoàn Kiếm",
            "type": "Quận",
            "city_id": "01"
        },
        ....
        ]
}

```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="106">STT</th><th width="179">Trường thông tin</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy </td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu quận huyện  có cấu trúc</p><ul><li><code>id</code>: ID huyện/quận sẽ tương ứng với <strong><code>district_id</code></strong> khi tạo/cập nhật khách hàng và lấy thông tin khách hàng về</li><li><code>name</code>: Tên huyện/quận</li><li><code>type</code>: Kiểu quận hoặc huyện</li><li><code>city_id</code>: ID của thành phố</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="422: Unprocessable Entity Lỗi không cung cấp param city\_id" %}

```
{
    "code": "errors",
    "message": "Invalid city_id params"
}
```

{% endtab %}
{% endtabs %}

## Danh sách xã theo tỉnh (Xã theo cơ chế chính quyền 2 cấp)

Danh sách các xã theo city\_id  của tỉnh/thành phố có status=1 (Tỉnh sau sát nhập) dựa trên API Tỉnh/thành phố ở trên

&#x20;<mark style="color:blue;">`GET`</mark> `{{domain}}/api/v1/wards`

| Name                                       | Type   | Description                                       |
| ------------------------------------------ | ------ | ------------------------------------------------- |
| city\_id<mark style="color:red;">\*</mark> | String | ID của tỉnh/thành phố dựa theo api Danh sách tỉnh |

#### Headers

| Name                                   | Type   | Description                                                           |
| -------------------------------------- | ------ | --------------------------------------------------------------------- |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](/thong-tin-chung.md#phuong-thuc-xac-thuc) |
|                                        |        |                                                                       |

Response:&#x20;

{% tabs %}
{% tab title="200: Thành công" %}
Kết quả điển hình ( payload là:  city\_id=34)&#x20;

{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "numFound": 104,
    "data": [
        {
            "id": "13279",
            "name": "Xã Vũ Tiên",
            "city_id": "33"
        },
        {
            "id": "13264",
            "name": "Xã Thư Vũ",
            "city_id": "33"
        },
        {
            "id": "13246",
            "name": "Xã Tân Thuận",
            "city_id": "33"
        },
...
```

{% endtab %}

{% tab title="Mô tả kết quả" %}

<table><thead><tr><th width="106">STT</th><th width="179">Trường thông tin</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái yêu cầu</td></tr><tr><td>2</td><td>numFound</td><td>Số lượng bản ghi tìm thấy </td></tr><tr><td>3</td><td>data</td><td><p>Mảng dữ liệu xã phường  có cấu trúc</p><ul><li><code>id</code>: ID Xã/phường sẽ tương ứng với <code>ward_id</code>  khi tạo/cập nhật khách hàng và lấy thông tin khách hàng về</li><li><code>name</code>: Tên xã phường</li><li><code>city_id</code>: ID của thành phố/Tỉnh</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}

{% endtab %}

{% tab title="422: Lỗi thiếu thông tin" %}
Kết quả điển hình:

```json
{
    "code": "errors",
    "message": "Invalid city_id params"
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.