API

Konfigurace API

Nejprve je potřeba API povolit a nastavit v administraci.

Otevřít konfiguraci:
Modules > PrestaBlog > Configuration > Tools > API

Dostupná nastavení:

• Povolit API: hlavní přepínač. Dokud je vypnutý, API neodpovídá na žádné požadavky.
• API klíč: klikněte na „Vygenerovat nový klíč“. Klíč se zobrazí pouze jednou — okamžitě si ho zkopírujte, později už nebude dostupný. Ukládá se pouze jeho kryptografický otisk (SHA-256). Pokud klíč ztratíte, vygenerujte nový.
• Automaticky aktivovat nové články: určuje, zda se články vytvořené přes API zveřejní ihned, nebo se uloží jako koncept, pokud požadavek tento parametr výslovně neobsahuje.
• Limit požadavků: maximální počet požadavků za minutu na jednu IP adresu (výchozí: 60).
• Zabezpečení obrázků: blokuje stahování obrázků z privátních/interních IP rozsahů. Doporučeno pro instalace dostupné z internetu.
• Za proxy: zapněte, pokud je váš obchod za Cloudflare, reverse proxy nebo CDN, aby se správně zpracovala klientská IP.
• Úroveň logů: None vypne logování. Security loguje neúspěšná ověření a blokace. Debug loguje všechny požadavky (dočasně pro diagnostiku).
• Povolené CORS originy: pouze pokud webová aplikace na jiné doméně potřebuje volat API z prohlížeče. Ve většině případů ponechte prázdné.

Oprávnění API

Sekce Oprávnění API umožňuje přesně omezit, co může API klíč provádět. Každou operaci lze zapnout nebo vypnout nezávisle — jak pro články, tak pro kategorie.

• Povolit vytváření článků / kategorií: povolí požadavky POST pro vytvoření nového obsahu.
• Povolit úpravy článků / kategorií: povolí požadavky PUT pro aktualizaci existujícího obsahu.
• Povolit mazání článků / kategorií: povolí požadavky DELETE. Vypněte, pokud chcete zabránit náhodnému smazání ze strany AI agenta nebo skriptu třetí strany.

Použití přes AI agenta (doporučeno)

Nejste vývojář nebo nechcete psát kód? Nejjednodušší metoda je použít AI agenta, například Claude, přes protokol MCP (Model Context Protocol). Agent přesně ví, jaká volání provést, řeší ověřování a rozumí vašim pokynům v přirozeném jazyce.

1. Povolte API a vygenerujte klíč

V administraci PrestaBlog: Tools > API. Povolte API, klikněte na „Generate a new key“ a zkopírujte zobrazený klíč — později už nebude dostupný.

2. Sestavte URL pro připojení MCP

URL pro připojení má tento formát:

https://prestablog-mcp.prestablog.workers.dev/mcp?key=YOUR_KEY&shop=https://your-shop.com

Nahraďte YOUR_KEY klíčem, který jste vygenerovali, a https://your-shop.com URL adresou vašeho obchodu.

Nezaměňujte to s „API URL“, což je jiná adresa používaná pro přímá volání.

3. Nastavení v Claude

V Claude klikněte vlevo nahoře na Customize, poté na Connectors,
v horní části sloupce, který se objeví, klikněte na tlačítko + a potom Add a custom connector.

Vyplňte:

• Name: libovolné (např. PrestaBlog API)
• URL: URL pro připojení MCP sestavené v kroku 2

Potvrďte. Claude nyní může přistupovat k vašemu blogu a přímo vytvářet, upravovat a mazat články i kategorie.

Příklady toho, co můžete Claude zadat:

• „Vytvoř článek o letních botách v kategorii Móda“
• „Vypiš 10 posledních publikovaných článků“
• „Změň název článku 42“
• „Vytvoř novou kategorii Novinky s tímto popisem“
• „Smaž kategorii 5“

4. Nastavení ve Windsurf

Ve Windsurf otevřete panel Cascade, klikněte na ... vpravo nahoře, poté na ikonu MCPs (poslední ikona vpravo dole v menu). Otevře se editor. Po správném vygenerování URL přidejte následující konfiguraci (viz krok 2):

{
  "mcpServers": {
    "prestablog": {
      "serverUrl": "https://prestablog-mcp.prestablog.workers.dev/mcp?key=YOUR_KEY&shop=https://your-shop.com"
    }
  }
}

Uložte. Cascade zobrazí dole v panelu 1 MCP, což potvrzuje aktivní připojení.

Příklady toho, co můžete Cascade zadat:

• „Vytvoř článek o letních botách v kategorii Móda“
• „Vypiš 10 posledních publikovaných článků“
• „Změň název článku 42“
• „Vytvoř novou kategorii Novinky s tímto popisem“
• „Smaž kategorii 5“

Autentizace (REST)

Každý požadavek musí obsahovat API klíč v HTTP hlavičce. Jsou podporovány dva formáty:

Authorization: Bearer YOUR_API_KEY

nebo

X-Api-Key: YOUR_API_KEY

Automatická blokace: po 5 neúspěšných pokusech o ověření ze stejné IP dojde k blokaci na 1 hodinu. Tuto dobu lze upravit v nastavení API.

Články

Seznam článků

GET /prestablog-api/articles

Vrací stránkovaný seznam článků. Dostupné parametry: lang (ID jazyka), page, per_page (max 100), active (1 = pouze publikované), category (ID kategorie), search (vyhledávání v názvu), sort (date, title, id), order (asc, desc).

curl -X GET "https://your-shop.com/prestablog-api/articles?lang=1&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_KEY"

Detail článku

GET /prestablog-api/articles/{id}

Vrací všechna data o článku: vícejazyčná pole, kategorie, přiřazené produkty, související články a obsah.

curl -X GET "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Vytvořit článek

POST /prestablog-api/articles

Minimální příklad:

curl -X POST "https://your-shop.com/prestablog-api/articles" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "Můj článek",
        "content": "<h2>Úvod</h2><p>Obsah článku.</p>"
      }
    },
    "categories": [1],
    "active": true
  }'

Kompletní příklad s obrázkem, vícejazyčným obsahem a metadaty:

{
  "languages": {
    "1": {
      "title": "Můj článek",
      "introduction": "Krátký text zobrazený v přehledech",
      "content": "<h2>Sekce</h2><p>Kompletní HTML obsah.</p>",
      "meta_title": "Můj článek - SEO titulek",
      "meta_description": "Popis pro vyhledávače",
      "meta_keywords": "slovo1, slovo2",
      "link_rewrite": "muj-clanek"
    },
    "2": {
      "title": "My article",
      "introduction": "Short text displayed in listings",
      "content": "<h2>Section</h2><p>Full HTML content.</p>"
    }
  },
  "categories": [2, 5],
  "active": true,
  "date": "2026-06-15 09:00:00",
  "enable_toc": true,
  "author_id": 1,
  "image": {
    "url": "https://example.com/image.jpg"
  }
}

Dostupná pole:

Upravit článek

PUT /prestablog-api/articles/{id}

Částečná aktualizace: upraví se pouze pole, která jsou v požadavku. Pole, která nejsou odeslána, si ponechají svou aktuální hodnotu. U jazyků se aktualizují pouze ty, které jsou v payload.

curl -X PUT "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "languages": {
      "1": {
        "title": "New title"
      }
    }
  }'

Smazat článek

DELETE /prestablog-api/articles/{id}

Smaže článek a všechna související data: obrázky (všechny varianty), kategorie, přiřazené produkty a související články.

curl -X DELETE "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Obrázek článku

POST /prestablog-api/articles/{id}/image

Dle kontextu jsou dostupné tři metody:

Vzdálená URL (obrázek je hostovaný online):

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

Lokální soubor (multipart upload):

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/image.jpg"

Base64 (fallback):

Poznámka: base64 je velmi objemné a u složitějších obrázků může být těžkopádné. Pokud je to možné, preferujte nahrávání přes vzdálenou URL.

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base64": "/9j/4AAQSkZJRg...", "filename": "photo.jpg"}'

Kategorie

API umožňuje vytvářet, zobrazovat, upravovat a mazat kategorie, stejně jako u článků.

Seznam kategorií

GET /prestablog-api/categories

Ve výchozím nastavení vrací kategorie ve formě stromu. Použijte flat=1 pro plochý seznam, active=1 pouze aktivní, lang pro jazyk.

curl -X GET "https://your-shop.com/prestablog-api/categories?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Detail kategorie

GET /prestablog-api/categories/{id}

Vrací všechna data kategorie: vícejazyčná pole, počet článků a přiřazené skupiny zákazníků.

Vytvořit kategorii

POST /prestablog-api/categories

Minimální příklad:

curl -X POST "https://your-shop.com/prestablog-api/categories" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "Novinky"
      }
    },
    "active": true
  }'

Kompletní příklad:

{
  "languages": {
    "1": {
      "title": "Novinky",
      "description": "<p>Všechny novinky z našeho obchodu.</p>",
      "meta_title": "Novinky - SEO titulek",
      "meta_description": "SEO popis kategorie",
      "meta_keywords": "novinky",
      "link_rewrite": "news"
    },
    "2": {
      "title": "News",
      "description": "<p>All the latest news from our shop.</p>",
      "link_rewrite": "news"
    }
  },
  "parent": 0,
  "position": 1,
  "active": true,
  "image": {
    "url": "https://example.com/category.jpg"
  }
}

Dostupná pole:

Upravit kategorii

PUT /prestablog-api/categories/{id}

Částečná aktualizace: upraví se pouze pole obsažená v požadavku.

curl -X PUT "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "New category name",
        "description": "<p>New description.</p>"
      }
    }
  }'

Smazat kategorii

DELETE /prestablog-api/categories/{id}

Smaže kategorii a všechna související data: obrázek, vazby na články a skupiny zákazníků.

curl -X DELETE "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY"

Obrázek kategorie

POST /prestablog-api/categories/{id}/image

Stejné tři metody jako u článků: vzdálená URL, lokální soubor (multipart) nebo base64.

Poznámka: base64 je velmi objemné a u složitějších obrázků může být těžkopádné. Pokud je to možné, preferujte nahrávání přes vzdálenou URL.

curl -X POST "https://your-shop.com/prestablog-api/categories/1/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/category.jpg"

Autoři

Autoři jsou v API dostupní pouze pro čtení. Musí být vytvořeni v administraci PrestaBlog.

• GET /prestablog-api/authors - seznam všech autorů
• GET /prestablog-api/authors/{id} - detail autora s vícejazyčnými biografiemi

curl -X GET "https://your-shop.com/prestablog-api/authors?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Kódy chyb

Všechny chybové odpovědi mají tento formát:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Human readable error message",
    "details": { "field": "languages.1.title" }
  }
}

Limit požadavků: při překročení limitu obsahuje odpověď 429 hlavičku Retry-After, která udává, kolik sekund máte počkat před dalším pokusem. Každá odpověď také obsahuje hlavičky X-RateLimit-Limit a X-RateLimit-Remaining.

Integrace s Pythonem

Pro vývojáře v Pythonu umožňuje knihovna requests komunikovat s API v několika řádcích.

pip install requests

import requests

BASE = "https://your-shop.com/prestablog-api"
KEY = "YOUR_KEY"
headers = {"Authorization": f"Bearer {KEY}"}

# Seznam článků
r = requests.get(f"{BASE}/articles", headers=headers, params={"lang": 1, "per_page": 10})
print(r.json())

# Vytvořit článek
r = requests.post(f"{BASE}/articles", headers=headers, json={
    "languages": {"1": {"title": "Můj článek", "content": "<p>Obsah</p>"}},
    "categories": [1],
    "active": True
})
print(r.json())

# Nahrát obrázek z lokálního souboru
with open("image.jpg", "rb") as f:
    r = requests.post(f"{BASE}/articles/18/image", headers=headers, files={"file": f})
print(r.json())