API

API (Application Programming Interface) poskytuje datové rozhraní pro přístup k datům v rámci konkrétního rezervačního systému (konkrétního subjektu). Pomocí programového přístupu je díky API možné získávat informace o rezervacích a zpracovávat je v dalších/externích aplikacích.

Níže uvedený popis datového rozhraní je určen pro odborníky a obsahuje technické informace a specifikace!

Tato funkcionalita je dostupná pouze v balíčku PREMIUM.

API pro předávání dat do iframe integrace

V určitých případech může být vhodné předat počáteční data o zákazníkovi přímo do integrovaného rezervačního formuláře. Podobně pak může být vhodné ovlivnit, co se má stát po úspěšném provedení rezervace. Pokud máte systém reenio vložený do vlastního webu, je toto možné pomocí doplnění skriptu pro vložení. Níže je uvedena ukázka, která rozšiřuje standardní podobu kódu pro integraci o atributy data-api-ready a data-reservation-created. Předvyplnění vlastních položek rezervačního formuláře není podporováno.

<script>
    function onApiReady(api){
        api.setCustomer({
            firstName: 'Pepa',
            lastName: 'Novák',
            email: 'pepa@reenio.cz',
            phone: '+420123....'
        });
    }

    function onReservationCreated(){
        // TODO: redirect?
    }
</script>
<div class="reenio-iframe" data-size="auto" data-url="/service/seo-konzultace-zdarma-1234;viewMode=7-days;hideResources=1" data-api-ready="onApiReady" data-reservation-created="onReservationCreated"></div>
<script src="https://reenio.cz/cs/GEAA321A/widget-iframe.js" async defer></script>

Obecné informace

REST API je dostupné na adrese https://reenio.cz/cs/api/v1/admin/.

Pro veškerou příchozí i odchozí komunikaci s API je použito kódování UTF-8.

Pokud není uvedeno jinak, je datum a čas používaný při komunikaci s API v časové zóně UTC. Formát data a času se řídí standardem ISO 8601.

Detailní popis API naleznete na adrese: https://reenio.cz/api-docs/

Autentizace

Přístup k REST API je zabezpečen pomocí API klíče, který získáte po přihlášení do administrace systému reenio (https://reenio.cz/cs/admin/#/settings/api). Tento klíč je vždy svázán se subjektem a uživatelem, který jej vytvořil. Díky tomu máte při komunikaci s API stejná oprávnění jako daný uživatel. API klíč udržujte vždy v tajnosti. V případě podezření na jeho odcizení jej stačí v administraci odstranit a vytvořit nový.

Klíč je potřeba předávat v rámci všech požadavků na API a to v HTTP dotazu prostřednictvím Authorization: Bearer <ApiKey>. Například:

Authorization: Bearer Ky3Ancs1D2Nd33W6MQ2e9Db5

Seznam zákazníků

Požadavek
GET /customer/list
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
limit Maximální počet záznamů na stránku (maximálně 100). ne int

Tento koncový bod využívá stránkování odpovědí API.

Detail zákazníka

Požadavek
GET /customer/detail/{id}
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
id ID zákazníka ano int

Seznam rezervací

Požadavek
GET /reservation/list
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. ano string
end Datum konce požadovaného období ve formátu ISO 8601. ano string
includeCancelled Má výsledek obsahovat i stornované rezervace? ne bool
includeAlternate Má výsledek zahrnovat i náhradníky? ne bool
limit Maximální počet záznamů na stránku (maximálně 500). ne int

Tento koncový bod využívá stránkování odpovědí API.

Poznámka

Dotazované období může být maximálně 90 dní. V případě potřeby získat data na delší období je potřeba provést více dotazů.

Možné stavy rezervace
Stav Název
0 nová
1 potvrzená
2 stornovaná
3 neproběhla
4 proběhla
5 nedorazil
Číselník pro "reservationType"
Hodnota Název
1 interval
2 celý jeden termín
4 celá sekvence
5 místenky / sedadla
6 libovolný čas
7 vícedenní
8 poukaz

Detail rezervace

Požadavek
GET /reservation/detail/{id}
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
id ID rezervace ano int

Detail rezervace na základě kódu rezervace

Požadavek
GET /reservation/detailByCode/{code}
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
code Kód rezervace ano string

Storno rezervace

Požadavek
GET /reservation/cancel/{id}
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
id ID rezervace ano int
Odpověď serveru

V případě úspěšného storna vrátí server HTTP stavový kód 200 (OK). Pokud není možné rezervaci stornovat prostřednictvím API (například z důvodu, že je již uhrazena), bude vrácen stavový kód 405 (Method Not Allowed).

Seznam zdrojů typu "místo"

Požadavek
GET /resource/place
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>

Seznam zdrojů typu "služba"

Požadavek
GET /resource/service
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>

Seznam zdrojů typu "zaměstnanec"

Požadavek
GET /resource/employee
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>

Detail přihlášeného uživatele

Přihlášeným uživatele se myslí uživatel, pro nějž byl vystaven API klíč.

Požadavek
GET /user/info
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>

Seznam termínů typu "Celý jeden termín"

Odpověď obsahuje pouze základní informace o termínu.

Požadavek
GET /event/singleevent
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. ano string
end Datum konce požadovaného období ve formátu ISO 8601. ano string
Poznámka

Dotazované období může být maximálně 31 dní. V případě potřeby získat data na delší období je potřeba provést více dotazů.

Seznam termínů typu "Celá sekvence"

Odpověď obsahuje pouze základní informace o termínu.

Požadavek
GET /event/sequence
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. ano string
end Datum konce požadovaného období ve formátu ISO 8601. ano string
Poznámka

Dotazované období může být maximálně 31 dní. V případě potřeby získat data na delší období je potřeba provést více dotazů.

Definice termínů

Toto API vrací pouze základní vlastnosti termínů. Data obsahují popis termínu, tak jak byl zadán v administraci systému.

Požadavek
GET /eventdefinition/singleevent
GET /eventdefinition/interval
GET /eventdefinition/customtime
GET /eventdefinition/sequence
GET /eventdefinition/seats
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. ano string
end Datum konce požadovaného období ve formátu ISO 8601. ano string
Poznámka

Dotazované období může být maximálně 31 dní. V případě potřeby získat data na delší období je potřeba provést více dotazů.

Dny volna

Požadavek
GET /daysoff/list
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. ano string
end Datum konce požadovaného období ve formátu ISO 8601. ano string

Doklady k platbám

Požadavek
GET /paymentdocument/list
Hlavička požadavku
Název hlavičky Hodnota
Accept application/json
Authorization Bearer <ApiKey>
Parametry požadavku
Název parametru Popis parametru Povinný Datový typ
start Datum počátek požadovaného období ve formátu ISO 8601. Jedná se o datum dokončení platby. ano string
end Datum konce požadovaného období ve formátu ISO 8601. Jedná se o datum dokončení platby. ano string

Stránkování odpovědí API

Koncové body API podporující stránkování vracejí v rámci odpovědi serveru kromě požadovaných dat také vlastnosti "hasNextPage" a "nextPage". Vlastnost "nextPage" obsahuje absolutní URL pro získání další stránky s daty. Odkaz na další stránku je vrácen vždy, a to i přesto, že žádná další data nemusejí aktuálně existovat. To, jestli nějaká další data v daný okamžik existují udává vlastnost "hasNextPage" (true/false). Příklad odpovědi koncového bodu podporujícího stránkování:

{
    "list":[
        {
            "id":1884,
            ....
        ...
        },
        ...
        ...
    ],
    "hasNextPage": true,
    "nextPage":"https://reenio.cz/cs/api/v1/admin/reservation/list?continuationToken=91b7PM"
}

Pro získání další stránky použijte URL tak jak ji vrátilo API. Do URL již není potřeba přidávat další parametry požadavku (každá následující stránka má automaticky stejné vlastnosti jako ta první). Autentizace během stránkování probíhá stejným způsobem jako při dotazu na požadovaný koncový bod.

Pseudokód pro získání všech požadovaných dat z API:

var url = "https://reenio.cz/cs/api/v1/admin/reservation/list?start=2020-10-27&end=2020-12-27&limit=5";
var response = null;
do {
    response = ...; // požadavek na data
    // TODO: zpracování dat

    url = response.nextPage;
} while(response.hasNextPage);

V průběhu stránkování je zajištěno, že nově vzniklá data budou vždy na následující stránce. Díky tomu je možné pokračovat ve stránkování i s odstupem času. Stačí si v okamžiku, kdy bude mít vlastnost "hasNextPage" hodnotu false, uložit adresu další stránky (nextPage). A o pár hodin později vytvořit požadavek na tuto stránku. Odpověď bude obsahovat pouze nově vzniklá data. Během stránkování je potřeba postupovat vždy kupředu. Tedy každý následující požadavek musí vést na "nextPage" předchozí odpovědi (požadavek by nikdy neměl směřovat opakovaně na tutéž stránku).

Počet položek na stránce lze ovlivnit pomocí parametru "limit". Tento limit se může pro jednotlivé koncové body lišit.

Důležité změny v API k 4. 2. 2021

  1. Nový koncový body pro detail rezervace na základě kódu rezervace.
  2. Vlastnost "Resources" v popisu termínů bude v budoucnu odstraněna. Byla nahrazena vlastností "ResourceVariants".
  3. Nový princip stránkování odpovědí API ("hasNextPage" + "nextPage").