API REST et intégrations

Référence des endpoints API pour gérer services et paiements.

Dernière mise à jour 21 novembre 2026

Articles dans cette catégorie

Cet article n'est pas encore disponible dans votre langue - version polonaise affichée.

Oficjalny interfejs BlackHost Public REST API umożliwia bezpieczną automatyzację, integrację z zewnętrznymi botami (np. Discord), skryptami CI/CD oraz własnymi panelami zarządzania.


🌐 Podstawowe informacje

  • Base URL: https://api.blackhost.pl/v1
  • Format danych: JSON (application/json)
  • Kodowanie: UTF-8
  • Protokół: HTTPS (wymagany TLS 1.3 / 1.2)
  • CORS: Dostępny dla wszystkich domen (Access-Control-Allow-Origin: *) przy zapytaniach z nagłówkiem Authorization: Bearer

🔑 Uwierzytelnianie (Klucze API)

Wszystkie zapytania do API wymagają przekazania aktywnego tokenu dostępowego (Personal Access Token) w nagłówku HTTP:

Authorization: Bearer bh_pat_twoj_unikalny_token

Jak wygenerować klucz API?

  1. Zaloguj się do panelu klienta na dash.blackhost.pl (https://dash.blackhost.pl).
  2. Przejdź do zakładki Konto (/account).
  3. W sekcji Klucze API kliknij przycisk Nowy klucz.
  4. Wpisz nazwę identyfikacyjną (np. Bot Discord, Skrypt backupu).
  5. Zaznacz wymagane uprawnienia (Scopes).
  6. Opcjonalnie wybierz datę i godzinę wygaśnięcia tokenu.
  7. Skopiuj wygenerowany token bh_pat_... i zapisz go w bezpiecznym miejscu (sekret nie będzie widoczny ponownie).

⚠️ Bezpieczeństwo: Nigdy nie udostępniaj tokenu publicznie (np. w publicznych repozytoriach GitHub). Klucz API daje dostęp do Twoich serwerów w ramach wybranych uprawnień.


🛡️ Dostępne uprawnienia (Scopes)

Podczas generowania klucza możesz precyzyjnie określić, do jakich operacji ma on dostęp:

Uprawnienie (Scope)Opis
account:readOdczyt listy aktywnych serwerów i usług przypisanych do konta
account:billingDoładowania portfela, historia transakcji, płatności i zakupy
game:readOdczyt statusu, parametrów, zużycia zasobów i graczy serwerów gier
game:powerStart, stop, restart oraz natychmiastowe zatrzymanie (kill) serwera gry
game:commandWysyłanie poleceń do konsoli serwera gry oraz akcje na graczach (kick/ban/op)
game:files:readPrzeglądanie katalogów, wyszukiwanie oraz odczyt i pobieranie plików
game:files:writeEdycja plików, tworzenie katalogów, usuwanie, zmiana nazw, pakowanie ZIP
vps:readOdczyt parametrów, statystyk zużycia, logów, kopii i zapory maszyn VPS
vps:powerZarządzanie zasilaniem VPS (Start, Stop, Reboot, Shutdown)
vps:consoleGenerowanie sesji i dostęp do konsoli noVNC maszyny VPS
vps:firewallKonfiguracja reguł zapory ogniowej, białej listy IP oraz opcji bezpieczeństwa
vps:settingsZmiana nazwy, konfiguracja rekordu PTR/rDNS, zarządzanie kluczami SSH i hasłem
vps:backupsTworzenie, przywracanie i zarządzanie kopiami zapasowymi VPS
vps:install1-Click instalatory oprogramowania na VPS oraz instalacje systemowe
vps:subusersZarządzanie subużytkownikami i delegowanie uprawnień do maszyn VPS

⏱️ Limity zapytań (Rate Limiting)

Dla zachowania stabilności infrastruktury obowiązuje standardowy limit 60 zapytań na minutę na każdy klucz API.

Po przekroczeniu limitu serwer zwróci odpowiedź HTTP 429 Too Many Requests wraz z nagłówkiem informującym o czasie odblokowania:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "success": false,
  "error": "Zbyt wiele zapytań. Spróbuj ponownie za chwilę."
}

🚀 Przykłady wywołań

cURL

# Pobranie listy swoich serwerów
curl -X GET "https://api.blackhost.pl/v1/servers" \
  -H "Authorization: Bearer bh_pat_TWOJ_TOKEN" \
  -H "Accept: application/json"

Node.js / TypeScript (Fetch)

const API_TOKEN = "bh_pat_TWOJ_TOKEN";

async function getServers() {
  const response = await fetch("https://api.blackhost.pl/v1/servers", {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${API_TOKEN}`,
      "Accept": "application/json"
    }
  });

  const data = await response.json();
  console.log("Moje serwery:", data);
}

getServers();

Python (Requests)

import requests

API_TOKEN = "bh_pat_TWOJ_TOKEN"
headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Accept": "application/json"
}

response = requests.get("https://api.blackhost.pl/v1/servers", headers=headers)
print("Odpowiedź API:", response.json())

📚 Moduły dokumentacji API

Przejdź do szczegółowych przewodników i specyfikacji technicznych poszczególnych modułów:

  • Serwery Gier (Game API) - zarządzanie stanem serwerów gier, konsola, menedżer plików, autoinstalatory silników/modów/pluginów, ekwipunki graczy, powiadomienia Discord oraz cykl życia usług.
  • Maszyny VPS (VPS API) - kontrola maszyn KVM, zapora ogniowa (Firewall), rekordy rDNS/PTR, kopie zapasowe PBS, autoinstalatory aplikacji (1-Click Apps), klucze SSH, telemetria SSE/WebSocket oraz subużytkownicy.
  • Portfel, Płatności i Sklep (Billing & Shop API) - saldo portfela wPLN, historia transakcji, automatyczne doładowania (Stripe, Litecoin LTC), przelewy wewnętrzne P2P, metody płatności oraz katalog pakietów.