Dokumentacja integracji Guest API

1. Architektura i zakres usługi

Guest Gateway umożliwia niezalogowanym odwiedzającym komentowanie artykułów w blockchainie BLURT. Frontend przyjmuje pseudonim oraz treść, jego własny serwer wysyła zgłoszenie do Guest API, Gemini AI analizuje komentarz, a worker publikuje zatwierdzony wpis w blockchainie z konta technicznego.

1. Odwiedzający → formularz na Twojej stronie.
2. Backend frontendu → HTTPS + sekret API → Guest Gateway.
3. Weryfikacja danych, limitów i moderacja Gemini; w razie potrzeby ręczne zatwierdzenie.
4. Worker → podpis Posting Key konta gościa → RPC BLURT.
5. Frontend → sprawdzenie statusu zgłoszenia po ID.

Każda aplikacja ma własny sekret i limity. Może publikować przez własne konto BLURT, np. @blurtpl-guest dla blurt.pl albo niezależne konto utworzone przez operatora innego frontendu. Pseudonim odwiedzającego pojawia się w treści, ale autorem blockchainowym pozostaje konto gościnne.

2. Zaproszenie, własne konto Guest i aplikacja

1. Poproś administratora o dostęp. Dostęp do zarządzania Guest API nie jest publicznie otwarty. Administrator przypisuje Twój nick BLURT, rolę managera i ewentualne uprawnienie „Może dodać własne konto gościnne”.
2. Zaloguj się do panelu blurtplugin.online kontem BLURT przez WhaleVault / Blurt Keychain lub opcję podpisu Posting Key (jeśli dostępna w Twojej wersji panelu).
3. Przygotuj dedykowane konto gościnne BLURT. Konto musi już istnieć w blockchainie. W zakładce Konta gościnne dodaj je wraz z Posting Key (WIF), jeśli administrator zezwolił na samodzielne dodawanie. Jeżeli nie masz tego uprawnienia, administrator może przypisać Ci istniejące konto.
4. Utwórz aplikację. W Kontach gościnnych podaj nazwę, wskaż przydzielone konto BLURT, ustaw limit godzinowy i dzienny, kliknij Wygeneruj sekret API.
5. Skopiuj sekret natychmiast. Wartość w postaci ggk_… jest pokazywana tylko raz; później można ją wymienić, ale nie ponownie odczytać.
6. Skonfiguruj backend swojego frontendu i przetestuj zgłoszenie oraz późniejszy odczyt jego statusu.

3. Co jest czym: nick, Posting Key i API key

Nie podawaj Active Key ani Owner Key. Złamanie Posting Key nadal umożliwia niechciane publikacje oraz generowanie kosztów; najlepiej używać dedykowanego konta o małym saldzie i posiadać możliwość wymiany klucza.

4. Endpoint i autoryzacja

Publiczny endpoint produkcyjny (wersja testowa usługi):

https://blurtplugin.online/bg-entry.php

Żądania wykonuj serwer → serwer przez HTTPS. Nagłówek Authorization musi mieć postać Bearer ggk_…. Nie wywołuj tego endpointu bezpośrednio z przeglądarki z prawdziwym sekretem.

Obsługiwane są POST (nowy komentarz) i GET ?id=… (odczyt statusu). Operacje administracyjne, nadawanie dostępu i dodawanie Posting Key odbywają się w panelu, a nie przez to publiczne API.

5. Wysłanie komentarza — POST

Przykładowe żądanie:

POST /bg-entry.php HTTP/1.1
Host: blurtplugin.online
Authorization: Bearer ggk_TUTAJ_SEKRET_APLIKACJI
Idempotency-Key: frontend:comment-1234567890
Content-Type: application/json

{
  "visitor_id": "visitor_8nBL4m9X2qP7v6K1",
  "nickname": "Anna",
  "body": "Bardzo ciekawy artykuł!",
  "parent_author": "autor",
  "parent_permlink": "przykladowy-artykul"
}

Wymagany Content-Type: application/json. Żądanie ma limit ok. 16 KB. Konto autora Guest jest wybierane po kluczu aplikacji — nie wysyła się żadnego posting_key, account czy api_secret w JSON.

Odpowiedź 202 Accepted przy poprawnym przyjęciu (publikacja nie musi być natychmiastowa):

{
  "ok": true,
  "id": "9f3ca91dba802a531c48f77b892ac343",
  "status": "moderating",
  "account": "blurtpl-guest"
}

id jest identyfikatorem zgłoszenia. Ponowienie żądania z tym samym Idempotency-Key w obrębie aplikacji zwraca ten sam komentarz i może zawierać duplicate: true. Nie generuj nowego klucza przy timeoutach lub ponowieniu tego samego formularza.

6. Sprawdzanie statusu, AI i moderacja

Do sprawdzenia statusu użyj tego samego klucza API:

GET /bg-entry.php?id=9f3ca91dba802a531c48f77b892ac343 HTTP/1.1
Host: blurtplugin.online
Authorization: Bearer ggk_TUTAJ_SEKRET_APLIKACJI

Przykładowa odpowiedź:

{
  "ok": true,
  "comment": {
    "id": "9f3ca91dba802a531c48f77b892ac343",
    "status": "published",
    "review_reason": null,
    "permlink": "re-9f3ca91dba802a531c48f77b",
    "tx_id": "...",
    "published_at": "2026-10-30 10:15:00",
    "account": "blurtpl-guest"
  }
}

AI ma identyfikować spam i nadużycia, a nie oceniać poglądy. W przypadku niejednoznacznej treści lub niedostępnej usługi zgłoszenie może trafić do ręcznej kontroli. Frontend powinien pokazać użytkownikowi informację, że publikacja może potrwać — 202 nie oznacza published.

Dla odczytu statusu ID ma postać 32 małych znaków hex. Sekret innej aplikacji nie może odczytać cudzych zgłoszeń.

7. Limity, błędy HTTP i ponawianie

Gateway ogranicza zgłoszenia do 3 komentarzy na odwiedzającego na 24 godziny w ramach aplikacji, a także stosuje osobne limity godzinowe i dobowe skonfigurowane przez właściciela aplikacji. Wdrożony frontend powinien dodatkowo posiadać własny antyspam, CAPTCHA i ochronę CSRF.

Odpowiedź błędu zwykle ma postać {"ok":false,"error":"KOD"}. Zależnie od konfiguracji reverse proxy odpowiedź 404 może być HTML — sprawdzaj HTTP status i nie zakładaj, że każdy błąd zwróci JSON.

8. Przykłady integracji — cURL, PHP i frontend

Test serwerowy (cURL)

curl --fail-with-body -X POST 'https://blurtplugin.online/bg-entry.php' \
  -H "Authorization: Bearer $BLURT_GUEST_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: frontend:comment-1234567890' \
  --data '{
    "visitor_id":"visitor_8nBL4m9X2qP7v6K1",
    "nickname":"Anna",
    "body":"Testowy komentarz.",
    "parent_author":"autor",
    "parent_permlink":"przykladowy-artykul"
  }'

Uwaga: powyższy POST tworzy rzeczywiste zgłoszenie. Używaj wyłącznie własnej aplikacji i testowego wpisu, a nie cudzych artykułów.

PHP — wywołanie z backendu

<?php
$apiKey = getenv('BLURT_GUEST_API_KEY'); // konfiguracja poza webrootem
if (!$apiKey) { throw new RuntimeException('API key missing'); }

// Zachowuj ten sam klucz dla ponowienia tej samej operacji.
$submissionKey = 'frontend:comment-1234567890';
$payload = [
    'visitor_id' => 'visitor_8nBL4m9X2qP7v6K1',
    'nickname' => 'Anna',
    'body' => 'To jest komentarz testowy.',
    'parent_author' => 'autor',
    'parent_permlink' => 'przykladowy-artykul',
];
$ch = curl_init('https://blurtplugin.online/bg-entry.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
        'Idempotency-Key: ' . $submissionKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_THROW_ON_ERROR),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 15,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException('Guest API connection failed'); }
curl_close($ch);
$result = json_decode($response, true);
if ($httpCode !== 202 || !is_array($result) || empty($result['ok'])) {
    throw new RuntimeException('Guest API rejected the submission: HTTP ' . $httpCode);
}
$commentId = $result['id']; // zachowaj do odpytywania statusu

JavaScript po stronie przeglądarki

// Tylko Twoja własna trasa backendowa! Nigdy nie przekazuj tu ggk_...
const response = await fetch('/api/guest-comment', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  credentials: 'same-origin',
  body: JSON.stringify({nickname, body, parent_author, parent_permlink})
});
const result = await response.json();
// Backend ustala visitor_id i Idempotency-Key, chroni trasę CSRF/rate-limit.
// Po otrzymaniu result.id odpytuj status przez własny backend.

Backend frontendu powinien sam tworzyć losowy visitor_id (np. przechowywany w sesji), nadawać trwały identyfikator wysyłki, kontrolować uprawnienia/czas odpowiedzi i nie przekazywać surowego API key przeglądarce. Dla żądania GET statusu używa tych samych nagłówków Bearer po stronie serwera.

9. Bezpieczeństwo i niezależność frontendów

• API key przechowuj tylko na serwerze frontendu, np. w prywatnej konfiguracji; nie loguj pełnego tokenu.
• Posting Key podawaj wyłącznie w zaufanym panelu Guest; nie przesyłaj go przez formularz komentarza ani endpoint publikacji.
• Najlepiej użyj osobnego konta gościnnego BLURT z ograniczonym saldem, a nie konta osobistego.
• Przy ujawnieniu sekretu wygeneruj nowy API key w panelu; stary traci ważność. Sprawdź limity i historię zgłoszeń.
• Po stronie frontendu zapewnij HTTPS, walidację pól, CSRF, ochronę przed botami oraz własne ograniczenia częstotliwości.
• Nie twórz ponownie tego samego zgłoszenia nowym Idempotency-Key, jeśli wcześniejsza operacja ma niepewny wynik.
• Manager widzi tylko przypisane aplikacje. Nadanie dostępu do panelu nie oznacza dostępu do innych kont, sekretów ani ustawień finansowych.

Gateway jest usługą scentralizowaną, natomiast opublikowane komentarze pozostają na blockchainie BLURT i mogą być wyświetlane także przez inne frontendy.

10. Lista kontrolna przed uruchomieniem

1. Masz zaproszenie managera i dostęp do zakładki Konta gościnne.
2. Dedykowane konto BLURT istnieje i ma prawidłowy Posting Key, uprawnienia publikacji oraz niezbędne saldo BLURT.
3. Wygenerowano sekret API, zapisano go poza katalogiem publicznym frontendu.
4. Z frontendu działa testowy POST i odczyt statusu GET po ID.
5. Wyświetlane są czytelne informacje: moderacja, kolejka, publikacja, odrzucenie.
6. Powtórzenie tego samego POST z tym samym Idempotency-Key nie tworzy nowego komentarza.
7. Sprawdzono limity 429, błędny klucz 401 i brak dostępu do cudzych zgłoszeń.
8. Włączono walidację, ochronę CSRF i zabezpieczenia antyspamowe po stronie swojej aplikacji.
9. Opublikowany komentarz można odnaleźć w blockchainie pod kontem Guest.