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.

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.

Při komunikaci s API je nutné používat minimální verzi TLS 1.2.

Počet požadavků na API je omezen na 200/minutu.

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

Parametry požadavku

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

Parametry požadavku

Seznam rezervací

Požadavek

GET /reservation/list

Hlavička požadavku

Parametry požadavku

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

Číselník pro "reservationType"

Detail rezervace

Požadavek

GET /reservation/detail/{id}

Hlavička požadavku

Parametry požadavku

Detail rezervace na základě kódu rezervace

Požadavek

GET /reservation/detailByCode/{code}

Hlavička požadavku

Parametry požadavku

Storno rezervace

Požadavek

GET /reservation/cancel/{id}

Hlavička požadavku

Parametry požadavku

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

Seznam zdrojů typu "služba"

Požadavek

GET /resource/service

Hlavička požadavku

Seznam zdrojů typu "zaměstnanec"

Požadavek

GET /resource/employee

Hlavička požadavku

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

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

Parametry požadavku

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

Parametry požadavku

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

Parametry požadavku

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

Blokace času

Požadavek

GET /daysoff/list

Hlavička požadavku

Parametry požadavku

Doklady k platbám

Požadavek

GET /paymentdocument/list

Hlavička požadavku

Parametry požadavku

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

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.

Verze TLS

TLS (Transport Layer Security) je kryptografický protokol umožňující zabezpečený přenos dat po veřejné síti Internet v rámci protokolu HTTPS. Pro komunikaci s reenio API je nutné používat TLS ve verzi 1.2 a vyšší. Starší verze TLS budou podporovány pouze do 1. 10. 2021. Po tomto datu bude podpora starších verzí SSL/TLS vypnuta. Ujistěte se tedy prosím, že při komunikaci s API a jeho integraci používáte správnou verzi TLS.

Způsob jak verzi TLS nastavit závisí na programovacím jazyce a platformě, které používáte na své straně komunikace.

Důvodem k přechodu na novější verzi TLS je zvýšení zabezpečení komunikace mezi našim serverem a Vaší aplikací a naplnění dnes obecně uznávaných doporučení.

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

1. Nový koncový bod 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").

Důležité změny v API k 1. 10. 2021

1. Přechod na novější verzi certifikátů TLS (Transport Layer Security) pro veškerou komunikaci na HTTPS protokolu. Podporována je pouze TLS 1.2 a vyšší, starší verze TLS již nebudou dále podporovány a nebude tak možné vytvářet HTTP požadavky.