StockSEO API

REST API do wbudowania funkcji SEO i AI StockSEO we własny produkt. Audyty, generowanie opisów produktów (także masowo), monitoring widoczności w wyszukiwarkach i w odpowiedziach AI.

// wprowadzenie

API jest wersjonowane w ścieżce (/ext/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.

API jest przeznaczone dla systemów, które chcą oferować swoim klientom funkcje SEO/AI: platform sklepowych, CRM-ów, wtyczek i narzędzi do zarządzania asortymentem. Endpointy dzielą się na publiczny health check oraz chronione, wymagające klucza API. Operacje masowe działają asynchronicznie przez system zadań. Żądania POST są limitowane na klucz (domyślnie 30/min; nagłówki X-RateLimit-*, po przekroczeniu 429 z Retry-After) — masowe operacje rób przez endpointy *-bulk, a status odpytuj GET-em, który limitu nie ma.

// uwierzytelnianie

Chronione endpointy wymagają klucza API w nagłówku:

# zalecane
X-API-Key: sk_stockseo_xxxxxxxxxxxx

# alternatywnie
Authorization: Bearer sk_stockseo_xxxxxxxxxxxx

Klucz otrzymujesz od StockSEO przy uruchamianiu integracji. Jest przypisany do Twojego systemu i ma zestaw uprawnień (scope): seo:read (analizy), seo:generate (generowanie treści), geo:read (widoczność w AI) albo * (wszystko). Brak uprawnienia zwraca 403 forbidden.

Klucz jest tajny. Trzymaj go po stronie serwera — nigdy w kodzie wykonywanym w przeglądarce.

// 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": "unauthorized",
    "message": "Brak lub nieprawidłowy klucz API",
    "hint": "Wyślij nagłówek X-API-Key: sk_stockseo_..."
  }
}

// kody błędów

// przykłady integracji

Najczęstszy przypadek: klient zaimportował paletę, chcesz wygenerować opisy dla wszystkich produktów naraz.

PHP (curl)

$KEY = "sk_stockseo_...";
$BASE = "https://stockseo.tojest.dev/ext/v1";

// 1. Zlec zadanie
$ch = curl_init($BASE . "/content/product-bulk");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Content-Type: application/json", "X-API-Key: " . $KEY],
  CURLOPT_POSTFIELDS => json_encode(["products" => $produkty]),
  CURLOPT_RETURNTRANSFER => true,
]);
$job = json_decode(curl_exec($ch), true);
$jobId = $job["data"]["job_id"];

// 2. Odpytuj co 5 sekund, az gotowe
do {
  sleep(5);
  $ctx = stream_context_create(["http" => ["header" => "X-API-Key: " . $KEY]]);
  $st = json_decode(file_get_contents($BASE . "/jobs/" . $jobId, false, $ctx), true);
} while ($st["data"]["status"] !== "completed");

// 3. Zapisz opisy przy produktach
foreach ($st["data"]["results"] as $r) {
  zapiszOpis($r["id"], $r["description_html"]);
}

JavaScript (fetch)

const KEY = "sk_stockseo_...", BASE = "https://stockseo.tojest.dev/ext/v1";
const H = { "Content-Type": "application/json", "X-API-Key": KEY };

const job = await (await fetch(BASE + "/content/product-bulk", {
  method: "POST", headers: H, body: JSON.stringify({ products })
})).json();

let st;
do {
  await new Promise(r => setTimeout(r, 5000));
  st = await (await fetch(BASE + "/jobs/" + job.data.job_id, { headers: H })).json();
} while (st.data.status !== "completed");

st.data.results.forEach(r => zapiszOpis(r.id, r.description_html));

Python (requests)

import requests, time
KEY = "sk_stockseo_..."; BASE = "https://stockseo.tojest.dev/ext/v1"
H = {"X-API-Key": KEY}

job = requests.post(f"{BASE}/content/product-bulk",
                    json={"products": produkty}, headers=H).json()
job_id = job["data"]["job_id"]

while True:
    time.sleep(5)
    st = requests.get(f"{BASE}/jobs/{job_id}", headers=H).json()
    if st["data"]["status"] == "completed": break

for r in st["data"]["results"]:
    zapisz_opis(r["id"], r["description_html"])

// zmiany API

Pytania o integrację? kontakt@stockseo.pl