Tài liệu tích hợp chính thức

Tích hợp Cloud247 API từ xác thực đến webhook

Hướng dẫn đầy đủ các luồng tạo đơn hàng, gia hạn dịch vụ, nâng cấp addon và nhận sự kiện qua webhook. Đặc tả chi tiết từng request và response theo chuẩn OpenAPI 3.1 nằm ở phần cuối trang.

Base URL https://api.cloud247.vn/v1
Xác thực Authorization: Bearer <token>
Định dạng kết quả {"data": {...}}

Bắt đầu nhanh

Ba bước để gọi API

Hệ thống API hoạt động độc lập, không dùng session, cookie hay CSRF như trang Portal. Ngoại trừ bước cấp token, mọi request đều dùng Bearer token và giao tiếp hoàn toàn bằng JSON.

1

Cấp token đúng quyền

Gọi POST /auth/tokens bằng email hoặc username. Chỉ khai báo những quyền (abilities) thực sự cần dùng và bảo mật token cẩn thận vì token gốc chỉ hiển thị một lần.

2

Lấy ngữ cảnh & tùy chọn

Dùng GET /context, chi tiết sản phẩm và tùy chọn dịch vụ để lấy danh sách ngôn ngữ, tiền tệ, chu kỳ, addon, datacenter và hệ điều hành hợp lệ trước khi gửi đơn.

3

Gửi thao tác an toàn

Sinh một khóa Idempotency-Key riêng cho từng yêu cầu để tránh chạy trùng khi gửi lại. Có thể gửi kèm Quote-Fingerprint nếu cần khóa đúng mức giá đã báo.

Mọi phản hồi JSON thành công đều bọc trong khóa data; danh sách phân trang có thêm links và meta. Khi có lỗi, hệ thống trả về chuẩn application/problem+json và không bọc trong data.

Quy chuẩn tích hợp

Những quy ước cần lưu ý

Ngôn ngữ và đơn vị tiền tệ

Truyền header Accept-Language: vi hoặc en để chọn ngôn ngữ phản hồi. Header X-Currency dùng khi lấy context, xem bảng giá catalog và bắt buộc phải có khi gọi POST /order-quotes hoặc POST /orders. Các dịch vụ đang hoạt động và hóa đơn đã tạo luôn giữ nguyên đơn vị tiền tệ ban đầu của chính nó.

Biểu phí và chính sách dịch vụ

GET /context trả về mục data.settings. Trong đó, fees chứa biểu phí đổi IP (tính trên từng IP), phí chuyển quyền sở hữu và phần trăm phí chuyển ví thu từ người gửi. Hai khoản phí thao tác này chưa bao gồm thuế — hãy dùng API báo giá thao tác để lấy tổng số tiền cuối cùng.

Mục service_policy cung cấp các quy tắc chung về tự gia hạn, tạm khóa, xóa dịch vụ quá hạn, ngưỡng thời hạn tối thiểu để mở quyền lợi VM và thời gian chờ hoàn tiền tự động khi khởi tạo lỗi (tất cả đơn vị tính bằng phút). Thời gian giữ trước khi xóa tính từ lúc hết hạn và chỉ có hiệu lực khi expired_termination.enabled là true. Đây là quy định mặc định để tham khảo; mốc thời gian thực tế có thể khác tùy gói dịch vụ. Lưu ý thời gian chờ hoàn tiền khi lỗi khởi tạo không phải là chính sách dùng thử.

Quy trình đặt hàng mới

Chỉ cần gọi GET /catalog/products/{product} một lần theo tiền tệ đã chọn: kết quả đã bao gồm đầy đủ bảng giá theo mọi chu kỳ của gói chính và addon, cùng danh sách datacenter / hệ điều hành trong configuration_options. Khi đổi chu kỳ trên giao diện, hãy lọc theo billing_cycle_id ngay trên dữ liệu vừa tải thay vì gọi lại API. Khi thanh toán, POST /order-quotes là bước kiểm tra tùy chọn, còn POST /orders luôn tự động tính lại giá mới nhất ngay thời điểm lập đơn. Bạn có thể gộp nhiều VM, Hosting và Proxy vào cùng mảng items; trường promotion_code ở cấp ngoài cùng áp dụng cho toàn bộ đơn hàng.

Với mỗi phần tử trong items[], mảng units phải có số lượng phần tử khớp đúng bằng qty. Trong items[].units[].configuration, mỗi VM cần truyền hostname, còn mỗi Hosting cần cả domain và username (username Hosting dài 3–16 ký tự, bắt đầu bằng chữ thường, chỉ gồm chữ thường và chữ số, đồng thời 8 ký tự đầu phải là duy nhất).

items[].configuration.password đóng vai trò là mật khẩu mặc định cho tất cả dịch vụ trong mục đó. Chỉ truyền items[].units[].configuration.password khi có đơn vị cần mật khẩu riêng; nếu bỏ qua hoặc để null, đơn vị đó sẽ tự kế thừa mật khẩu mặc định.

Bước báo giá chỉ kiểm tra tính khả dụng của hostname VM, tên miền và username Hosting chứ chưa giữ chỗ. Khi gọi POST /orders, hệ thống sẽ giữ chỗ đồng thời các thông tin này trong thời gian đơn chờ thanh toán và tự nhả ra nếu đơn bị hủy hoặc quá hạn. Nếu thanh toán lại sau khi hết hạn giữ chỗ, hệ thống sẽ kiểm tra lại khả dụng trước khi trừ tiền.

Gia hạn và mua thêm Addon

Khi gia hạn, truyền chu kỳ đích qua target_billing_cycle_id. Thao tác mua addon dùng addons[].addon_id kèm số lượng tăng thêm qty và không làm thay đổi chu kỳ hay ngày hết hạn của gói chính. Hãy kiểm tra giới hạn số lượng hợp lệ trước tại GET /services/{service}/upgrade-options.

Chống trùng lặp (Idempotency) và khóa giá (Quote-Fingerprint)

  • Bạn tự tạo giá trị Idempotency-Key cho mỗi thao tác. Chỉ dùng lại đúng khóa cũ khi cần gửi lại (retry) đúng request bị gián đoạn; thao tác mới phải dùng khóa mới.
  • Header Quote-Fingerprint là tùy chọn khi đặt hàng, gia hạn hoặc mua addon. Nếu có truyền mà giá hoặc cấu hình đã thay đổi, API sẽ trả về lỗi 409 quote_changed để bạn xác nhận lại với khách.
  • Nếu không gửi Quote-Fingerprint, hệ thống hiểu là bạn đồng ý thanh toán theo mức giá tính lại tại thời điểm gửi lệnh.

Tích hợp Webhook

Đăng ký URL HTTPS công khai qua POST /webhooks và lưu ngay chuỗi bí mật whsec_* vì khóa này chỉ hiển thị duy nhất một lần lúc tạo. Phía máy chủ nhận webhook cần kiểm tra chữ ký HMAC trên raw body, xác thực timestamp để tránh replay attack và chống xử lý trùng dựa trên trường id trong JSON payload đã xác minh (có thể đối chiếu thêm với header event ID).

Laravel 12

Code mẫu tích hợp

Bộ code mẫu dùng Laravel HTTP Client chuẩn, chỉ cần chép về và thay ID, token, URL theo tài khoản của bạn.

1a. Khai báo cấu hình Cloud247 · Thêm vào file config/services.php
'cloud247' => [
    'base_url' => env('CLOUD247_API_URL', 'https://api.cloud247.vn/v1'),
    'token' => env('CLOUD247_API_TOKEN'),
    'locale' => env('CLOUD247_API_LOCALE', 'vi'),
    'currency' => env('CLOUD247_API_CURRENCY', 'VND'),
    'webhook_secret' => env('CLOUD247_WEBHOOK_SECRET'),
],
1b. Tạo HTTP Client dùng chung · app/Services/Cloud247Api.php
<?php

namespace App\Services;

use Illuminate\Http\Client\PendingRequest;
use Illuminate\Support\Facades\Config;
use Illuminate\Support\Facades\Http;

final class Cloud247Api
{
    /**
     * @param array<string, string> $headers
     */
    public function request(array $headers = []): PendingRequest
    {
        return Http::baseUrl(
            rtrim(Config::string('services.cloud247.base_url'), '/') . '/',
        )
            ->acceptJson()
            ->asJson()
            ->withToken(Config::string('services.cloud247.token'))
            ->withHeaders([
                'Accept-Language' => Config::string('services.cloud247.locale'),
                ...$headers,
            ])
            ->timeout(30);
    }

    /**
     * @param array<string, string> $headers
     */
    public function pricedRequest(array $headers = []): PendingRequest
    {
        return $this->request([
            'X-Currency' => Config::string('services.cloud247.currency'),
            ...$headers,
        ]);
    }
}
2. Cấp API token · Token gốc chỉ hiển thị duy nhất một lần
<?php

use Illuminate\Support\Facades\Http;

$issued = Http::baseUrl('https://api.cloud247.vn/v1/')
    ->acceptJson()
    ->asJson()
    ->post('auth/tokens', [
        'identifier' => 'customer@example.com',
        'password' => 'your-password',
        'device_name' => 'Production integration',
        'abilities' => [
            'catalog:read',
            'orders:create',
            'orders:read',
            'services:read',
            'services:renew',
            'services:upgrade',
            'webhooks:manage',
        ],
    ])
    ->throw()
    ->json('data');

// Store this value securely. It cannot be retrieved again.
$accessToken = $issued['access_token'];
3. Xem bảng giá, báo giá & tạo đơn hàng · Header Quote-Fingerprint là tùy chọn
<?php

use App\Services\Cloud247Api;
use Illuminate\Support\Str;

$api = app(Cloud247Api::class);
$productId = 12;
$billingCycleId = 3;

// X-Currency is used only for request context, catalog, and new-order checkout requests.
// One response contains all-cycle product/addon pricing and configuration options.
$product = $api->pricedRequest()
    ->get("catalog/products/{$productId}")
    ->throw()
    ->json('data');

// On cycle changes, select matching rows from $product['pricings'] and
// $product['addons'][*]['pricings']; do not request the catalog again.

$orderPayload = [
    'items' => [
        [
            'product_id' => $productId,
            'billing_cycle_id' => $billingCycleId,
            'qty' => 2,
            'auto_renew' => true,
            'configuration' => [
                // Required default password; a unit may override it.
                'password' => 'ChangeMe-Strong-Password',
                'datacenter_id' => 2,
                'operating_system_id' => 5,
            ],
            'units' => [
                [
                    'configuration' => ['hostname' => 'api-vm-01.example.com'],
                ],
                [
                    'configuration' => [
                        'hostname' => 'api-vm-02.example.com',
                        'password' => 'A-Different-Strong-Password',
                    ],
                ],
            ],
            'addons' => [
                ['addon_id' => 8, 'qty' => 2],
            ],
        ],
    ],
    // One code applies to the complete multi-product order.
    'promotion_code' => null,
];

$lockDisplayedPrice = true;
$fingerprint = $lockDisplayedPrice
    ? $api->pricedRequest()
        ->post('order-quotes', $orderPayload)
        ->throw()
        ->json('data.quote_fingerprint')
    : null;

$headers = ['Idempotency-Key' => (string) Str::uuid()];

if (is_string($fingerprint)) {
    $headers['Quote-Fingerprint'] = $fingerprint;
}

$order = $api->pricedRequest($headers)
    ->post('orders', $orderPayload)
    ->throw()
    ->json('data');
4. Gia hạn và mua thêm addon · Bước xem trước và xác nhận dùng cùng payload
<?php

use App\Services\Cloud247Api;
use Illuminate\Support\Str;

$api = app(Cloud247Api::class);
$serviceId = 123;

// Renewal
$renewalPayload = [
    'target_billing_cycle_id' => 3,
    'promotion_code' => null,
];

$renewalFingerprint = $api->request()
    ->post("services/{$serviceId}/renewals/preview", $renewalPayload)
    ->throw()
    ->json('data.quote_fingerprint');

$renewal = $api->request([
    'Idempotency-Key' => (string) Str::uuid(),
    'Quote-Fingerprint' => $renewalFingerprint,
])
    ->post("services/{$serviceId}/renewals", $renewalPayload)
    ->throw()
    ->json('data');

// Addon purchase: qty is the additional quantity.
$upgradeOptions = $api->request()
    ->get("services/{$serviceId}/upgrade-options")
    ->throw()
    ->json('data');

$addonPayload = [
    'addons' => [
        ['addon_id' => 8, 'qty' => 2],
    ],
    'promotion_code' => null,
];

$addonFingerprint = $api->request()
    ->post("services/{$serviceId}/upgrades/preview", $addonPayload)
    ->throw()
    ->json('data.quote_fingerprint');

$operation = $api->request([
    'Idempotency-Key' => (string) Str::uuid(),
    'Quote-Fingerprint' => $addonFingerprint,
])
    ->post("services/{$serviceId}/upgrades/addons", $addonPayload)
    ->throw()
    ->json('data');
5a. Đăng ký URL nhận webhook · Chuỗi secret chỉ trả về duy nhất một lần
<?php

use App\Services\Cloud247Api;

$api = app(Cloud247Api::class);

// Register once. Persist data.secret encrypted because it is shown once.
$endpoint = $api->request()
    ->post('webhooks', [
        'name' => 'Production events',
        'url' => 'https://partner.example.com/api/webhooks/cloud247',
        'events' => [
            'order.updated',
            'invoice.updated',
            'service.updated',
            'service.operation.updated',
            'wallet.balance.updated',
        ],
    ])
    ->throw()
    ->json('data');

$signingSecret = $endpoint['secret'];
5b. Khai báo route nhận webhook · routes/api.php
<?php

use App\Http\Controllers\Cloud247WebhookController;
use Illuminate\Support\Facades\Route;

Route::post('webhooks/cloud247', Cloud247WebhookController::class);
5c. Xác minh và xử lý webhook · Xác minh chữ ký HMAC trực tiếp trên raw body
<?php

namespace App\Http\Controllers;

use App\Jobs\ProcessCloud247Webhook;
use Illuminate\Http\Request;
use Illuminate\Http\Response;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Config;
use Throwable;

final class Cloud247WebhookController
{
    public function __invoke(Request $request): Response
    {
        $timestamp = $request->header('X-Cloud247-Timestamp');
        $signature = $request->header('X-Cloud247-Signature');

        abort_unless(
            is_string($timestamp)
                && ctype_digit($timestamp)
                && is_string($signature),
            401,
        );

        abort_if(abs(now()->timestamp - (int) $timestamp) > 300, 401);

        $expected = 'v1=' . hash_hmac(
            'sha256',
            $timestamp . '.' . $request->getContent(),
            Config::string('services.cloud247.webhook_secret'),
        );

        abort_unless(hash_equals($expected, $signature), 401);

        $payload = $request->json()->all();
        $eventId = data_get($payload, 'id');
        $eventType = data_get($payload, 'type');

        abort_unless(
            is_string($eventId)
                && $eventId !== ''
                && is_string($eventType)
                && $eventType !== ''
                && $request->header('X-Cloud247-Event-Id') === $eventId
                && $request->header('X-Cloud247-Event') === $eventType,
            401,
        );

        $dedupeKey = "cloud247:webhook:{$eventId}";

        if (! Cache::add($dedupeKey, true, now()->addDays(7))) {
            return response()->noContent();
        }

        try {
            ProcessCloud247Webhook::dispatch(
                eventId: $eventId,
                type: $eventType,
                payload: $payload,
            );
        } catch (Throwable $exception) {
            Cache::forget($dedupeKey);

            throw $exception;
        }

        return response()->noContent();
    }
}
Trong môi trường production, nên lưu mã sự kiện (event ID) vào một bảng database có unique index thay vì cache để chống xử lý trùng ngay cả khi khởi động lại hệ thống hoặc xóa cache.

Proxy · API

Mua và quản lý Proxy qua API

Xem danh sách gói Proxy đang mở bán qua GET /v1/catalog/products?type=proxy, sau đó gọi API chi tiết sản phẩm để lấy chu kỳ, giao thức và chế độ xác thực hỗ trợ. Luồng đặt mua vẫn dùng chung quy trình chuẩn: POST /v1/order-quotes → POST /v1/orders → POST /v1/orders/{order}/payments. Giá và tồn kho sẽ được kiểm tra lại lúc tạo đơn; bước báo giá không giữ chỗ.

Ví dụ bên dưới minh họa một phần tử trong mảng items (thay product_id và billing_cycle_id theo catalog thực tế). Mỗi phần tử trong units tương ứng với một Proxy. Nếu chọn ip_allowlist, không gửi username/password; còn hai chế độ kết hợp (AND/OR) yêu cầu đủ cả tài khoản lẫn danh sách IP.

Cấu hình một Proxy mẫu
{
  "product_id": 123,
  "billing_cycle_id": 1,
  "qty": 1,
  "auto_renew": false,
  "configuration": {
    "protocol": "http",
    "auth_mode": "userpass_and_ip_allowlist",
    "password": "Example-Only-ChangeMe!42"
  },
  "units": [{
    "configuration": {
      "username": "customer_proxy01",
      "allowed_cidrs": ["203.0.113.10/32"]
    }
  }],
  "addons": []
}

userpass · ip_allowlist · userpass_and_ip_allowlist · userpass_or_ip_allowlist

Chế độ AND yêu cầu khớp cả tài khoản lẫn IP cho phép; chế độ OR chỉ cần một trong hai. Chỉ sử dụng chế độ xác thực và giao thức nằm trong danh sách gói hỗ trợ.

Dịch vụ chung

Tham số {service} luôn là ID dịch vụ chung trên hệ thống, không phải ID bản ghi nội bộ của Proxy. Chẳng hạn, GET /v1/services/123 trả về toàn bộ thông tin chung kèm đối tượng data.detail chứa cấu hình kết nối và trạng thái hiện tại của Proxy — không cần và không có endpoint GET /v1/services/123/proxy riêng.

EndpointChức năng / Quyền cần có
GET /v1/services/{service}Xem chi tiết đầy đủ của dịch vụ, bao gồm data.detail theo từng loại · services:read
GET /v1/services/{service}/maintenance-optionsKiểm tra các thao tác được hỗ trợ và lý do nếu tạm khóa · services:read
GET /v1/services/{service}/operations
GET /v1/services/{service}/operations/{operation}
Theo dõi tiến độ tác vụ bất đồng bộ (đổi IP, đổi cấu hình truy cập...) · services:read

Chức năng riêng của Proxy

Nhóm endpoint /proxy/ phục vụ riêng cho trạng thái kết nối và các thao tác đặc thù của Proxy; các API dịch vụ chung ở trên vẫn dùng song song bình thường.

EndpointChức năng / Quyền cần có
GET /v1/services/{service}/proxy/statusĐọc trạng thái đã lưu gần nhất và xếp lịch làm mới ngầm nếu đủ điều kiện · services:read
GET /v1/services/{service}/proxy/rotations/quote
POST /v1/services/{service}/proxy/rotations
Báo phí và gửi lệnh đổi IP mới khi gói hỗ trợ · services:control
POST /v1/services/{service}/proxy/access-configurationsCập nhật username, new_password hoặc allowed_cidrs đúng theo chế độ đang bật · services:control

Lưu ý rằng /proxy/status trả về bản ghi đã lưu và giới hạn tần suất làm mới ngầm, không gọi trực tiếp sang máy chủ đích ngay trong lúc đọc. Khi cần lấy thông tin gói, hạn sử dụng và cấu hình đầy đủ, hãy dùng GET /v1/services/{service}.

Ví dụ quy trình đổi IP cho dịch vụ 123

  1. Gọi GET /v1/services/123/maintenance-options để xác nhận thao tác đổi IP đang khả dụng.
  2. Lấy thông tin báo phí tại GET /v1/services/123/proxy/rotations/quote.
  3. Gửi POST /v1/services/123/proxy/rotations kèm Idempotency-Key và giá trị accepted_quote còn hạn. Mã 202 trả về mã tác vụ tại data.operation.id.
  4. Nếu mã tác vụ là 456, theo dõi GET /v1/services/123/operations/456 cho đến khi hoàn tất rồi đọc lại chi tiết hoặc trạng thái Proxy để nhận thông tin kết nối mới (tránh coi mã 202 là đã đổi IP xong).

Mọi request POST đổi IP hoặc đổi thông tin truy cập đều bắt buộc có Idempotency-Key để retry an toàn khi rớt mạng. Nếu lần đổi IP có tính phí, phải truyền nguyên giá trị accepted_quote từ bước báo giá (không gửi kèm IP muốn chọn). Khi đổi thông tin mà muốn giữ nguyên mật khẩu cũ, hãy bỏ trống key new_password thay vì gửi chuỗi rỗng.

Mã phản hồi 202 chỉ xác nhận hệ thống đã tiếp nhận lệnh; cần theo dõi trạng thái tác vụ cho tới khi kết thúc. Đơn hàng mới chỉ trừ tiền và kích hoạt sau khi cấp phát thành công. Trong quá trình sử dụng, nếu trạng thái kết nối tạm thời chưa xác định thì không đồng nghĩa dịch vụ đã bị hủy. Khi cấu hình client, dùng giá trị endpoint để kết nối; egress_ip là IP đầu ra thực tế đã ghi nhận.

Proxy dùng chung toàn bộ các API bật/tắt tự gia hạn, gia hạn và hủy dịch vụ; hiện chưa áp dụng các API của VM/Hosting, mua addon hoặc chuyển nhượng cho Proxy. Mật khẩu đầy đủ nằm trong trường detail.password_hint ở API chi tiết hoặc status (API danh sách không trả về mật khẩu và allowlist).

VM console · noVNC

Tích hợp console VNC trực tiếp lên website của bạn

Gọi API để lấy ticket truy cập, sau đó dùng thư viện noVNC kết nối trực tiếp qua WebSocket của Cloud247.

Gọi POST /v1/services/{service}/maintenance/console-sessions từ backend bằng Bearer token có ability services:control (tài khoản phải sở hữu dịch vụ và có quyền services.control). Request này không cần body, cookie, CSRF hay Idempotency-Key.

Tuyệt đối giữ API token ở phía backend. Hệ thống của bạn cần kiểm tra quyền sở hữu của người dùng đang đăng nhập trước khi cấp ticket console về trình duyệt; xem URL, ticket và mật khẩu console là thông tin nhạy cảm, không ghi log hay lưu cache công khai.

1. Backend gọi lấy ticket console
curl --request POST \
  'https://api.cloud247.vn/v1/services/123/maintenance/console-sessions' \
  --header 'Authorization: Bearer <API_TOKEN>' \
  --header 'Accept: application/json'
Laravel HTTP Client · backend
<?php

use Illuminate\Support\Facades\Http;

// Authorize the signed-in customer's access to this service first.
$serviceId = 123;
$console = Http::baseUrl('https://api.cloud247.vn/v1')
    ->withToken(config('services.cloud247.token'))
    ->acceptJson()
    ->post("services/{$serviceId}/maintenance/console-sessions")
    ->throw()
    ->json('data');
Trường dữ liệuCách sử dụng
data.endpoint.web_urlURL WebSocket hoàn chỉnh (đã kèm token). Truyền nguyên chuỗi này vào noVNC.
data.endpoint.web_url_fallbackURL WebSocket dự phòng dùng khi đường dẫn chính gặp sự cố kết nối.
data.endpoint.passwordMật khẩu phiên VNC, truyền vào tham số credentials.password của noVNC.
data.session.expires_at
data.endpoint.ttl_seconds
Thời điểm hết hạn ticket (ISO 8601) và số giây hiệu lực còn lại.
data.endpoint.connection_typeDùng noVNC cho loại native_vnc; nếu là webmks/vmrc thì dùng client tương ứng. Nhớ kiểm tra null trước khi đọc các trường tùy chọn.

Kết nối qua WebSocket Cloud247

Chỉ cần cài gói @novnc/novnc ở frontend mà không phải tự dựng máy chủ WebSocket riêng. Ví dụ dưới minh họa cách gắn console vào phần tử #console có chiều cao xác định.

2. noVNC · JavaScript
import RFB from '@novnc/novnc/core/rfb.js';

// consoleData = response.data from your authorized backend
const { endpoint, session } = consoleData;
if (endpoint.connection_type !== 'native_vnc' || !endpoint.web_url) {
    throw new Error('A native VNC WebSocket endpoint is required');
}
if (session.expires_at && Date.parse(session.expires_at) <= Date.now()) {
    throw new Error('Fetch a fresh console ticket before connecting');
}

const screen = document.getElementById('console');
screen.style.height = '70vh';
const rfb = new RFB(screen, endpoint.web_url, {
    shared: true,
    credentials: { password: endpoint.password },
});
rfb.scaleViewport = true;
rfb.addEventListener('credentialsrequired', () => {
    rfb.sendCredentials({ password: endpoint.password });
});
// Optional toolbar: rfb.sendCtrlAltDel();
// When closing/unmounting the console: rfb.disconnect();

Nếu kết nối đầu thất bại, hãy ngắt kết nối instance cũ rồi thử lại với web_url_fallback nếu có. Trang chạy HTTPS yêu cầu kết nối WSS (nếu website có bật Content-Security-Policy, cần cho phép host/port WebSocket trong chỉ thị connect-src). Do API gọi từ backend nên bạn không cần cấu hình CORS cho tên miền API.

Thời hạn ticket và kết nối lại

Kiểm tra expires_at và ttl_seconds để biết thời hạn hiệu lực. Khi cần mở lại phiên sau lúc hết hạn, hãy gọi lại endpoint trên để lấy thông tin mới. Lưu ý API có thể trả lại ticket đang còn hạn chứ không nhất thiết tạo ticket mới sau mỗi lần gọi, vì vậy hãy luôn lấy đúng URL và mật khẩu từ response mới nhất.

Ý nghĩa các mã lỗi thường gặp: 401/403 (sai token hoặc thiếu quyền), 404 (dịch vụ không thuộc tài khoản), 422 (dịch vụ đang khóa, hết hạn hoặc chưa hỗ trợ console). Nếu gặp 429 (vượt giới hạn tần suất), hãy chờ đúng số giây trong header Retry-After rồi mới gọi lại.

noVNC API

Tích hợp nâng cao — Tự dựng WebSocket (websockify) hoặc dùng phần mềm VNC desktop

Tự dựng WebSocket hoặc dùng VNC desktop

Lấy endpoint.host, endpoint.port và endpoint.password từ response và bảo đảm server của bạn mở kết nối TCP tới được host/port này (truyền đúng hostname, không thêm https://). Vì port có thể thay đổi theo từng phiên, luôn lấy thông tin mới thay vì ghi cứng trong cấu hình.

Nếu muốn dùng domain riêng, bạn có thể chạy websockify chuyển tiếp từ endpoint WSS của mình về endpoint.host:endpoint.port rồi trỏ noVNC vào đó kèm endpoint.password (không trỏ trực tiếp noVNC vào cổng TCP thuần và không tự ghép thành URL WSS). Các ứng dụng VNC trên máy tính dùng trực tiếp 3 thông số host, port và mật khẩu.

Ví dụ cấu hình websockify cho một phiên
# Replace host and port with the current API response.
nc -vz -w 5 console.cloud247.vn 31726

websockify --ssl-only \
  --cert=/path/to/fullchain.pem --key=/path/to/privkey.pem \
  0.0.0.0:6080 console.cloud247.vn:31726
# noVNC URL on your website: wss://your-console.example.com:6080/

Ví dụ websockify trên chỉ áp dụng cho một VM cố định. Nếu triển khai cho nhiều VM, bạn cần dùng định tuyến theo token để ánh xạ động đúng cổng đích mỗi lần API cấp ticket mới. Lưu ý SSL trên websockify chỉ mã hóa chặng trình duyệt → server của bạn; để tích hợp gọn nhẹ nhất trên trình duyệt, nên dùng trực tiếp đường dẫn WSS của Cloud247.

websockify

OpenAPI 3.1

Danh mục endpoint

Tra cứu chi tiết tham số, cấu trúc request/response và gửi thử request trực tiếp bằng Bearer token.

Tên đường dẫn và tên trường JSON luôn giữ nguyên tiếng Anh để bảo đảm tương thích cố định khi tích hợp.
Cloud247 API v1 · https://api.cloud247.vn/v1 OpenAPI 3.1 · Bearer Auth · JSON