Tài liệu API v1

REST JSON, UTF-8. Base URL: https://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, gia hạn 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 (khuyến nghị, không bắt buộc gửi mật khẩu qua API tích hợp lâu dài).

Quy ước phản hồi

Endpoint tài khoản (shop): { "success": true|false, "data"?: …, "message"?: … }
Catalog proxy: { "ok": true, "data": { regions, products, templates, priceModes }, "store": … }
License runtime (client tool): { "active": true|false, … }
Giá proxy / gia hạn: chỉ trả giá bán (price_vnd, total_price_vnd). Không có giá gốc, chiết khấu hay payload nhà cung cấp.

API tích hợp nạp tiền (callback ngân hàng) và endpoint quản trị nội bộ không liệt kê tại đây — chỉ cấp khi triển khai. Rate limit áp dụng theo nhóm. Vượt ngưỡng → HTTP 429.

Công khai — health

GET Công khai /v1/public/health

Health check

Kiểm tra API đang chạy (load balancer, uptime monitor). Chỉ trả trạng thái running.

Ví dụ curl

curl "https://2movn.com/api/v1/public/health" \
  -H "Accept: application/json"

Phản hồi mẫu

{
  "status": "running"
}

POST Công khai /v1/public/proxy/socks5-test

Test proxy SOCKS5 (TCP/UDP)

Gọi máy chủ check proxy (Python). Không cần Bearer.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`proxy_socks5 / proxy`	body	Không	Chuỗi `ip:port:user:pass` hoặc `socks5://…`
`host + port`	body	Không	Thay cho chuỗi proxy
`transport`	body	Không	`tcp` \| `udp` \| `both`
`timeout`	body	Không	3–60 giây
`targets_list`	body	Không	dns_global, dns_asia, dns_vietnam, ntp, stun

Ví dụ curl

curl -X POST https://2movn.com/api/v1/public/proxy/socks5-test \
  -H "Content-Type: application/json" \
  -d '{"proxy_socks5":"1.2.3.4:8080:user:pass","transport":"tcp"}'

Phản hồi mẫu

{
  "ok": true,
  "summary": { … },
  "results": [ … ]
}

Công khai — catalog công cụ

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 "https://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 khai — catalog proxy/VPS

Cùng nguồn với https://2movn.com/cua-hang-proxy/catalog?type=PRIVATE_PROXY. Giá trong products[].prices là giá bán (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 "https://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.

Tài khoản — xác thực Bearer

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 https://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 https://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."
}

Tài khoản — mua công cụ

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.

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 https://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.

Tài khoản — quản lý license

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

Gia hạn license công cụ

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 https://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
  }
}

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 "https://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 "https://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 "https://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 "https://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."
}

Tài khoản — tải file công cụ

POST Bearer bắt buộc /v1/download/signed-link

Lấy URL tải có chữ ký

Trả URL ký thời hạn 5 phút. Chỉ license thuộc tài khoản Bearer.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`license_id`	body	Có	ID license đã mua

Ví dụ curl

curl -X POST https://2movn.com/api/v1/download/signed-link \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"license_id":55}'

Phản hồi mẫu

{
  "url": "https://2movn.com/api/v1/download/file/55?expires=…&signature=…"
}

GET Công khai /v1/download/file/{license_id}

Tải file (URL đã ký)

Không dùng Bearer — chỉ URL signed-link hợp lệ. Redirect hoặc stream file tool.

Ví dụ curl

curl -L "https://2movn.com/api/v1/download/file/55?expires=…&signature=…" -o tool.zip

Phản hồi mẫu

(binary file hoặc redirect 302)

Tài khoản — đặt mua proxy/VPS

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ó	≥7 ký tự, chữ In hoa + số
`pickIP`	body	Không	Chỉ SHARED_PROXY: mua lại IP đã sở hữu (quantity = 1)
`port`	body	Không	Bắt buộc private + VPS (mặc định 33333 / 3389)
`nodeCode`	body	Không	Tùy chọn catalog nâng cao
`poolCode`	body	Không	Tùy chọn catalog nâng cao
`hostName`	body	Không	VPS: tên máy; để trống → random
`enableBackup`	body	Không	boolean

Ví dụ curl

curl -X POST https://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"],
    "price_vnd": 30000
  }
}

HTTP 201. Proxy được gắn label = 2movn_{email}. Mua lại IP shared: gửi pickIP + quantity:1. Hết hàng / mật khẩu yếu / template bị ẩn → 422.

Tài khoản — proxy/VPS instance

Gia hạn: renew-info (xem giá) → renew (xác nhận). Điều khiển nguồn (private + VPS): action — start, stop, reset (khởi động lại).

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 "https://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 + thông tin kết nối

Trả metadata local và connection (user/pass/port) nếu tải được trạng thái live. Không trả payload nhà cung cấp thô.

Ví dụ curl

curl "https://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",
    "status": "running",
    "expires_at": "2026-06-20T00:00:00+00:00",
    "is_expired": false,
    "controls_locked": false,
    "connection": {
      "username": "user01",
      "password": "***",
      "port": 8080,
      "ipv4": "1.2.3.4"
    },
    "live_error": null
  }
}

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

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

Gửi lệnh bật / tắt / khởi động lại máy qua Server (PUT /vm/action). Khuyến nghị dùng reset để khởi động lại — upstream không có giá trị reboot.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`action`	body	Có	Khuyến nghị: `start` (bật), `stop` (tắt), `reset` (khởi động lại). Tương thích ngược: `reboot` → `reset`, `shutdown` → `stop`.

Ví dụ curl

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

Phản hồi mẫu

{
  "success": true,
  "message": "Đã gửi lệnh «Khởi động lại»."
}

Chỉ PRIVATE_PROXY và CLOUD_SERVER. Shared proxy → 422. Máy hết hạn → 422. Lỗi upstream (vd. VM không tồn tại) → 422 kèm message.

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ó	Không dùng PROXY_HTTP_NONE_AUTH
`password`	body	Có	≥7 ký tự, hoa + số
`port`	body	Có	1–65535
`hostName`	body	Không
`changeIP`	body	Không	boolean
`enableBackup`	body	Không	boolean

Ví dụ curl

curl -X POST "https://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."
}

Username không đổi (server giữ username hiện tại). Mật khẩu: >6 ký tự, có chữ In hoa và số. Template PROXY_HTTP_NONE_AUTH bị từ chối. Máy hết hạn → 422.

Tài khoản — gia hạn proxy/VPS

Luồng: (1) renew-info — xem giá & số dư → (2) renew — trừ ví và gia hạn theo chu kỳ hiện tại.

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

Xem giá gia hạn

Trả giá bán từng dịch vụ và tổng. Gọi trước renew.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vm_codes`	query hoặc body	Có	1–50 mã VM. GET: `?vm_codes=VM1`, nhiều mã `?vm_codes=VM1&vm_codes=VM2` hoặc `?vm_codes=VM1,VM2`. POST JSON: `{"vm_codes":["VM1","VM2"]}`

Ví dụ curl

# GET một VM
curl "https://2movn.com/api/v1/proxy/instances/renew-info?vm_codes=VM20260520001" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

# GET nhiều VM (lặp key)
curl "https://2movn.com/api/v1/proxy/instances/renew-info?vm_codes=VM20260520001&vm_codes=VM20260520002" \
  -H "Authorization: Bearer YOUR_TOKEN"

# POST (khuyến nghị)
curl -X POST https://2movn.com/api/v1/proxy/instances/renew-info \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vm_codes":["VM20260520001","VM20260520002"]}'

Phản hồi mẫu

{
  "success": true,
  "data": {
    "items": [
      {
        "vm_code": "VM20260520001",
        "vm_type": "PRIVATE_PROXY",
        "renew_period": "7 ngày",
        "ip_address": "1.2.3.4",
        "host_name": "proxy-01",
        "expires_at": "23/06/2026 20:20",
        "product_name": "Proxies Private",
        "price_vnd": 14000
      }
    ],
    "total_price_vnd": 14000,
    "balance": 943960
  }
}

renew_period mô tả thời gian gia hạn thêm (vd. «7 ngày»). Chỉ gia hạn được nếu còn hạn hoặc hết hạn ≤ 3 ngày; quá 3 ngày → 422.

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

Gia hạn proxy/VPS

Trừ ví theo giá renew-info và gia hạn các dịch vụ đã chọn.

Tham số

Tên	Vị trí	Bắt buộc	Mô tả
`vm_codes`	body	Có	Mảng mã VM thuộc tài khoản, 1–50

Ví dụ curl

curl -X POST https://2movn.com/api/v1/proxy/instances/renew \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vm_codes":["VM20260520001"]}'

Phản hồi mẫu

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

Một phần lỗi → VM lỗi được hoàn tiền. Số dư không đủ → 422.

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
Công khai
GET	`/v1/public/health`	—
POST	`/v1/public/proxy/socks5-test`	—
GET	`/v1/tools/catalog`	—
GET	`/v1/proxy/catalog` · `/v1/proxy/pricing`	—
Tài khoản — xác thực
POST	`/v1/auth/token`	—
DEL	`/v1/auth/token`	Bearer
Tài khoản — công cụ
POST	`/v1/tools/orders`	Bearer
POST	`/v1/tools/licenses/{id}/renew`	Bearer
GET	`/v1/tools/licenses`	Bearer
GET	`/v1/tools/licenses/{id}`	Bearer
GET	`/v1/tools/licenses/{id}/devices`	Bearer
DEL	`/v1/tools/licenses/{id}/devices/{deviceId}`	Bearer
POST	`/v1/download/signed-link`	Bearer
GET	`/v1/download/file/{license_id}`	URL ký
Tài khoản — proxy/VPS
POST	`/v1/proxy/orders`	Bearer
GET	`/v1/proxy/instances`	Bearer
GET	`/v1/proxy/instances/{vmCode}`	Bearer
POST	`/v1/proxy/instances/{vmCode}/action`	Bearer
POST	`/v1/proxy/instances/{vmCode}/reinstall`	Bearer
GETPOST	`/v1/proxy/instances/renew-info`	Bearer
POST	`/v1/proxy/instances/renew`	Bearer