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

Součástí integrace je použití Players endpointu pomocí webového formuláře (např. registrační formulář pro hráče).

Princip formulář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 ... -->
        <label for="character_ids">Postava:</label>
        <select name="character_ids" id="character_ids">
            <option></option>
            <option value="160">Arwen</option> <!-- ... seznam postav podle jejich ID ... -->
        </select>
 
        <label for="zazitky">To nejdůležitější: Tři věty, co chceš hrát:</label>
        <textarea id="zazitky" name="zazitky"></textarea>
 
        <label for="cinnosti">To nejdůležitější: Tři věty, co chceš na hře dělat:</label>
        <textarea id="cinnosti" name="cinnosti"></textarea>
 
        <label for="size_head">Obvod hlavy</label>
        <input type="number" id="size_head" name="size_head" min="0" max="999" value="0">cm
 
        <label for="size_breast">Obvod hrudi</label>
        <input type="number" id="size_breast" name="size_breast" min="0" max="999" value="0">cm
 
        <label for="size_waist">Obvod pasu</label>
        <input type="number" id="size_waist" name="size_waist" min="0" max="999" value="0">cm
 
        <label for="size_hips">Obvod boků</label>
        <input type="number" id="size_hips" name="size_hips" min="0" max="999" value="0">cm
 
        <label for="size_clothes">Konfekční velikost (např. trička)</label>
        <select name="size_clothes" id="size_clothes">
            <option></option>
            <option value="XS">XS</option>
            <option value="S">S</option>
            <option value="M">M</option>
            <option value="L">L</option>
            <option value="XL">XL</option>
            <option value="2XL">2XL</option>
            <option value="3XL">3XL</option>
            <option value="4XL">4XL</option>
            <option value="5XL">5XL</option>
            <option value="6XL">6XL</option>
            <option value="7XL">7XL</option>
            <option value="8XL">8XL</option>
            <option value="9XL">9XL</option>
        </select>
 
        <label for="size_type">Typ</label>
        <select name="size_type" id="size_type">
            <option></option>
            <option value="F">Dámské</option>
            <option value="M">Pánské</option>
        </select>
 
        <label for="avatar">Avatar</label>
        <input type="file" id="avatar" name="avatar" accept="image/jpeg, image/png, image/gif">
 
 
    <!-- 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"> <!-- Skryté pole pro jazyk cs (češtna) en (english) -->
    <input type="hidden" id="alerts_enabled" name="alerts_enabled" value="0"> <!-- Skryté pole pro povolení nebo zakázání alertů -->
    <input type="hidden" id="from_submit" name="from_submit" value="1"> <!-- Skryté pole pro povolení nebo zakázání alertů -->
 
    <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>

Důležité je, aby vaše doména s registrací byla stejná jako ta, která je v LARP Builderu povolená pro daný projekt.

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, zadejte 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). Při implementaci se zaměřte na:

1. Správné nastavení hlaviček (AuthorizationKey),
2. Ošetření chybových stavů,
3. Bezpečné ukládání API klíče (neprozrazujte jej veřejně).

Doporučujeme nejprve vše otestovat v Postmanu (GET/POST požadavky), a poté nasadit do produkčního prostředí s ohledem na bezpečnost a spolehlivost. Pokud narazíte na potíže, hlášky v odpovědích JSON většinou napoví, kde je problém.