Volání API

Metody API rozhraní helpdesku se nachází na URL adresách "/api/*"

Drtivá většina volání musí obsahovat autentifikaci uživatele. Používá se BASIC HTTP autentifikace. K autentifikaci se použije login a heslo existujícího uživatele v helpdesku. S jeho autentifikací se potom volání API metody provádí.

Vytvoření požadavku

K vytvoření nového požadavku je potřeba:

volat API adresu POST api/Tickets/NewTicket
vyplnit BASIC HTTP autentifikaci existujícím uživatelem v helpdesku
tělo requestu může být buď v JSON nebo XML formátu, v minimální podobě je třeba zadat typ požadavku, předmět a text:

{
    "Type": "EndUserTicket",
    "Subject": "Test minima z API",
    "Message": "Text z API."
}

Obvykle je potřeba vytvářet požadavek do příslušné Služby - to platí vždy pro další typy požadavků, jako je Incident nebo Požadavek na službu. Její ID získáte z URL při editaci služby v Administraci helpdesku.

{
    "Type": "ServiceRequest",
    "ServiceId": 1,
    "Subject": "Test požadavku z API do služby",
    "Message": "Text z API."
}

Odezva úspěšného vytvoření požadavku je indikována standardně formou HTTP status code 200 a obsahuje ID vytvořeného požadavku, vypadá např. takto:

{
    "TicketREF": "TIC-016558",
    "TicketId": 16558
}

Pokud naopak dojde k chybě, HTTP status code je chybový a obvykle je vrácena i informace o chybě, např.:

Vytváření nového požadavku umožňuje zadat mnoho parametrů požadavku, např. přílohy, HTML podobu textu, prioritu, vyplnit vlastní formulář přímo v helpdesku, štítky, provázat s e-mailovou schránkou pro následnou odpověď apod.

Úplnou dokumentaci rozhraní API naleznete přímo v prohlížeči na url adrese "/api".

Zadavatel požadavku

Pokud neznáme jméno a heslo uživatele, který požadavek zakládá, existují i další způsoby, jak požadavek založit. Jedním z nich je použít BASIC autentifikaci některého operátora nebo administrátora, který požadavek založí za jiného uživatele. Operátora či administrátora proto, protože má k takové funkci - zadávat za někoho jiného - oprávnění. Potom lze vytvořit nový požadavek za uživatele buď zadáním parametru SubmitterUserProviderKey (pokud známe přímo ID uživatele, nebo jej na API vyhledáme), nebo pomocí parametru SubmitterEmail (pokud známe jeho emailovou adresu). V případě emailové adresy se jedná o nejjednodušší způsob, jak vytvořit požadavek a spárovat ho se zadavatelem podle jeho emailové adresy. Pokud emailová adresa v systému dosud neexistuje, bude vytvořen nový účet automaticky. Volání potom může vypadat třeba následovně:

POST api/Tickets/NewTicket

Vhodné je spárovat požadavek i s konkrétní příchozí emailovou schránkou pomocí parametru ServiceMailboxId, kterou helpdeskový systém vybírá. Poté budou případné odpovědi uživateli chodit emailem právě z této emailové schránky. Její ID zjistíme opět pomocí editace příchozí emailové schránky v administraci helpdesku.

Pro BASIC autentifikaci operátora nebo administrátora je vhodné vytvořit v helpdesku k tomu speciální uživatelský účet a ten v API klientovi používat.

Platí pro helpdeskový systém verze 5.2.6 a vyšší.

VOIPEX DOCS

Založení nového požadavku přes API helpdesku

Volání API

Vytvoření požadavku

Zadavatel požadavku