cs:api [LARPBuilder Wiki]

Tato stránka je pouze pro čtení. Můžete si pouze prohlédnout zdrojový kód, ale ne ho měnit. Zeptejte se správce, pokud si myslíte, že něco není v pořádku.
====== API ======
LARP Builder poskytuje endpoint **Players**, který slouží k práci s hráči – umožňuje získat seznam hráčů, detail konkrétního hráče a přidávat nové hráče do systému. API tak lze využít například pro registrační formulář na vlastních webových stránkách (WordPress, Drupal, statické stránky atd.) nebo pro integraci s jinými nástroji.

Pro přístup k API je vyžadována autorizace. Jsou podporovány dva hlavní mechanismy:
  - **API klíč (API Key)**: Každý projekt v LARP Builderu má vlastní API klíč. Ten musí být součástí každého požadavku (v hlavičce, formulářových datech či JSONu).
  - **Ověření zdroje požadavku (Origin)**: Server kontroluje, z jaké domény požadavek přichází. Pokud doména není povolená v nastavení projektu, server volání odmítne (//CORS a bezpečnost//).
  - **(Volitelně) Basic Auth**: Pro přístup k některým citlivějším částem API (nebo pro volání z nástrojů jako Postman) je vyžadováno přihlášení administrátora (email a heslo). Tento způsob umožňuje serveru ověřit, že uživatel má dostatečná práva k projektu.

====== Použití API na stránkách akce (HTML kód) ======
Níže je ukázka **Players** endpointu s webovým formulářem (např. registrační formulář pro hráče). V HTML formuláři se vyplní údaje o hráči (jméno, příjmení, email atd.) a spolu s nimi se odešle také API klíč. Odeslání probíhá ne klasickým //submit//, ale JavaScriptem, který zavolá API endpoint a data mu předá.

<code html>
<form id="apiForm" action="#" method="post">
    <!-- ... předdefinovaná povinná pole ... -->
    <label for="firstname">Jméno:</label>
    <input type="text" id="firstname" name="firstname" required />

    <label for="lastname">Příjmení:</label>
    <input type="text" id="lastname" name="lastname" required />

    <label for="email">E-mail:</label>
    <input type="email" id="email" name="email" required />

    <!-- ... další předdefinovaná nepovinná pole ... -->
    <!-- (výběr postavy, různé velikosti, poznámky atd.) -->

    <!-- Skrytá povinná pole s API klíčem a dalšími parametry -->
    <input type="hidden" id="api_key" name="api_key" value="VAŠ_API_KLÍČ" />
    <input type="hidden" id="lang" name="lang" value="cs"> 
    <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0">
    <input type="hidden" id="form_submit" name="form_submit" value="1">

    <button type="submit">Odeslat</button>
</form>

<!-- Potřebné skripty -->
<script src="https://larpbuilder.cz/api/js/jquery-3.7.1.slim.min.js"></script>
<script src="https://larpbuilder.cz/api/js/apiControl.js"></script>
</code>

**Poznámka:**  
  - `api_key` = **API klíč** získaný z LARP Builderu (v nastavení konkrétního projektu).  
  - V LARP Builderu je nutné **přidat doménu** vašich stránek mezi povolené (např. `mojedomena.cz`), aby server akceptoval požadavky z této domény.
  - Pokud chcete aby formulář napsal že registrace porběhla úspěšně či neúspěšně nastavte hodnotu "value" u alerts_enabled na 1 (<input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0">)
  - Můžete zmenit také jazyk jakým bude formulář odpovídat změněním cs v parametru lang jazyky na výběr jsou cs: čeština, en: angličtina, de: němčina, fr: francouzština, es: španělština
  - Parametr form_submit říká zda se má po odeslání do LB API formulář snažit o odeslání také jako by šlo oběžný formulář na stránkách (vhodné třeba pro další zpracování formulářových dat do vlastní databáze)

**Jak to funguje:**  
  - JavaScript v `apiControl.js` zachytí odeslání formuláře, sebere všechny údaje (včetně `api_key`) a pošle je metodou **POST** na `https://larpbuilder.cz/api/players/`.  
  - Server zkontroluje, zda doména (Origin) je povolená a API klíč je platný. Pokud ano, vytvoří nového hráče a vrátí JSON s výsledkem.  

====== Generování embed kódu formuláře vytvořeného v LARPBuilderu ======
V sekci **Seznam formulářů** je u již vytvořených formulářů k dispozici akce **Zobrazit HTML kód**, která automaticky generuje kompletní embed kód formuláře na základě uložených dat. Tento kód obsahuje kompletní HTML dokument s inline styly, speciálními typy polí jako je **scale** (bodovací škála), **paragraph** (odstavec) či **button** (tlačítko) a skrytými poli s aktuálním API klíčem který je uložitelný jako samostatná .html stránka nebo vložitelný například do Wordpressu bez nutnosti se více starat o HTML kód.

=== Výhody ===
  - **Samostatnost:** Embed kód je kompletní a nevyžaduje žádné další nastavení a skripty (kromě minimálně potřebných skriptů jquery a apiControl.js).
  - **Aktualizace:** Možnost dynamického doplnění selectů z databáze zajistí, že na webu bude vždy aktuální výběr.
  - **Kompatibilita:** Kód je vhodný pro různé CMS, například pro WordPress, kde jej lze vložit pomocí HTML bloku nebo shortcodu.
  - **Jednoduchost:** Stačí zkopírovat vygenerovaný kód a vložit jej na webovou stránku.

====== Jak vložit formulář do WordPress (nebo jiného CMS) ======
Pokud chcete snadno vložit vygenerovaný HTML kód formuláře do WordPressu, stačí postupovat následovně:

**Zkopírujte embed kód:**  Použijte postup tak jak je napsán o odstavec výše (tento kód obsahuje všechny potřebné části a je připravený ke kopírování), nebo si vytvořte vlastní formulář a připojte k němu nutná pole a potřebné javaskripty. 

**Vložte kód do příspěvku:**  Ve WordPressu přejděte na tvorbu nebo úpravu příspěvku. V editoru (Gutenberg) přidejte blok „Vlastní HTML“ a do něj vložte zkopírovaný embed kód. Pokud používáte klasický editor, přepněte na záložku HTML a vložte kód přímo tam.

**Uložte a publikujte:** Uložte změny a publikujte příspěvek. Formulář by se měl zobrazit přesně tak, jak byl vygenerován – s vlastními styly a funkcemi pro odeslání dat přes API.

** Otestování**: Otevřete stránku s formulářem, vyplňte jej a klikněte //Odeslat//. Po úspěchu se v administraci LARP Builderu objeví nový hráč s vyplněnými údaji. Pokud dojde k chybě (např. špatná doména, chybějící povinné pole), zobrazí se chybová hláška (v případě že je <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="1"> jinak se chybové hlášení nezobrazí).

Tento postup nevyžaduje žádné složité nastavení ani zásahy do šablony. Stačí zkopírovat hotový kód a vložit jej na stránku. WordPress se postará o zobrazení kódu bez zásahu do dalších souborů či nastavení.

**Tip:** Pokud se kód HTML a `<script>` v klasickém WordPress editoru //nezobrazí správně// nebo se //zahodí//, použijte místo toho blok //Vlastní HTML// (v novém Gutenberg editoru), případně shortcody v Code Snippets.  

===== Kde získám API klíč =====
    - V administraci LARP Builderu otevřete daný projekt.  
    - Přejděte do sekce //Nastavení projektu//.  
    - Najděte **API klíč** (obvykle v dolní části nastavení) a zkopírujte jej.  
    - Zároveň v této sekci přidejte //doménu//, ze které budete formulář volat (např. `moje-stranka.cz`), a uložte změny.

====== Použití API v Postmanu ======
Pro ladění a pokročilejší správu můžete využít nástroj [[https://www.postman.com/|Postman]]. Ukážeme tři operace s endpointem **Players**:

=== 1) Získání seznamu hráčů ===
  - **Metoda**: GET  
  - **URL**: ''https://larpbuilder.cz/api/players/''  
  - **Autorizace**:  
    - V //Headers// přidejte: ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''  
    - Pokud voláte z Postmanu a nechcete řešit povolenou doménu, použijte //Basic Auth// s přihlašovacími údaji administrátora (v záložce ''Authorization''). V Basic Auth vyplníte //Username = váš email// a //Password = vaše heslo// používané pro LARP Builder.  
  - **Očekávaný výsledek**: JSON seznam hráčů (pole objektů). Pokud žádní hráči nejsou, vrátí se prázdné pole.

=== 2) Získání detailu jednoho hráče ===
  - **Metoda**: GET  
  - **URL**: ''https://larpbuilder.cz/api/players/123'' (místo 123 dosaďte ID hráče)  
  - **Autorizace**: Stejně jako výše (API klíč + případně Basic Auth).  
  - **Očekávaný výsledek**: JSON s detaily hráče. Pokud ID neexistuje, vrátí se chyba 404.

=== 3) Přidání nového hráče ===
  - **Metoda**: POST  
  - **URL**: ''https://larpbuilder.cz/api/players/''  
  - **Tělo**: JSON (//raw body - application/json//) nebo //form-data// s požadovanými poli (např. ''firstname'', ''lastname'', ''email''). Minimální požadovaná jsou jméno, příjmení, email.  
  - **Hlavičky**: Opět ''AuthorizationKey: Bearer <nowiki><API_KLÍČ></nowiki>''. Pokud nejste na povolené doméně, použijte v Postmanu i Basic Auth (stejný postup jako výše).  
  - **Očekávaný výsledek**: ''{"success":"Player added successfully"}'' (HTTP 200) nebo chybová hláška (HTTP 4xx/5xx).

====== Chyby a jejich řešení ======
Nejčastější chyby při volání API **Players**:

  - **Neplatný API klíč nebo nepovolený origin**: Vrací se 403 s hláškou typu ''"Invalid API Key or unauthorized origin"''. Zkontrolujte správnost klíče a doménu projektu.
  - **Chybějící data**: Vrací se 400 (Bad Request) s informací o chybějících polích (např. ''"Field 'email' is required"''). Přidejte všechna povinná pole.
  - **Neautorizovaný přístup**: 401 (Unauthorized). Je nutné použít Basic Auth, pokud voláte z nedůvěryhodné domény, nebo pokud daná akce vyžaduje přihlášeného admina.
  - **Objekt nenalezen**: 404 (Not Found), např. když hráč s daným ID neexistuje.
  - **Interní chyba serveru**: 500 (Internal Server Error). Může jít o dočasný výpadek, chybu v datech nebo v kódu serveru.

====== Závěr ======
API LARP Builderu pro **Players** vám umožní integrovat správu hráčů do vlastních stránek a nástrojů. Základem je **API klíč** a volání z povolené domény (nebo Basic Auth pro administrátory).  

**Stručný postup**:
  - V administraci LARP Builderu: Získat API klíč a **přidat doménu** mezi povolené.  
  - Na svém webu (např. WordPress): Vložit HTML formulář s `api_key` a připojit JavaScript `apiControl.js`.  
  - Otestovat funkčnost (ideálně i v Postmanu).  

Po úspěšném odeslání se v LARP Builderu objeví nově přidaný hráč. Pokud narazíte na potíže, pomůže vám ladění v prohlížeči (konzole) nebo v Postmanu – chyby se vracejí v JSON odpovědích. Hodně štěstí s integrací!