StockSEO API

Publiczne REST API do weryfikacji licencji i sprawdzania wydań platformy StockSEO. Zbuduj integrację, panel odsprzedawcy albo własne narzędzie na naszym systemie.

Bazowy URL: https://stockseo.pl/api/v1 JSON in / JSON out CORS: włączony

// wprowadzenie

API jest wersjonowane w ścieżce (/api/v1/). Wszystkie odpowiedzi to JSON w spójnym kształcie: sukces ma ok: true i pole data, błąd ma ok: false i pole error. Nie musisz nic instalować — wystarczy klient HTTP.

Endpointy dzielą się na publiczne (status serwera) i wymagające licencji (weryfikacja, wydania). Licencja to podpisany token, który klient dostaje przy zakupie.

// uwierzytelnianie

Chronione endpointy wymagają ważnej licencji przekazanej jako:

pole license w ciele żądania POST (dla /license/verify), lub
parametr ?license= w URL (dla endpointów GET wydań).

Licencja jest podpisana kryptograficznie (Ed25519). Serwer weryfikuje podpis, datę ważności i listę unieważnień. Podrobienie licencji jest niemożliwe bez klucza prywatnego wydawcy.

uwaga

Nie ma osobnych „kluczy API" — token licencyjny jest poświadczeniem. Traktuj go jak sekret: nie umieszczaj w kodzie front-endu widocznym publicznie.

// format odpowiedzi

Każda udana odpowiedź:

{
  "ok": true,
  "data": { /* zawartość zależna od endpointu */ },
  "meta": { "api": "v1" }
}

Każdy błąd:

{
  "ok": false,
  "error": {
    "code": "missing_license",
    "message": "Pole license jest wymagane",
    "hint": "Wyślij POST z body {license: ...}"
  }
}

// kody błędów

HTTP	code	znaczenie
400	missing_license	Brak wymaganego pola/parametru licencji
403	license_expired	Licencja wygasła (abonament do odnowienia)
403	license_revoked	Licencja unieważniona przez wydawcę
403	license_invalid_signature	Podpis nieprawidłowy (token podrobiony/uszkodzony)
404	no_release	Brak opublikowanego wydania
404	not_found	Nieznany endpoint

// endpointy

GET/api/v1/

Zwraca informacje o API i listę dostępnych endpointów. Przydatne do odkrywania i sprawdzenia, że API odpowiada.

# żądanie
curl https://stockseo.pl/api/v1/

# odpowiedź
{ "ok":true, "data":{ "name":"StockSEO Platform API", "version":"v1", ... } }

GET/api/v1/status

Health check. Publiczny — nie wymaga licencji. Użyj do monitoringu dostępności serwera.

curl https://stockseo.pl/api/v1/status

{ "ok":true, "data":{
  "status":"operational",
  "time":"2026-07-22T01:10:10+00:00",
  "libsodium":true,
  "release_available":true
}}

POST/api/v1/license/verify

Weryfikuje licencję: sprawdza podpis, datę ważności i listę unieważnień. Zapisuje log użycia (urządzenie, czas, IP). To główny endpoint dla integracji, które chcą potwierdzić dostęp klienta.

Ciało żądania

pole	typ	opis
license	string	Token licencyjny klienta (wymagany)

Przykład

curl -X POST https://stockseo.pl/api/v1/license/verify \
  -H "Content-Type: application/json" \
  -d '{"license":"eyJkZXZpY2Ui..."}'

# sukces
{ "ok":true, "data":{
  "valid":true,
  "name":"Sklep Kowalski",
  "exp":"2027-01-15",
  "daysLeft":177,
  "perpetual":false
}}

pole daysLeft

Gdy licencja jest bezterminowa (dożywotnia), daysLeft to null, a perpetual to true. Dla abonamentów daysLeft mówi, ile dni zostało — użyj do ostrzegania klienta przed wygaśnięciem.

GET/api/v1/release/latest

Metadane najnowszego wydania (numer wersji, data, liczba plików). Wymaga ?license=. Użyj, by sprawdzić, czy jest dostępna nowsza wersja.

curl "https://stockseo.pl/api/v1/release/latest?license=eyJ..."

{ "ok":true, "data":{
  "version":"1.0.5", "released":"2026-07-22", "files":8
}}

GET/api/v1/release/manifest

Pełny podpisany manifest wydania (lista plików z sumami kontrolnymi + podpis). Wymaga ?license=. Dla narzędzi implementujących własny mechanizm aktualizacji.

curl "https://stockseo.pl/api/v1/release/manifest?license=eyJ..."

{ "ok":true, "data":{
  "manifest":{ "version":"1.0.5", "files":[...] },
  "signature":"base64-ed25519-signature"
}}

// przykłady integracji

JavaScript (fetch)

const res = await fetch("https://stockseo.pl/api/v1/license/verify", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ license: userLicense })
});
const json = await res.json();
if (json.ok && json.data.valid) {
  console.log("Licencja ważna dla:", json.data.name);
}

Python (requests)

import requests
r = requests.post("https://stockseo.pl/api/v1/license/verify",
                  json={"license": user_license})
data = r.json()
if data["ok"] and data["data"]["valid"]:
    print("Ważna do:", data["data"]["exp"])

PHP (curl)

$ch = curl_init("https://stockseo.pl/api/v1/license/verify");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["license" => $license]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

// zmiany API

wersja	data	zmiany
v1	2026-07	Pierwsze publiczne API: status, weryfikacja licencji, metadane wydań.

stabilność

Wersja v1 jest stabilna. Zmiany łamiące kompatybilność trafią do v2 pod nową ścieżką — v1 będzie działać dalej. Zmiany nie-łamiące (nowe pola, nowe endpointy) dochodzą do v1 bez zapowiedzi.

Pytania o integrację? kontakt@stockseo.pl