# Lấy Dịch vụ

> Liệt kê các dịch vụ vận chuyển khả dụng cho một tuyến và shop. Gọi API này trước, rồi truyền `service_id` (hoặc `service_type_id`) trả về vào Tính phí và Tạo đơn.

## Endpoint

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

**Method**: `POST`

## Headers

| Header | Bắt buộc | Mô tả |
| --- | --- | --- |
| `Content-Type` | Có | `application/json` |
| `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) |

## Tham số

- **shop_id** (Int): Shop có hợp đồng/bảng giá quyết định các dịch vụ khả dụng. Đây là **trường trong body** (khác với header `ShopId`)
- **from_district** (Int): Mã quận/huyện lấy hàng (từ [Lấy Quận/Huyện](https://developer.ghn.vn/vi/docs/master-data/get-district.md))
- **to_district** (Int): Mã quận/huyện giao (từ [Lấy Quận/Huyện](https://developer.ghn.vn/vi/docs/master-data/get-district.md))

## Ví dụ Request

```bash
curl -X POST https://dev-online-gateway.ghn.vn/shiip/public-api/v2/shipping-order/available-services \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_id": 196560,
    "from_district": 1452,
    "to_district": 1444
  }'
```

## Response

### Thành công (HTTP 200)

_Lấy từ một lần gọi thật trên môi trường Staging._

```json
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "service_id": 53320,
      "short_name": "Hàng nhẹ",
      "service_type_id": 2
    },
    {
      "service_id": 100039,
      "short_name": "Hàng nặng",
      "service_type_id": 5
    }
  ]
}
```

### Các trường Response

`data` là một mảng dịch vụ khả dụng.

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `service_id` | Int | Mã dịch vụ — truyền vào [Tính phí](https://developer.ghn.vn/vi/docs/order/calculate-fee.md) và [Tạo đơn](https://developer.ghn.vn/vi/docs/order/create.md) |
| `short_name` | String | Tên hiển thị dịch vụ (ví dụ "Hàng nhẹ", "Hàng nặng") |
| `service_type_id` | Int | Loại dịch vụ, chọn theo khối lượng:<br>`2`: tổng khối lượng **dưới 20 kg**<br>`5`: tổng khối lượng **từ 20 kg trở lên**, hoặc đơn nhiều kiện |

## Lưu ý

- **Response rỗng nghĩa là không tìm thấy shop.** Nếu `shop_id` bạn gửi không tồn tại, GHN trả về HTTP 200 với **body rỗng** (không phải lỗi JSON). Hãy coi body rỗng là "không tìm thấy shop".

## Bảng mã lỗi

| code_message | HTTP | Khi nào |
| --- | --- | --- |
| `USER_ERR_COMMON` | 400 | Thiếu `shop_id` / `from_district` / `to_district` |
| `WARD_IS_INVALID` | 400 | Địa chỉ định dạng mới không map được sang quận/huyện |
| `SERVER_ERROR_COMMON` | 500 | Lỗi hệ thống |