# Trả hàng

> Buộc trả một hoặc nhiều đơn về người gửi. Đơn phải đang ở trong mạng lưới GHN tại giai đoạn có thể trả — xem `order_codes` bên dưới.

## Endpoint

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

**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ố

- **order_codes** (String[]): Danh sách mã vận đơn GHN cần buộc trả, gửi theo lô. Mỗi đơn phải đang ở trạng thái có thể trả — `delivery_fail`, `storing`, `waiting_to_return`, hoặc `return`; trạng thái khác sẽ trả về `result: false` (xem Response). Xử lý **theo từng đơn** (best-effort), không phải tất-cả-hoặc-không

## Ví dụ Request

```bash
curl -X POST https://dev-online-gateway.ghn.vn/shiip/public-api/v2/switch-status/return \
  -H "Token: 5c1d8a9e-2f4b-11ed-..." \
  -H "ShopId: 92837" \
  -H "Content-Type: application/json" \
  -d '{
    "order_codes": ["LADHFT", "LADFYR"]
  }'
```

## Response

### Kết quả (HTTP 200)

**Best-effort theo từng đơn**: mỗi mã được xử lý độc lập, nên response luôn là HTTP 200 với một phần tử cho mỗi mã — kể cả khi tất cả đều thất bại. **Luôn kiểm tra `result` của từng phần tử**; HTTP 200 không có nghĩa là mọi đơn đã được trả.

```json
{
  "code": 200,
  "message": "Success",
  "data": [
    {
      "order_code": "LADHFT",
      "result": false,
      "message": "Trạng thái đơn hàng không hợp lệ"
    },
    {
      "order_code": "NOTREAL9",
      "result": false,
      "message": "Order code không tồn tại."
    }
  ]
}
```

Một phần tử thành công có `result: true` và `message: "OK"`.

### Các trường Response

| Trường | Kiểu | Mô tả |
| --- | --- | --- |
| `code` | Int | Mã HTTP (`200` nếu thành công) |
| `message` | String | Thông báo kết quả tổng (`Success`) |
| `data` | Object[] | Mỗi phần tử tương ứng một mã đơn trong request |
| `data[].order_code` | String | Mã đơn của phần tử này |
| `data[].result` | Bool | `true` nếu đã trả hàng; `false` nếu đơn bị từ chối |
| `data[].message` | String | Thông báo từng đơn. `OK` khi thành công; khi thất bại là một trong:<br>`Trạng thái đơn hàng không hợp lệ` — trạng thái đơn không cho phép trả<br>`Order code không tồn tại.` — mã đơn không tồn tại<br>`Khách hàng không có quyền thay đổi trạng thái đơn hàng.` — đơn không thuộc tài khoản của bạn |

## Bảng mã lỗi

| Điều kiện | HTTP | Ý nghĩa |
| --- | --- | --- |
| `result: false` trong `data` | 200 | Thất bại theo từng đơn — kiểm tra `message` của phần tử (trạng thái không cho trả / mã không tồn tại / không phải đơn của bạn) |
| `CLIENT_NOT_OWNER_OF_SHOP` | 400 | Token không sở hữu shop |
| `SERVER_ERROR_COMMON` | 500 | Lỗi hệ thống |