LARP Builder poskytuje REST API, které umožňuje externě spravovat data LARP aplikace. Konkrétně endpoint Players 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 (např. vlastní CRM).

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="from_submit" name="from_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.

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.

Pokud chcete formulář umístit například na WordPress web:

Získání API klíče v LARP Builderu:

1. V administraci LARP Builderu otevřete daný projekt, přejděte do sekce Nastavení projektu a najděte API klíč.
2. Zkopírujte tento klíč a vložte jej do `value=„VAŠ_API_KLÍČ“` v HTML kódu.

Povolení domény:

1. V Nastavení projektu přidejte doménu, ze které budete formulář volat (např. `moje-stranka.cz`).
2. Uložte změny, aby LARP Builder povolil CORS požadavky z této domény.

Vložení HTML formuláře:

1. Ve WordPressu nelze vždy vkládat `<form>` a `<script>` přímo do textového editoru. Využijte např. plugin (Insert Headers and Footers, Code Snippets), nebo upravte šablonu (soubor page.php, single.php nebo footer.php).
2. Zkopírujte kód formuláře (výše) do místa, kde se má formulář zobrazit.
3. Upravte `value=„VAŠ_API_KLÍČ“` na skutečnou hodnotu klíče.

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

1. Pokud je už ve WordPressu jQuery, můžete vynechat link na `jquery-3.7.1.slim.min.js`. Jinak jej vložte stejně jako v ukázce.
2. Vložit `<script src=„https://larpbuilder.cz/api/js/apiControl.js“></script>` do `<head>` nebo těsně před `</body>`.
3. Případně použijte funkci `wp_enqueue_script()` ve functions.php.

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 hláška.

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).
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.
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. Získat API klíč v LARP Builderu a vložit jej do kódu formuláře (pole `api_key`).
2. Přidat svou doménu mezi povolené v nastavení projektu.
3. Vložit HTML formulář a JavaScript (apiControl.js) na své stránky.
4. 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í!