# Lấy Bưu cục

> Tìm bưu cục GHN gần một quận/huyện, ví dụ để shop mang hàng đến gửi tại bưu cục.

## Endpoint

| Môi trường | URL |
| --- | --- |
| Production | `https://online-gateway.ghn.vn/shiip/public-api/v2/station/get` |
| Staging | `https://dev-online-gateway.ghn.vn/shiip/public-api/v2/station/get` |

**Method**: `GET`

## Headers

| Header | Bắt buộc | Mô tả |
| --- | --- | --- |
| `Token` | Có | Token của shop (do GHN cấp) — [lấy token](https://developer.ghn.vn/vi/docs/token/get-token.md) |
| `ShopId` | Có | Shop ID (số nguyên) |
| `captcha` | Tùy điều kiện | Một số tài khoản (không có quyền tra cứu bưu cục) phải gửi captcha token ở header này, nếu không sẽ nhận HTTP 422. Liên hệ GHN nếu gặp trường hợp này |

## Tham số

- **district_id** (String): Mã quận/huyện (từ [Lấy Quận/Huyện](https://developer.ghn.vn/vi/docs/master-data/get-district.md)).
- **ward_code** (String): Mã phường/xã (từ [Lấy Phường/Xã](https://developer.ghn.vn/vi/docs/master-data/get-ward.md)) để thu hẹp tìm kiếm
- **offset** (Int): Vị trí phân trang. Mặc định: `0`
- **limit** (Int): Số lượng mỗi trang. Mặc định: do GHN quy định

## Ví dụ Request

```bash
curl -X GET "https://dev-online-gateway.ghn.vn/shiip/public-api/v2/station/get?district_id=1444&offset=0&limit=20" \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837"
```

## Response

`data` là một **mảng** object bưu cục (`[]` khi không có kết quả, không bao giờ `null`).

_Cấu trúc theo tài liệu trường của GHN — tài khoản test này yêu cầu captcha token nên không lấy được mẫu thành công thật (xem lỗi 422 bên dưới)._

```json
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "locationId": 1888,
      "locationName": "Bưu cục 1888 - Quận 1",
      "address": "123 Lê Lợi, Phường Bến Thành, Quận 1, TP. Hồ Chí Minh",
      "wardName": "Phường Bến Thành",
      "districtName": "Quận 1",
      "provinceName": "Hồ Chí Minh",
      "latitude": 10.7721,
      "longitude": 106.698,
      "email": "buucuc1888@ghn.vn"
    }
  ]
}
```

### Các trường Response

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `locationId` | Int | **Mã bưu cục** — dùng làm `pick_station_id` khi tạo đơn |
| `locationName` | String | Tên bưu cục |
| `address` | String | Địa chỉ bưu cục |
| `wardName` | String | Tên phường/xã |
| `districtName` | String | Tên quận/huyện |
| `provinceName` | String | Tên tỉnh |
| `latitude` | Float | Vĩ độ |
| `longitude` | Float | Kinh độ |
| `email` | String | Email bưu cục |

### Lỗi — cần captcha (HTTP 422)

_Lấy từ một lần gọi thật trên môi trường Staging — tài khoản này không có quyền tra cứu bưu cục nên endpoint yêu cầu captcha token._

```json
{
  "code": 422,
  "message": "token contains an invalid number of segments",
  "data": null,
  "code_message": "SECURITY_CHECK_FAILED",
  "code_message_value": "Discover fraud and abuse potential"
}
```

## Bảng mã lỗi

| code_message | HTTP | Khi nào |
| --- | --- | --- |
| `SECURITY_CHECK_FAILED` | 422 | Tài khoản cần captcha token ở header `captcha` — liên hệ GHN |
| `USER_ERR_COMMON` | 400 | Dữ liệu không hợp lệ |
| `STATION_INVALID` | 400 | Tra cứu bưu cục thất bại phía GHN |
| `SERVER_ERROR_COMMON` | 500 | Lỗi hệ thống |