Documentation API revendeur

1. Obtenir une clé API

Rendez-vous dans votre espace client, onglet Revendeur → Mes clés API, et générez une clé. Elle n'est affichée qu'une seule fois : copiez-la immédiatement, nous n'en conservons que l'empreinte et personne — nous compris — ne peut la retrouver ensuite.

Vous pouvez maintenir jusqu'à 5 clés actives simultanément. En pratique, prenez-en une par environnement : une pour votre site en production, une pour vos tests. Si l'une fuite, vous la révoquez sans interrompre l'autre.

2. Authentification

Toutes les requêtes se font sur cette base :

https://oneheberge.fr/api/v1

La clé s'envoie au choix dans l'un des deux en-têtes suivants — les deux sont équivalents, prenez celui qui s'intègre le mieux à votre client HTTP :

# au choix
X-Api-Key: votre_cle
Authorization: Bearer votre_cle

Une requête sans clé valide reçoit un 401. Chaque appel met à jour la date de dernière utilisation de la clé, visible dans votre espace client : c'est le moyen le plus simple de repérer une clé oubliée mais toujours active.

3. Format des réponses et limites

Toutes les réponses sont en JSON et suivent la même enveloppe, succès comme erreur. Votre code n'a donc qu'un seul format à gérer :

{
  "success": true,
  "message": "Success",
  "data": { ... }
}

En cas d'erreur, success vaut false et message contient la raison en clair. Fiez-vous au code HTTP plutôt qu'au texte du message : celui-ci peut être reformulé, pas le code.

Limite de débit

60 requêtes par minute et par adresse IP. Au-delà, l'API répond 429. C'est largement suffisant pour un site marchand : ne bouclez pas sur l'API pour rafraîchir un tableau de bord, mettez les résultats en cache quelques minutes et n'appelez qu'à la demande ou sur événement.

4. Consulter le catalogue

Commencez toujours par /products : c'est lui qui vous donne le product_id à passer à la commande. Ne codez pas ces identifiants en dur dans votre site — une offre peut être retirée ou remplacée, et votre tunnel de vente doit suivre sans redéploiement.

5. Commander un VPS

Corps de la requête :

# commande d'un VPS
curl -X POST https://oneheberge.fr/api/v1/vps/order \
  -H "X-Api-Key: $ONEHEBERGE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id": 50, "label": "client-4821", "os": "debian12"}'

6. Piloter une machine

Ces actions sont asynchrones côté hyperviseur : un 200 signifie « ordre accepté », pas « machine déjà démarrée ». Pour afficher un état fiable, interrogez /vps/{id} quelques secondes plus tard plutôt que de supposer le résultat.

7. Codes d'erreur

8. Exemple complet d'intégration

Le scénario type : votre client paie sur votre site, vous commandez la machine, vous stockez son identifiant, puis vous affichez son état dans votre propre interface.

<?php
// Cle lue depuis l'environnement, jamais ecrite dans le code
$key = getenv('ONEHEBERGE_KEY');

function oh_call($method, $path, $body = null) {
    global $key;
    $ch = curl_init('https://oneheberge.fr/api/v1' . $path);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_TIMEOUT        => 20,
        CURLOPT_HTTPHEADER     => [
            'X-Api-Key: ' . $key,
            'Content-Type: application/json',
        ],
        CURLOPT_POSTFIELDS => $body ? json_encode($body) : null,
    ]);
    $raw  = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return [$code, json_decode($raw, true)];
}

// 1. commande, avec la reference de VOTRE client
list($code, $res) = oh_call('POST', '/vps/order', [
    'product_id' => 50,
    'label'      => 'client-' . $monClientId,
    'os'         => 'debian12',
]);

if ($code !== 200) {
    // On NE marque PAS la commande comme livree : on alerte et on garde
    // la trace, sinon le client a paye pour rien.
    error_log('OneHeberge: ' . ($res['message'] ?? 'echec'));
    return;
}

$vpsId = $res['data']['id'];
// 2. a enregistrer chez vous : c'est le lien entre vos deux bases
enregistrerVps($monClientId, $vpsId);

// 3. plus tard, redemarrage demande depuis votre interface
oh_call('POST', "/vps/$vpsId/reboot");

Besoin d'aide ?

Une question sur un endpoint, un comportement inattendu, un besoin non couvert ? Ouvrez un ticket depuis votre espace client en précisant l'horodatage de la requête : nos journaux d'API permettent de retrouver l'appel exact et de vous répondre précisément.