Download the PHP package mervit/idoklad-v3 without Composer

iDoklad v3

PHP třída pro zasílání požadavků na iDoklad api v3.

Dokumentace iDoklad api v2

Dokumentace iDoklad api v3

Děkuji @malcanek za vytvoření v2, knihovnu jsem upgradoval na verzi 3 a dávám jí tímto k dispozici ostatním zájemcům

Změny v kodu proti verzi v2 od /iDoklad-v2

• Podstattná změna je v odpovědích, kdy bylo u listů TotalItems a TotalPages přesunuto pod parametr data. Položky listů tedy již nelze načíst metodou getData ale nově vzniklou metodou getItems. U existujících aplikací je tedy nutné při přechodu z verze 2 na verzi 3 zasáhnout do všech callu které vrací list výsledků.
• Přepracované jsou filtry, které nyní umožňují seskupování a zanořování podmínek a kombinací logických operátorů or a and
• Requesty GET nově podporují parametr select pro omezení dat ve výsledcích
• Requesty GET nově podporují také parametr include který umožňuje zahrnout do odpovědi i data z připojených entit

Vložení knihovny do projektu

Knihovnu vložíme do projektu naincludováním souboru src/iDoklad.php, nebo si knihovnu přidáme pomocí composeru. Následně se na knihovnu odkážeme pomocí use.

Zadáme naše client ID, client secret a v případě, že chceme použít OAuth2 autentifikaci i redirect URI. Nakonec si zavoláme objekt iDokladu, který zajišťuje veškerou komunikaci.

Autorizace pomocí OAuth2 - Authorization code flow

Autorizace pomocí OAuth probíhá v několika krocích. Jako client ID a client secret používáme údaje získané z developer portálu.

Nejdříve nabídneme uživateli URL adresu, kde zadá své přihlašovací údaje. Tu získáme pomocí nasledující metody:

Po zadání přihlašovacích údajů je uživatel přesměrován na zadanou redirect URI i s kódem, pomocí kterého získáme jeho credentials údaje. Kód zpracujeme následujícím způsobem:

Nyní jsou v instanci objektu založeny credentials a můžeme odesílat dotazy na iDoklad api. Credentials můžeme získat 2 způsoby. Získání credentials přímo z objektu:

Zpracování credentials pomocí credentials callbacku:

Callback funguje tak, že knihovna zavolá callback funkci vždy, když jsou změněny credentials. To se hodí, jelikož automaticky probíhá refresh tokenu po jeho vypršení.

Nahrání credentials do iDoklad objektu

Založení objektu s již existujícími credentials

Vložení credentials do již existujícího objektu

Poté co objekt obsahuje credentials, lze provádět dotazy do iDoklad api.

Autorizace pomocí OAuth2 - Client credentials flow

Tato metoda je jednodušší. Credentials získáme na základě client id a client secret, které získáme z nastavení účtu uživatele. Po založení objektu pouze zavoláme:

Jako u OAuth2 - Authorization code flow i zde funguje credentials callback.

Odesílání požadavků na iDoklad api

Pro odeslání požadavku na api slouží iDokladRequest objekt. Ten lze v nejjednodušší podobě založit pouze s jedním parametrem, který určuje akci dle dokumentace, a poté rovnou odeslat na api.

Získání dat z api

Pokud požadavek proběhne úspěšně, jsou zpět vrácena data v podobě iDokladResponse objektu. Nejdříve zkontrolujeme, zda požadavek proběhl v pořádku (návratová hodnota by měla být 200):

Poté můžeme získat samotná data v poli:

Odchytávání chyb

Třída vyhazuje vyjímky typu iDokladException.

Vytvoření nové faktury

Případně můžeme nově zadat method type pomocí fce, což by nyní vypadalo následovně:

Použití filtru a třídění

Pro použití filtru použijeme třídu iDokladFilter. Parametry můžeme zadat hned při založení třídy, první parametr je jméno pole, které chceme filtrovat, druhý parametr je operátor, poslední parametr je hodnota.

Vztahy mezi jednotlivými filtry můžeme definovat pomocí metody setFilterType.

Filtrů můžeme přidat několik a pomocí filterGroup třídy je můžeme seskupit.

Pro použití třídění použijeme třídu iDokladSort. Opět můžeme hned přidávat parametry, kdy první parametr je jméno pole a druhý parametr je dobrovolný a lze zadat, zda řadit vzestupně (asc) či sestupně (desc).

Stránkování a počet vrácených položek

Omezení výsledku

Pomocí metody addSelect můžeme omezit data, které API vrací a výrazně tím dobu zpracování požadavku

Zanořená data odělujeme tečkou

Můžeme přidat i více proměných odělené čárkou

Načtení připojených entit

Pomocí metody addInclude můžeme naopak rozšířit vrácené data o detaily připojených entit. Díky této funkci již nemusíme načítat detail připojené entity samostatným callem.

Zanořená data odělujeme tečkou

Můžeme přidat i více proměných odělené čárkou

Vyhazování exception při návratových kódech vyšších nebo rovno 400

Pokud chceme zapnout vyhazování exception při http návratových kódech vyšších rovno 400, stačí nám zavolat fci

Upload přílohy

Pokud chceme uploadovat přílohu, stačí nám použít metodu addFile nad request objektem.

Jiné úpravy

Pokud potřebujeme použít metody POST, PUT, PATCH, DELETE, použijeme k tomu metodu addMethodType nad objektem iDokladRequest.

Příklady

Příklady použití lze vidět v souborech acf.php a ccf.php. acf.php obsahuje příklad použití authorization code flow, ccf obsahuje příklad na client credentials flow, stačí doplnit vlastní client ID, client secret a redirect URI.

Příklad vytvoření faktury