Premiers pas

Bienvenue sur PVE Cloud API v2. Cette page couvre les étapes minimales pour votre premier appel.

1 — Obtenir votre premier token

L'API utilise des tokens Sanctum (Bearer). Il n'existe pas d'endpoint POST /login — le premier token se crée depuis votre dashboard :

Connectez-vous sur https://pveman.bzctoons.net/dashboard
Allez dans Paramètres → Tokens API
Cliquez Créer un token, choisissez les scopes
Copiez la valeur affichée une seule fois

Une fois ce token bootstrap en main, vous pouvez en créer d'autres via l'API :

POST /api/v1/tokens
Authorization: Bearer <token-bootstrap>
Content-Type: application/json

{
  "name": "mon-app",
  "abilities": ["lxc:read","lxc:write","billing:read"]
}

Le champ token retourné est affiché une seule fois — conservez-le immédiatement.

2 — Authentifier chaque requête

Authorization: Bearer <token>

3 — Lister vos conteneurs

GET /api/v1/lxc
Authorization: Bearer <token>

Scopes disponibles

Scope	Accès
`lxc:read`	Lecture des conteneurs et métriques
`lxc:write`	Création, actions, suppression des conteneurs
`billing:read`	Factures, transactions, wallet
`orders:write`	Création de commandes
`webhooks:write`	Gestion des endpoints webhook

Cas d'usage

Scénarios complets pour intégrer PVE Cloud dans votre application.

UC 1 — Créer un token d'accès

Un token Sanctum est requis pour chaque appel. Créez-en un avec les capacités minimales nécessaires.

// PHP
$client = new BzctoonsClient(
    'https://pveman.bzctoons.net',
    'VOTRE_TOKEN_ADMIN' // token existant pour bootstrapper
);

$token = $client->issueToken('mon-app', [
    'lxc:read',       // container:list, getContainer…
    'billing:read',
    'billing:write',
    'reseller',       // réservé aux comptes revendeur et administrateur
]);
// → $token['token']  — à stocker, affiché une seule fois

# CLI
export BZCTOONS_URL=https://pveman.bzctoons.net
export BZCTOONS_TOKEN=VOTRE_TOKEN_ADMIN

./bzcapi token:issue "mon-app" \
  --abilities="lxc:read,billing:read,billing:write,reseller"

UC 2 — Explorer le catalogue

Listez les types d'addon disponibles avant de commencer à en attacher.

// PHP
$types = $client->availableAddonTypes();
// $types['data'][0] → {id, name, unit_price_recurring, setup_fee_onetime, is_resizable, …}
// (montants en centimes)

# CLI
./bzcapi container:list
./bzcapi addon:list --help

UC 3 — Attacher un addon à un conteneur

L'opération est asynchrone. Le SDK peut attendre la fin du provisionnement pour vous. Statuts d'une opération : pending, running, retrying, puis succeeded, failed ou cancelled.

// PHP — Étape 1 : créer l'addon (retourne immédiatement)
$res = $client->attachAddon(
    containerId: 42,
    typeId:      3,   // ID du type d'addon
    size:        20   // optionnel
);
$opId = $res['meta']['operation']['id'];

// Étape 2 : attendre la fin (poll toutes les 2s, timeout 2min)
$final = $client->watchOperation(
    $opId,
    onProgress: function (string $status) {
        echo "[$status]\n"; // pending → running → succeeded
    }
);
if ($final['data']['status'] === 'succeeded') {
    echo "Addon actif : " . $res['data']['id'];
}

# CLI (--watch = attendre la fin)
./bzcapi addon:attach 42 3 --size=20 --watch

UC 4 — Récupérer un addon en échec

Si le provisionnement échoue (réseau, hyperviseur), relancez-le. Limité à 3 tentatives / heure.

// PHP
try {
    $res = $client->recoverAddon(42, 'addon-ulid');
    $client->watchOperation(
        $res['meta']['operation']['id'],
        fn($s) => print "[$s]\n"
    );
} catch (\RuntimeException $e) {
    // HTTP 429 — limite atteinte
    echo $e->getMessage();
}

# CLI
./bzcapi addon:recover 42 addon-ulid --watch
./bzcapi addon:history 42 addon-ulid --status=failed

UC 5 — Annuler une opération en attente

Seules les opérations en état Pending peuvent être annulées.

// PHP
$client->cancelAddonOperation(42, 'addon-ulid');

# CLI
./bzcapi addon:cancel 42 addon-ulid

UC 6 — Recevoir les événements en temps réel

Abonnez votre backend aux événements addon. L'endpoint doit être en HTTPS et répondre en < 30s.

// PHP
$endpoint = $client->subscribeToEvents(
    'https://mon-app.com/webhooks/bzctoons',
    ['addon.operation.completed', 'addon.operation.failed', 'addon.status.changed']
);
// Désactiver sans supprimer
$client->toggleWebhookEndpoint($endpoint['data']['id'], false);
// Supprimer
$client->unsubscribeFromEvents($endpoint['data']['id']);

# CLI
./bzcapi webhook:subscribe https://mon-app.com/webhooks/bzctoons \
  --events="addon.operation.completed,addon.operation.failed"
./bzcapi webhook:list

Le secret de signature n'est renvoyé qu'une seule fois, dans la réponse de création : $endpoint['data']['secret']. Conservez-le. Événements émis : addon.operation.completed, addon.operation.failed et addon.status.changed ; le corps JSON contient toujours la clé event.

Vérification de signature côté récepteur :

$body     = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, 'votre-secret');
if (!hash_equals($expected, $_SERVER['HTTP_X_SIGNATURE_256'] ?? '')) {
    http_response_code(401); exit;
}
$payload = json_decode($body, true);
// $payload['event'] → 'addon.operation.completed'

UC 7 — Vérifier la santé financière

// PHP
$snapshot = $client->billingSnapshot();
// → wallet.balance_cents, unpaid_invoices, recent_txs

# CLI
./bzcapi billing:snapshot

SDK & CLI

Version : 2.0.1 — PHP 8.2+ — Guzzle 7

⬇ SDK (zip) ⬇ CLI (bzcapi)

Installation

mkdir packages
cp bzctoons-php-sdk-v2.0.1.zip packages/
composer config repositories.bzctoons artifact ./packages
composer require bzctoons/php-sdk:^2.0

Pour le CLI : chmod +x bzcapi puis ajoutez-le à votre $PATH.

Référence SDK

Méthode	Description
`issueToken($name, $abilities)`	Créer un token Sanctum
`revokeToken($id)`	Révoquer un token
`listContainers()`	Lister les conteneurs
`getContainer($id)`	Détails d'un conteneur
`startContainer($id)` / `stopContainer($id)`	Démarrer / Arrêter
`attachAddon($cId, $typeId, $size)`	Attacher un addon
`resizeAddon($cId, $addonId, $size)`	Redimensionner un addon
`detachAddon($cId, $addonId)`	Détacher un addon
`recoverAddon($cId, $addonId)`	Récupérer un addon en échec
`cancelAddonOperation($cId, $addonId)`	Annuler une opération
`watchOperation($opId, $cb, $timeout)`	Attendre une opération (poll)
`subscribeToEvents($url, $events)`	S'abonner aux webhooks
`billingSnapshot()`	Snapshot financier
`raw($method, $path, $data)`	Accès direct à l'API

Commandes CLI

container:list                 Lister les conteneurs
container:show <id>            Détails d'un conteneur
addon:list <containerId>       Lister les addons
addon:attach <cId> <typeId>   Attacher un addon [--size] [--watch]
addon:watch <opId>             Suivre une opération
addon:recover <cId> <id>      Récupérer un addon [--watch]
addon:cancel <cId> <id>       Annuler une opération
addon:history <cId> <id>      Historique [--status]
webhook:list                   Lister les endpoints
webhook:subscribe <url>        S'abonner [--events]
webhook:unsubscribe <id>       Se désabonner
billing:snapshot               Snapshot financier
token:issue <name>             Créer un token [--abilities]

Variables d'environnement : BZCTOONS_URL et BZCTOONS_TOKEN.