> For the complete documentation index, see [llms.txt](https://docs.caresoft.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/khach-hang/thong-tin-tinh-huyen-xa.md).

# 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 %}