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:

1. 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).
2. 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).
3. (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.

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á.

<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>

Poznámka:

1. `api_key` = API klíč získaný z LARP Builderu (v nastavení konkrétního projektu).
2. 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.
3. 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“>)
4. 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
5. 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:

1. 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/`.
2. 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.

V nové verzi API LARP Builderu je k dispozici metoda, 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, dynamicky aktualizovanými select poli (např. pro výběr postavy či hráče), 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.

* Metoda get_form_as_embed_code() načte formulář z databáze a ověří, že patří aktuálnímu projektu (pomocí `project_id`). * Dynamicky doplní možnosti select polí z aktuální databáze (například u character_ids a player_ids). * Na základě uložených definic formuláře sestaví kompletní HTML kód, který obsahuje:

1. Inline CSS podle nastavení formuláře (barvy, font, velikost textu).
2. Všechny vstupní prvky formuláře.
3. Skrytá pole, kde je automaticky vložen aktuální API klíč.
4. Načtení minimálně potřebných skriptů (jQuery a apiControl.js) pro zpracování odeslání.

* Výsledný embed kód lze zkopírovat a vložit do jakéhokoli webu (například do WordPressu) bez nutnosti další konfigurace.

<!DOCTYPE html>
<html lang="cs">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Registrace</title>
  <style>body { background-color: #004708; color: #FFF200; font-size: 23px; font-family: Georgia, serif; }</style>
</head>
<body>
  <form id="apiForm" action="#" method="post" enctype="multipart/form-data">
    <p>Nějaký třeba nadpisový text</p><br>
    <label for="firstname">Jméno:</label>
    <input type="text" id="firstname" name="firstname" required><br>
    <label for="lastname">Příjmení:</label>
    <input type="text" id="lastname" name="lastname" required><br>
    <label for="email">E-mail:</label>
    <input type="email" id="email" name="email" required><br>
    <!-- Další pole podle uložených dat formuláře, včetně dynamických selectů a speciálních typů -->
    ...
    <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="1">
    <input type="hidden" id="form_submit" name="form_submit" value="1">
    <button type="submit">Odeslat</button>
  </form>
  <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>
</body>
</html>

1. 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).
2. Aktualizace: Možnost dynamického doplnění selectů z databáze zajistí, že na webu bude vždy aktuální výběr.
3. Kompatibilita: Kód je vhodný pro různé CMS, například pro WordPress, kde jej lze vložit pomocí HTML bloku nebo shortcodu.
4. Jednoduchost: Stačí zkopírovat vygenerovaný kód a vložit jej na webovou stránku.

Pokud chcete formulář umístit například na WordPress web, postupujte následovně:

1) Získání API klíče v LARP Builderu (pokud jej nekopírujete z vygenerovaného formuláře jako HTML kód tam již váš klíč je)

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

2) Vložení HTML formuláře do WordPressu

1. Možnost A – úprava šablony: Otevřete soubor page.php (nebo jiný .php soubor vaší šablony) a na vhodné místo vložte výše uvedený kód formuláře. Změňte `value=„VAŠ_API_KLÍČ“` na váš skutečný klíč.
2. Možnost B – použití pluginu (doporučeno, pokud nechcete zasahovat do šablony):
   1. Nainstalujte a aktivujte plugin, který umožňuje vkládat vlastní HTML/JS. Například:
      1. Insert Headers and Footers
      2. Code Snippets
   2. V administraci WP přejděte do Nastavení → Insert Headers and Footers (nebo do rozhraní Code Snippets) a do sekce, kde lze vkládat kód, vložte HTML formulář (u Code Snippets zvolte typ „HTML Snippet“ či „Shortcode“).
   3. Případně upravte `value=„VAŠ_API_KLÍČ“` na reálnou hodnotu.
   4. Uložte. Na stránce se pak objeví formulář.

3) Načtení skriptů (`apiControl.js` a jQuery)

1. Pokud už WordPress načítá jQuery, můžete link na `jquery-3.7.1.slim.min.js` vynechat.
2. Kód `<script src="https://larpbuilder.cz/api/js/apiControl.js"></script>` vložte do Insert Headers and Footers v sekci „Scripts in Footer“ nebo pomocí `wp_enqueue_script()` ve functions.php.
3. Ujistěte se, že se skripty načítají po načtení formuláře, aby mohl JavaScript reagovat na událost submit.

4) Otestování

1. Otevřete stránku s formulářem, vyplňte pole a klikněte Odeslat.
2. 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.

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.

Pro ladění a pokročilejší správu můžete využít nástroj Postman. Ukážeme tři operace s endpointem Players:

1. Metoda: GET
2. URL: https://larpbuilder.cz/api/players/
3. Autorizace:
   1. V Headers přidejte: AuthorizationKey: Bearer <API_KLÍČ>
   2. 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.
4. Očekávaný výsledek: JSON seznam hráčů (pole objektů). Pokud žádní hráči nejsou, vrátí se prázdné pole.

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

1. Metoda: POST
2. URL: https://larpbuilder.cz/api/players/
3. 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.
4. Hlavičky: Opět AuthorizationKey: Bearer <API_KLÍČ>. Pokud nejste na povolené doméně, použijte v Postmanu i Basic Auth (stejný postup jako výše).
5. Očekávaný výsledek: {„success“:„Player added successfully“} (HTTP 200) nebo chybová hláška (HTTP 4xx/5xx).

Nejčastější chyby při volání API Players:

1. 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.
2. 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.
3. 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.
4. Objekt nenalezen: 404 (Not Found), např. když hráč s daným ID neexistuje.
5. Interní chyba serveru: 500 (Internal Server Error). Může jít o dočasný výpadek, chybu v datech nebo v kódu serveru.

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:

1. V administraci LARP Builderu: Získat API klíč a přidat doménu mezi povolené.
2. Na svém webu (např. WordPress): Vložit HTML formulář s `api_key` a připojit JavaScript `apiControl.js`.
3. 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í!