API rozhraní

FAYN ústředna poskytuje API rozhraní pro integraci s aplikacemi třetích stran – například call centrem, hotelovým systémem nebo CRM. Tento návod shrnuje, co API umí, jak jej na ústředně povolit a jak s ním začít komunikovat.

Co API umožňuje

Přes API může aplikace třetí strany s ústřednou obousměrně komunikovat a provádět zejména tyto operace:

Dotazy– zjišťování parametrů a stavu ústředny (klapky, trunky, fronty, CDR záznamy, nahrávky…)
Konfigurace – vytváření a úprava funkcí ústředny (klapky, příchozí pravidla, IVR, fronty…)
Řízení hovorů – vytáčení, přepojování, přijímání či odmítání příchozích hovorů
Sledování událostí (webhook) – ústředna aktivně hlásí změny v reálném čase (stavy klapek, příchozí hovory, záznamy hovorů, změna v hovorech…)

Dva způsoby komunikace

Metoda	Princip
Dotaz / odpověď	Aplikace volá API a ústředna vrací odpověď – dotazy na data, konfiguraci, řízení hovorů.
Webhook	Aplikace se přihlásí k odběru vybraných událostí a ústředna je sama aktivně odesílá v okamžiku, kdy nastanou.

Povolení API na ústředně

Před připojením aplikace je potřeba API na ústředně zapnout a nastavit.

Přihlaste se do webové administrace ústředny a přejděte do menu Integrace › API.
Zapněte přepínač API.
Volitelně: aktivujte IP Restrikce a přidejte alespoň jednu povolenou IP adresu s maskou podsítě. API pak půjde využívat pouze z těchto adres – doporučujeme z bezpečnostních důvodů nastavit.
Volitelně: aktivujte odběr událostí a zadejte URL kam se budou webhooky zasílat.
V sekci Pokročilé nastavení zapněte podle potřeby monitor stavu klapek a trunků.
Klikněte na Uložit.

Přístupové údaje Po zapnutí API zobrazí ústředna ID klienta a heslo klienta. Tyto údaje slouží k vyžádání přístupového tokenu – uchovávejte je v bezpečí.

Blokace IP adres Pokud aplikace překročí povolený počet neúspěšných pokusů o autentizaci, ústředna její IP adresu zablokuje. Adresu lze odblokovat v seznamu blokovaných IP adres na ústředně.

Základy komunikace

Protokol: HTTPS, metody GET (dotazy) a POST (vytváření, úpravy, operace)
Port: shodný s webovým přístupem ústředny – HTTPS port 443
Formát odpovědí: JSON

Průběh požadavku

Aplikace vystupuje jako klient, ústředna jako server. Pro každý požadavek se naváže nové TCP spojení, které se po vrácení odpovědi uzavře. Při prvním požadavku aplikace odešle přihlašovací údaje a získá přístupový token; ten pak přikládá ke každému dalšímu volání.

Aplikace→ Žádost o token (Client ID + Secret)→ Ústředna vrátí access token→ API volání s tokenem

Autentizace a struktura požadavku

API využívá protokol OAuth 2.0. Pro autentizaci slouží tři rozhraní:

Metoda	Endpoint	Popis
`POST`	`get_token`	Získání přístupového tokenu pomocí Client ID a Client Secret.
`POST`	`refresh_token`	Obnovení tokenu – access token vyprší po 30 minutách.
`GET`	`del_token`	Zneplatnění (revokace) tokenu, např. při jeho kompromitaci.

Současně lze mít vygenerovaných až 8 tokenů. Doporučujeme využívat endpoint "`refresh_token`"

Formát URL požadavku

{base_url}/{api_path}/{endpoint}?access_token={access_token}

base_url   → https://{doména-ústředny} - například vh111.cloud.fayn.cz
api_path   → openapi/v1.0   (u vybraných rozhraní, např. CDR, také openapi/v2.0)
endpoint   → konkrétní API rozhraní, např. extension/update

Příklad požadavku (Postman)

Získání tokenu:

Získání stavu příchozí pravidel:

API endpointy

Endpointy a další dokumenty naleznete na stránkách [PBX API]