# Đơn hàng

> API LocalSERP Proxy: gói dịch vụ và giá, mua gói bằng số dư và lịch sử đơn hàng. Tham số, phản hồi mẫu, mã curl, Python và Node.js.

- URL: https://localserpproxy.com/vi/docs/api/orders/
- Cập nhật lần cuối: 2026-10-15
- Publisher: LocalSERP Proxy (https://localserpproxy.com)

Xem danh sách gói dịch vụ và giá, mua gói bằng số dư (dịch vụ mới, thêm lưu lượng hoặc gia hạn cổng) và xem các đơn hàng trước đây.

**Các điểm cuối trên trang này**

- `GET /v1/catalog/products`: Sản phẩm, gói dịch vụ và giá
- `POST /v1/orders`: Mua gói bằng số dư (dịch vụ mới, thêm lưu lượng hoặc gia hạn cổng)
- `GET /v1/orders`: Liệt kê đơn hàng
- `GET /v1/orders/{orderId}`: Xem đơn hàng

URL cơ sở `https://localserpproxy.com/api/v1`. Xác thực, lỗi và giới hạn: xem [Tổng quan API](https://localserpproxy.com/vi/docs/api/).

## Sản phẩm, gói dịch vụ và giá

`GET /v1/catalog/products`

Tất cả sản phẩm cùng các gói dịch vụ và giá, đúng như mức phí khi đặt hàng.

Công khai: không cần khóa API.

**Phản hồi** `200 OK`

```json
{
  "data": [
    {
      "id": "residential",
      "name": "Residential proxies",
      "description": "Residential traffic for manual local search, advertising, price and application checks in US cities. State, city and ZIP selection, subject to available exits; no promise of GPS position or rankings.",
      "unit": "GB",
      "plans": [
        {
          "id": "res-10",
          "productId": "residential",
          "name": "Local team",
          "quantity": 10,
          "unit": "GB",
          "durationDays": null,
          "price": "7.50",
          "pricePerUnit": "0.75",
          "popular": false,
          "features": [
            "US city selection, subject to availability",
            "Traffic stays until used",
            "Rotating or sticky sessions"
          ],
          "available": true,
          "countries": null
        }
      ]
    }
  ]
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/catalog/products"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"

r = requests.get(f"{API}/catalog/products", timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/catalog/products`);
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Mua gói bằng số dư (dịch vụ mới, thêm lưu lượng hoặc gia hạn cổng)

`POST /v1/orders`

Luôn thanh toán bằng số dư trả trước: API tính giá (giá trong danh mục × `quantity`), trừ tiền trong số dư, tạo hoặc gia hạn dịch vụ và trả về đơn hàng `completed` cùng với `fulfillment`. Thông tin proxy có ngay lập tức.

- **Lưu lượng proxy dân cư mới**: `{ "planId": "res-10" }`.
- **Lưu lượng 4G/5G xoay vòng mới (mỗi GB)**: `{ "planId": "mgb-10" }` (gói đăng ký lưu lượng với `productId: "mobile-gb"`, được cung cấp trong `fulfillment.residentialSubscriptionId`).
- **Thêm lưu lượng vào gói đăng ký hiện có**: `{ "planId": "res-10", "options": { "subscriptionId": "res_9x2m4k" } }`: gói phải thuộc sản phẩm của gói đăng ký đó.
- **Cổng di động mới**: `{ "planId": "mob-us-30d", "quantity": 1, "options": { "country": "US" } }`, có thể kèm `carrier` (xem nhà mạng của một quốc gia trong [Cổng di động](https://localserpproxy.com/vi/docs/api/mobile/)). Gói theo khu vực chỉ áp dụng cho các quốc gia thuộc khu vực đó (`422` trên `options.country` nếu không).
- **Gia hạn cổng di động**: `{ "planId": "mob-us-7d", "options": { "portId": "mob_2v8k1q" } }` cộng thời hạn của gói vào `expiresAt`.

**Số dư không đủ → `402 insufficient_balance`**, kèm số tiền còn thiếu và đề xuất nạp thêm trong `error.details` (`missing`, `suggestedTopUp`). Không trừ tiền nếu xảy ra lỗi. Để thanh toán phần chênh lệch, hãy bắt đầu nạp tiền với cùng yêu cầu trong `purchase` (`POST /v1/topups`): gói sẽ được mua ngay khi tiền nạp được ghi có.

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | Không | Khóa duy nhất (ví dụ UUID) để thử lại POST an toàn. Được lưu trong 24 h. — tối đa 128 ký tự |

**Nội dung yêu cầu**

| Trường | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `planId` | string | Có | — |
| `quantity` | integer | Không | 1–100, mặc định `1` |
| `options` | object | Không | — |

*Ví dụ: Proxy dân cư*

```json
{
  "planId": "res-10"
}
```

*Ví dụ: Cổng di động*

```json
{
  "planId": "mob-us-30d",
  "quantity": 1,
  "options": {
    "country": "US",
    "carrier": "verizon",
    "autoRenew": true
  }
}
```

*Ví dụ: Gia hạn cổng*

```json
{
  "planId": "mob-us-7d",
  "options": {
    "portId": "mob_2v8k1q"
  }
}
```

*Ví dụ: Lưu lượng di động*

```json
{
  "planId": "mgb-10"
}
```

*Ví dụ: Cổng theo khu vực*

```json
{
  "planId": "mob-us-30d",
  "options": {
    "country": "US",
    "carrier": "verizon"
  }
}
```

**Phản hồi** `201 Created`

```json
{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Local team",
  "quantity": 1,
  "unitPrice": "7.50",
  "subtotal": "7.50",
  "discount": "0.00",
  "total": "7.50",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s -X POST "https://localserpproxy.com/api/v1/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"planId":"res-10"}'
```

*Python*

```python
import os, uuid
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4())}

r = requests.post(f"{API}/orders", headers=HEADERS, json={"planId": "res-10"}, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
import { randomUUID } from 'node:crypto';

const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders`, {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.API_KEY}`, 'Idempotency-Key': randomUUID(), 'Content-Type': 'application/json' },
  body: JSON.stringify({ planId: 'res-10' }),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Danh sách đơn hàng

`GET /v1/orders`

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `page` | query | integer | Không | ≥ 1, mặc định `1` |
| `perPage` | query | integer | Không | 1–100, mặc định `20` |
| `status` | query | `completed` · `cancelled` | Không | Đơn hàng được tạo ở trạng thái đã thanh toán (đã trừ tiền trong số dư). `completed` — đã thanh toán và được cung cấp (thông tin proxy có ngay lập tức). |
| `productId` | query | string | Không | ID sản phẩm trong danh mục. Giá trị dành cho LocalSERP Proxy: `residential` (GB), `mobile` (cổng 4G/5G chuyên dụng) và `mobile-gb` (lưu lượng 4G/5G xoay vòng tính theo GB). Khách hàng cần xử lý được các giá trị chưa xác định. |

**Phản hồi** `200 OK`

```json
{
  "data": [
    {
      "id": "ord_4f8k2m9q",
      "status": "completed",
      "productId": "residential",
      "planId": "res-10",
      "planName": "Local team",
      "quantity": 1,
      "unitPrice": "7.50",
      "subtotal": "7.50",
      "discount": "0.00",
      "total": "7.50",
      "promoCode": null,
      "currency": "USD",
      "topUpId": null,
      "options": {},
      "fulfillment": {
        "residentialSubscriptionId": "res_9x2m4k",
        "mobilePortIds": []
      },
      "createdAt": "2026-10-05T14:03:11Z",
      "paidAt": "2026-10-05T14:03:11Z"
    }
  ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/orders" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

## Lấy đơn hàng

`GET /v1/orders/{orderId}`

Xác thực: khóa API trong tiêu đề `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Trong | Kiểu | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `orderId` | path | string | Có | — |

**Phản hồi** `200 OK`

```json
{
  "id": "ord_4f8k2m9q",
  "status": "completed",
  "productId": "residential",
  "planId": "res-10",
  "planName": "Local team",
  "quantity": 1,
  "unitPrice": "7.50",
  "subtotal": "7.50",
  "discount": "0.00",
  "total": "7.50",
  "promoCode": null,
  "currency": "USD",
  "topUpId": null,
  "options": {},
  "fulfillment": {
    "residentialSubscriptionId": "res_9x2m4k",
    "mobilePortIds": []
  },
  "createdAt": "2026-10-05T14:03:11Z",
  "paidAt": "2026-10-05T14:03:11Z"
}
```

*curl*

```bash
curl -s "https://localserpproxy.com/api/v1/orders/ord_4f8k2m9q" \
  -H "Authorization: Bearer $API_KEY"
```

*Python*

```python
import os
import requests

API = "https://localserpproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['API_KEY']}"}

r = requests.get(f"{API}/orders/ord_4f8k2m9q", headers=HEADERS, timeout=30)
r.raise_for_status()
print(r.json())
```

*Node.js*

```javascript
// Node.js 18+ (built-in fetch), ES module
const API = 'https://localserpproxy.com/api/v1';

const res = await fetch(`${API}/orders/ord_4f8k2m9q`, {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? `HTTP ${res.status}`);
console.log(await res.json());
```

---

LocalSERP Proxy: LocalSERP Proxy là dịch vụ proxy dân cư tại Hoa Kỳ để kiểm tra kết quả tìm kiếm địa phương, quảng cáo và giá theo từng thành phố, thanh toán bằng tiền mã hóa và không cần tải lên giấy tờ tùy thân.