Dokumentacja API Panelu Zarządzania

Spis treści

Wprowadzenie Endpoint Uwierzytelnianie Metody HTTP Dostępne akcje Przykłady użycia Kody błędów Struktura odpowiedzi Bezpieczeństwo

Wprowadzenie

API Panelu Zarządzania umożliwia zarządzanie wyszukiwarką z poziomu zewnętrznych aplikacji (np. grobnet.eu). Endpoint wymaga uwierzytelniania przez klucz API oraz opcjonalnie danych logowania administratora.

Informacja: API automatycznie sprawdza czy klucz API został wydany dla subdomeny, z której wykonujesz żądanie.

Endpoint

GET/POST /api/panelzarzadzania

GET/POST /api/panel skrócona wersja

Uwierzytelnianie

1. Klucz API (wymagany)

Klucz API musi być przekazany w jednym z następujących sposobów:

Nagłówek HTTP: X-API-Key: {twoj_klucz_api}
Parametr GET: ?api_key={twoj_klucz_api}
Parametr POST: api_key={twoj_klucz_api}

Uwaga: Klucz API jest weryfikowany w bazie danych grobnet.eu i musi być przypisany do subdomeny, z której wykonujesz żądanie.

2. Dane logowania administratora (opcjonalne)

Jeśli chcesz wykonać akcje wymagające uprawnień administratora, możesz przekazać:

username - nazwa użytkownika administratora wyszukiwarki
password - hasło do logowania w wyszukiwarce
admin_panel_password - hasło do panelu administracyjnego (dodatkowe zabezpieczenie)

Metody HTTP

GET - Pobieranie informacji

Pobiera podstawowe informacje o panelu zarządzania.

Przykład żądania:

curl -H "X-API-Key: twoj_klucz_api" \
  https://subdomena.grobnet.eu/api/panel

Odpowiedź:

{
  "status": "success",
  "message": "Autoryzacja pomyślna",
  "subdomain": "subdomena.grobnet.eu",
  "api_key_valid": true,
  "admin_authenticated": false,
  "data": {
    "info": "Panel zarządzania API",
    "subdomain": "subdomena.grobnet.eu",
    "timestamp": "2024-01-15 12:00:00",
    "endpoints": {
      "GET /api/panelzarzadzania": "Pobierz informacje o panelu",
      "POST /api/panelzarzadzania": "Wykonaj akcję zarządzania"
    }
  }
}

POST - Wykonywanie akcji

Wykonuje akcje zarządzania wymagające uprawnień administratora.

Struktura żądania:

{
  "action": "nazwa_akcji",
  "username": "admin",
  "password": "haslo_wyszukiwarki",
  "admin_panel_password": "haslo_panelu_admina"
}

Dostępne akcje

Informacja: Wszystkie akcje wymagają uwierzytelniania przez klucz API. Niektóre akcje wymagają dodatkowo danych logowania administratora (username, password).

📊 Statystyki

1. get_stats - Pobierz podstawowe statystyki

Pobiera podstawowe statystyki wyszukiwarki (liczba zmarłych, grobów, fotografii).

Akcja: get_stats
Wymaga logowania: Opcjonalne

Przykład żądania:

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: twoj_klucz_api" \
  -d '{
    "action": "get_stats",
    "username": "admin",
    "password": "haslo_wyszukiwarki"
  }' \
  https://subdomena.grobnet.eu/api/panel

👤 Zmarli

2. get_zmarli - Pobierz listę zmarłych

Pobiera listę zmarłych z możliwością filtrowania i paginacji.

Akcja: get_zmarli
Wymaga logowania: Opcjonalne
Parametry: page (int), limit (int), search (string), filters (object)

3. get_zmarli_by_id - Pobierz szczegóły zmarłego

Akcja: get_zmarli_by_id
Parametry: id (int) - ID zmarłego

4. add_zmarli - Dodaj zmarłego

Akcja: add_zmarli
Wymaga logowania: Wymagane
Parametry: data (object) - dane zmarłego

5. update_zmarli - Aktualizuj dane zmarłego

Akcja: update_zmarli
Wymaga logowania: Wymagane
Parametry: id (int), data (object)

6. delete_zmarli - Usuń zmarłego

Akcja: delete_zmarli
Wymaga logowania: Wymagane
Parametry: id (int)

👥 Użytkownicy

7. get_users - Pobierz listę użytkowników

Akcja: get_users
Wymaga logowania: Wymagane

8. get_user_by_id - Pobierz szczegóły użytkownika

Akcja: get_user_by_id
Wymaga logowania: Wymagane

9. add_user - Dodaj użytkownika

Akcja: add_user
Wymaga logowania: Wymagane

10. update_user - Aktualizuj użytkownika

Akcja: update_user
Wymaga logowania: Wymagane

11. delete_user - Usuń użytkownika

Akcja: delete_user
Wymaga logowania: Wymagane

📄 Strony

12. get_pages - Pobierz listę stron

Akcja: get_pages
Wymaga logowania: Opcjonalne

13-16. Operacje na stronach

get_page_by_id, add_page, update_page, delete_page

📋 Panele

17-21. Operacje na panelach

get_panels, get_panel_by_id, add_panel, update_panel, delete_panel

📝 Wpisy

22-26. Operacje na wpisach

get_posts, get_post_by_id, add_post, update_post, delete_post

💬 Komentarze

27-29. Operacje na komentarzach

get_comments, approve_comment, delete_comment

📧 Kontakty

30-33. Operacje na kontaktach

get_contacts, get_contact_by_id, update_contact, delete_contact

🎨 Bannery

34-38. Operacje na bannerach

get_banners, get_banner_by_id, add_banner, update_banner, delete_banner

🔔 Powiadomienia

39. get_notifications - Pobierz listę powiadomień

Akcja: get_notifications
Wymaga logowania: Wymagane

40. send_notification - Wyślij powiadomienie

Wysyła powiadomienie SMS lub email. Wymaga skonfigurowanych ustawień SMTP (dla email) lub SMSAPI (dla SMS).

Akcja: send_notification
Parametry: type (string: "email" lub "sms"), recipient (string), message (string), subject (string) - opcjonalne dla email

💾 Backup

41. create_backup - Utwórz backup bazy danych

Tworzy kopię zapasową bazy danych. Może tworzyć backup wszystkich tabel lub wybranych. Obsługuje kompresję gzip.

Akcja: create_backup
Parametry: name (string) - opcjonalna nazwa backupu, tables (array) - opcjonalna lista tabel, compress (bool) - kompresja gzip

42. list_backups - Pobierz listę backupów

Akcja: list_backups
Wymaga logowania: Wymagane

43. restore_backup - Przywróć backup

Przywraca bazę danych z backupu. Obsługuje pliki .sql i .sql.gz.

Akcja: restore_backup
Parametry: backup_file (string) - nazwa pliku backupu

⚙️ Ustawienia

44. get_settings - Pobierz ustawienia systemu

Akcja: get_settings
Wymaga logowania: Wymagane

45. update_settings - Aktualizuj ustawienia

Akcja: update_settings
Wymaga logowania: Wymagane

📊 Statystyki szczegółowe

46. get_statistics_detailed - Pobierz szczegółowe statystyki

Akcja: get_statistics_detailed
Wymaga logowania: Wymagane

🔗 Menu

47. get_menu - Pobierz strukturę menu

Akcja: get_menu
Wymaga logowania: Opcjonalne

48. update_menu - Aktualizuj menu

Akcja: update_menu
Wymaga logowania: Wymagane

📦 Moduły - Instalacja/Deinstalacja

49. install_module - Zainstaluj moduł

Instaluje moduł w systemie. Automatycznie instaluje tabele, szablony i konfigurację modułu.

Akcja: install_module
Parametry: module_folder (string) - folder modułu w katalogu MODULY

50. uninstall_module - Odinstaluj moduł

Akcja: uninstall_module
Parametry: module_folder (string) - folder modułu

Informacja: Wszystkie akcje są w pełni zaimplementowane i gotowe do użycia. API obsługuje kompletną logikę biznesową dla wszystkich funkcji.

Przykłady użycia

JavaScript (Fetch API)

GET - Pobierz informacje o panelu

async function getPanelInfo() {
    const response = await fetch('https://subdomena.grobnet.eu/api/panel', {
        method: 'GET',
        headers: {
            'X-API-Key': 'twoj_klucz_api'
        }
    });
    
    const data = await response.json();
    console.log(data);
}

POST - Pobierz statystyki

async function getStats() {
    const response = await fetch('https://subdomena.grobnet.eu/api/panel', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': 'twoj_klucz_api'
        },
        body: JSON.stringify({
            action: 'get_stats',
            username: 'admin',
            password: 'haslo_wyszukiwarki'
        })
    });
    
    const data = await response.json();
    if (data.status === 'success') {
        console.log('Statystyki:', data.data.stats);
    }
}

PHP (cURL)

GET - Pobierz informacje o panelu

function getPanelInfo($apiKey, $subdomain) {
    $url = "https://{$subdomain}/api/panel";
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-Key: ' . $apiKey
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    return null;
}

POST - Wyślij powiadomienie

function sendNotification($apiKey, $subdomain, $type, $recipient, $message, $subject = '') {
    $url = "https://{$subdomain}/api/panel";
    
    $data = [
        'action' => 'send_notification',
        'type' => $type,
        'recipient' => $recipient,
        'message' => $message
    ];
    
    if ($type === 'email' && !empty($subject)) {
        $data['subject'] = $subject;
    }
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode === 200) {
        return json_decode($response, true);
    }
    
    return null;
}

Python

GET - Pobierz informacje o panelu

import requests
import json

def get_panel_info(api_key, subdomain):
    url = f"https://{subdomain}/api/panel"
    headers = {
        'X-API-Key': api_key
    }
    
    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        return response.json()
    return None

POST - Pobierz statystyki

import requests
import json

def get_stats(api_key, subdomain, username, password):
    url = f"https://{subdomain}/api/panel"
    headers = {
        'Content-Type': 'application/json',
        'X-API-Key': api_key
    }
    data = {
        'action': 'get_stats',
        'username': username,
        'password': password
    }
    
    response = requests.post(url, headers=headers, json=data)
    if response.status_code == 200:
        return response.json()
    return None

Kody błędów

401 Unauthorized

Przyczyny:

Brak klucza API
Nieprawidłowy klucz API
Klucz API nie został wydany dla tej subdomeny
Nieprawidłowe dane logowania administratora

Przykład odpowiedzi:

{
  "status": "error",
  "message": "Nieprawidłowy klucz API",
  "code": "INVALID_API_KEY"
}

400 Bad Request

Przyczyny:

Brak parametru action w żądaniu POST
Nieznana akcja
Nieprawidłowe dane w żądaniu

Przykład odpowiedzi:

{
  "status": "error",
  "message": "Nieprawidłowa akcja",
  "code": "INVALID_ACTION"
}

403 Forbidden

Przyczyny:

Brak uprawnień do wykonania akcji
Wymagane dane logowania administratora
Konto użytkownika jest zablokowane

Przykład odpowiedzi:

{
  "status": "error",
  "message": "Brak uprawnień do wykonania tej akcji",
  "code": "FORBIDDEN"
}

404 Not Found

Przyczyny:

Nie znaleziono zasobu o podanym ID
Nieprawidłowy endpoint

500 Internal Server Error

Przyczyny:

Błąd serwera
Błąd bazy danych
Nieoczekiwany błąd podczas przetwarzania żądania

Struktura odpowiedzi

Sukces

{
  "status": "success",
  "message": "Autoryzacja pomyślna",
  "subdomain": "subdomena.grobnet.eu",
  "api_key_valid": true,
  "admin_authenticated": true,
  "data": {
    // Dane zależne od akcji
  }
}

Błąd

{
  "status": "error",
  "message": "Opis błędu",
  "code": "KOD_BLEDU",
  "data": []
}

Pola odpowiedzi

Pole	Typ	Opis
`status`	string	Status odpowiedzi: `success` lub `error`
`message`	string	Komunikat odpowiedzi
`code`	string	Kod błędu (tylko w przypadku błędu)
`subdomain`	string	Subdomena, dla której wykonano żądanie
`api_key_valid`	boolean	Czy klucz API jest prawidłowy
`admin_authenticated`	boolean	Czy użytkownik jest zalogowany jako administrator
`data`	object\|array	Dane odpowiedzi (zależne od akcji)

Bezpieczeństwo

⚠️ Uwagi bezpieczeństwa:

Klucz API: Przechowuj klucz API w bezpiecznym miejscu (zmienne środowiskowe, plik poza webroot)
HTTPS: Zawsze używaj HTTPS do komunikacji z API
Hasła: Nie loguj haseł w konsoli ani nie przechowuj ich w kodzie
Subdomena: Klucz API jest przypisany do konkretnej subdomeny - nie można użyć go na innej subdomenie

Jak uzyskać klucz API?

Zaloguj się do panelu Użytkownika grobnet.eu
Przejdź do sekcji "Klucze API"
Utwórz nowy klucz API dla wybranej subdomeny
Skopiuj i zapisz klucz API w bezpiecznym miejscu (będzie wyświetlony tylko raz)

Weryfikacja subdomeny

API automatycznie sprawdza czy klucz API został wydany dla subdomeny, z której wykonujesz żądanie. Subdomena jest pobierana z nagłówka HTTP_HOST lub SERVER_NAME.

Weryfikacja danych logowania

Jeśli przekażesz username i password, API sprawdzi je bezpośrednio z kontem administratora w bazie danych wyszukiwarki (DB_USERS). Weryfikacja używa tego samego mechanizmu co logowanie do panelu administracyjnego.

Ograniczenia API

Maksymalna liczba żądań: 1000 na godzinę na klucz API
Maksymalny rozmiar żądania: 10MBMaksymalny czas wykonywania żądania: 30 sekund
Obsługiwane metody HTTP: GET, POST
Format odpowiedzi: JSON

Najlepsze praktyki

Zawsze używaj HTTPS do komunikacji z API
Nie przechowuj klucza API w kodzie źródłowym
Używaj zmiennych środowiskowych do przechowywania poufnych danych
Regularnie aktualizuj klucz API
Monitoruj użycie API i reaguj na podejrzane aktywności
Implementuj mechanizm ponawiania żądań w przypadku błędów

Wersjonowanie API

Obecna wersja API: 1.0.0

API używa semantycznego wersjonowania (SemVer):

MAJOR - Zmiana powodująca niezgodność wsteczną
MINOR - Dodanie nowych funkcjonalności z zachowaniem wstecznej zgodności
PATCH - Poprawki błędów i optymalizacje

Wersja API jest przekazywana w nagłówku X-API-Version.