Tài liệu API v1

REST JSON, UTF-8. Base URL: http://test.2movn.com/api

Đăng nhập Đăng ký

Content-Type: application/json Accept: application/json Bearer cho endpoint tài khoản

Giới thiệu

API cho phép tích hợp mua công cụ (license), đặt proxy/VPS và quản lý tài nguyên đã mua. Endpoint công khai không cần token; endpoint tài khoản gửi header Authorization: Bearer <token>.

Tạo token an toàn: đăng nhập → Khu người dùng → Token API (không bắt buộc gửi mật khẩu qua API).

Xác thực

POST Công khai /v1/auth/token

Cấp Bearer token

Đăng nhập bằng email/mật khẩu tài khoản, nhận token dùng cho các request sau. Không tạo session cookie web.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`email`	body	Có	Email đăng ký
`password`	body	Có	Mật khẩu
`token_name`	body	Có	Tên gợi nhớ (vd. `server-prod`)

Ví dụ curl

curl -X POST http://test.2movn.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "token_name": "my-integration"
  }'

Phản hồi mẫu

{
  "success": true,
  "token": "1|abcdefghijklmnopqrst…",
  "token_type": "Bearer",
  "user": {
    "id": 42,
    "email": "[email protected]",
    "name": "Nguyen Van A"
  }
}

Lưu token ngay khi nhận — không hiển thị lại. Tài khoản không active → 403.

DELETE Bearer bắt buộc /v1/auth/token

Thu hồi token hiện tại

Xóa đúng token đang dùng trong header Authorization.

Ví dụ curl

curl -X DELETE http://test.2movn.com/api/v1/auth/token \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "message": "Đã thu hồi token hiện tại."
}

Công cụ — catalog

GET Công khai /v1/tools/catalog

Danh sách công cụ & gói giá

Trả về công cụ status=active kèm gói active, sắp theo giá.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`q`	query	Không	Tìm theo tên/mô tả
`tool_category_id`	query	Không	Lọc danh mục
`access_mode`	query	Không	`free` hoặc `buy`

Ví dụ curl

curl "http://test.2movn.com/api/v1/tools/catalog?access_mode=buy&q=proxy" \
  -H "Accept: application/json"

Phản hồi mẫu

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Tool Example",
      "slug": "tool-example",
      "description": "Mô tả ngắn",
      "access_mode": "buy",
      "tool_code": "TOOL001",
      "category": { "id": 2, "name": "Tiện ích" },
      "packages": [
        {
          "id": 10,
          "name": "1 tháng",
          "price": 99000,
          "duration_type": "month",
          "duration_value": 1,
          "max_devices": 2
        }
      ]
    }
  ]
}

Công cụ access_mode=free không mua qua API shop.

Công cụ — mua & gia hạn

POST Bearer bắt buộc /v1/tools/orders

Mua license công cụ

Trừ số dư ví, tạo license + mã kích hoạt. Áp dụng chiết khấu rate_buy_discount của user.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`tool_id`	body	Có	ID từ catalog
`package_id`	body	Có	ID gói trong `packages[]`

Ví dụ curl

curl -X POST http://test.2movn.com/api/v1/tools/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool_id":1,"package_id":10}'

Phản hồi mẫu

{
  "success": true,
  "data": {
    "license_id": 55,
    "key_license": "XXXX-YYYY-ZZZZ",
    "expired_at": "2026-06-20T10:00:00+00:00",
    "max_devices": 2,
    "transaction_code": "TXNABC123",
    "amount": 89100
  }
}

HTTP 201. Số dư không đủ → 402.

POST Bearer bắt buộc /v1/tools/licenses/{license_id}/renew

Gia hạn license

Gia hạn license thuộc tài khoản; license_id là số trong URL.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`license_id`	path	Có	ID license
`package_id`	body	Có	Gói gia hạn (có thể khác gói ban đầu nếu cùng tool)

Ví dụ curl

curl -X POST http://test.2movn.com/api/v1/tools/licenses/55/renew \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"package_id":10}'

Phản hồi mẫu

{
  "success": true,
  "data": {
    "license_id": 55,
    "expired_at": "2026-07-20T10:00:00+00:00",
    "transaction_code": "TXNRENEW01",
    "amount": 89100
  }
}

Công cụ — license & thiết bị

GET Bearer bắt buộc /v1/tools/licenses

Danh sách license

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`per_page`	query	Không	1–100, mặc định 20

Ví dụ curl

curl "http://test.2movn.com/api/v1/tools/licenses?per_page=20" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

Phản hồi mẫu

{
  "success": true,
  "data": [
    {
      "id": 55,
      "key_license": "XXXX-YYYY",
      "status": "active",
      "max_devices": 2,
      "current_devices": 1,
      "expired_at": "2026-06-20T10:00:00+00:00",
      "tool": { "id": 1, "name": "Tool", "tool_code": "T1" },
      "package": { "id": 10, "name": "1 tháng" },
      "devices": []
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 1
  }
}

GET Bearer bắt buộc /v1/tools/licenses/{license_id}

Chi tiết license

Ví dụ curl

curl "http://test.2movn.com/api/v1/tools/licenses/55" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "data": { "id": 55, "key_license": "…", "devices": [ … ] }
}

GET Bearer bắt buộc /v1/tools/licenses/{license_id}/devices

Danh sách thiết bị đã kích hoạt

Ví dụ curl

curl "http://test.2movn.com/api/v1/tools/licenses/55/devices" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "data": [
    {
      "id": 1,
      "device_id": "machine-uuid-abc",
      "status": "active",
      "first_active": "2026-05-01T08:00:00+00:00",
      "last_check": "2026-05-20T12:00:00+00:00"
    }
  ]
}

DELETE Bearer bắt buộc /v1/tools/licenses/{license_id}/devices/{deviceId}

Gỡ / reset thiết bị

deviceId là mã thiết bị (chuỗi) đã đăng ký.

Ví dụ curl

curl -X DELETE "http://test.2movn.com/api/v1/tools/licenses/55/devices/machine-uuid-abc" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "message": "Đã xóa thiết bị khỏi license."
}

Proxy / VPS — catalog

Cùng nguồn với http://test.2movn.com/cua-hang-proxy/catalog?type=PRIVATE_PROXY. Giá trong products[].prices là giá bán lẻ (cache ~5 phút).

GET Công khai /v1/proxy/catalog · /v1/proxy/pricing

Catalog khu vực, gói, template

Hai URL cùng handler. Tham số vm_type hoặc type bắt buộc.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vm_type / type`	query	Có	`PRIVATE_PROXY` \| `SHARED_PROXY` \| `CLOUD_SERVER`

Ví dụ curl

curl "http://test.2movn.com/api/v1/proxy/catalog?vm_type=PRIVATE_PROXY" \
  -H "Accept: application/json"

Phản hồi mẫu

{
  "ok": true,
  "data": {
    "regions": [
      {
        "code": "REGION_VN_HN",
        "name": "FPT Hà Nội",
        "subName": "Việt Nam",
        "outOfStock": false,
        "vmTypes": ["PRIVATE_PROXY", "SHARED_PROXY"]
      }
    ],
    "products": [
      {
        "code": "PRODUCT_163",
        "type": "PRIVATE_PROXY",
        "regionCode": "REGION_VN_HN",
        "name": "Proxies Private",
        "prices": [
          { "mode": "DAILY", "price": 14000 },
          { "mode": "MONTHLY", "price": 30000 }
        ]
      }
    ],
    "templates": [
      {
        "code": "TP007",
        "name": "HTTP",
        "codeRegions": ["REGION_VN_HN"],
        "vmTypes": ["PRIVATE_PROXY"]
      }
    ],
    "priceModes": ["DAILY", "MONTHLY"]
  },
  "error": null,
  "store": {
    "out_of_stock_region_codes": [],
    "out_of_stock_product_codes": []
  }
}

Dùng regions[].code → regionCode, products[].code → productCode, templates[].code → templateCode khi đặt mua.

Proxy / VPS — đặt mua

POST Bearer bắt buộc /v1/proxy/orders

Đặt mua proxy hoặc VPS

Tham số giống form web. Kiểm tra store.out_of_stock_* trong catalog trước khi gọi.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vmType`	body	Có	PRIVATE_PROXY \| SHARED_PROXY \| CLOUD_SERVER
`quantity`	body	Có	1–100
`regionCode`	body	Có	Từ catalog
`productCode`	body	Có	Từ catalog
`templateCode`	body	Có	Từ catalog
`priceMode`	body	Có	DAILY, MONTHLY, …
`username`	body	Không	Bắt buộc proxy private/shared
`password`	body	Có
`port`	body	Không	Bắt buộc private + VPS
`enableBackup`	body	Không	boolean

Ví dụ curl

curl -X POST http://test.2movn.com/api/v1/proxy/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vmType": "PRIVATE_PROXY",
    "quantity": 1,
    "regionCode": "REGION_VN_HN",
    "productCode": "PRODUCT_163",
    "templateCode": "TP007",
    "priceMode": "MONTHLY",
    "username": "user01",
    "password": "SecurePass1",
    "port": 8080
  }'

Phản hồi mẫu

{
  "success": true,
  "data": {
    "vm_codes": ["VM20260520001"],
    "charged_vnd": 30000
  }
}

HTTP 201. Hết hàng / lỗi upstream → 422.

Proxy / VPS — instance

GET Bearer bắt buộc /v1/proxy/instances

Danh sách instance đã mua

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vm_type`	query	Không	Lọc loại VM
`per_page`	query	Không	1–100, mặc định 30

Ví dụ curl

curl "http://test.2movn.com/api/v1/proxy/instances?vm_type=PRIVATE_PROXY" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "data": [
    {
      "vm_code": "VM20260520001",
      "vm_type": "PRIVATE_PROXY",
      "host_name": "proxy-01",
      "ip_address": "1.2.3.4",
      "status": "running",
      "expires_at": "2026-06-20T00:00:00+00:00"
    }
  ],
  "meta": { "current_page": 1, "total": 1 }
}

GET Bearer bắt buộc /v1/proxy/instances/{vmCode}

Chi tiết instance + snapshot upstream

Trường upstream là JSON VietServer đã mask giá bán lẻ.

Ví dụ curl

curl "http://test.2movn.com/api/v1/proxy/instances/VM20260520001" \
  -H "Authorization: Bearer YOUR_TOKEN"

Phản hồi mẫu

{
  "success": true,
  "data": {
    "vm_code": "VM20260520001",
    "vm_type": "PRIVATE_PROXY",
    "ip_address": "1.2.3.4",
    "upstream": { … },
    "upstream_error": null
  }
}

POST Bearer bắt buộc /v1/proxy/instances/{vmCode}/action

Điều khiển nguồn (private + VPS)

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`action`	body	Có	`start` \| `stop` \| `shutdown` \| `reset` \| `reboot`

Ví dụ curl

curl -X POST "http://test.2movn.com/api/v1/proxy/instances/VM20260520001/action" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

Phản hồi mẫu

{
  "success": true,
  "message": "Đã gửi lệnh «reboot»."
}

Shared proxy không hỗ trợ endpoint này.

POST Bearer bắt buộc /v1/proxy/instances/{vmCode}/reinstall

Cài lại OS (private + VPS)

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`templateCode`	body	Có
`password`	body	Có
`port`	body	Có	1–65535
`hostName`	body	Không
`username`	body	Không
`changeIP`	body	Không	boolean
`enableBackup`	body	Không	boolean

Ví dụ curl

curl -X POST "http://test.2movn.com/api/v1/proxy/instances/VM20260520001/reinstall" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"templateCode":"TP007","password":"NewPass1","port":8080}'

Phản hồi mẫu

{
  "success": true,
  "message": "Đã cài lại."
}

POST Bearer bắt buộc /v1/proxy/instances/renew

Gia hạn hàng loạt

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vm_codes`	body	Có	Mảng mã VM, tối đa 50
`price_mode`	body	Có	vd. MONTHLY

Ví dụ curl

curl -X POST http://test.2movn.com/api/v1/proxy/instances/renew \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vm_codes":["VM001","VM002"],"price_mode":"MONTHLY"}'

Phản hồi mẫu

{
  "success": true,
  "renewed": 2,
  "message": "Đã gia hạn."
}

Mã lỗi HTTP

Mã	Ý nghĩa
`401`	Thiếu hoặc sai Bearer token
`402`	Số dư ví không đủ (mua tool / proxy)
`403`	Tài khoản không active (cấp token)
`404`	Không tìm thấy resource hoặc không thuộc tài khoản
`422`	Dữ liệu không hợp lệ, hết hàng, lỗi nhà cung cấp
`429`	Quá giới hạn rate limit

Bảng tra nhanh

	Endpoint	Auth
POST	`/v1/auth/token`	—
DEL	`/v1/auth/token`	Bearer
GET	`/v1/tools/catalog`	—
POST	`/v1/tools/orders`	Bearer
POST	`/v1/tools/licenses/{id}/renew`	Bearer
GET	`/v1/tools/licenses`	Bearer
GET	`/v1/proxy/catalog`	—
POST	`/v1/proxy/orders`	Bearer
GET	`/v1/proxy/instances`	Bearer
POST	`/v1/proxy/instances/{vmCode}/action`	Bearer