Fio API – PHP třída – verze 2.0 – stahování transakcí

Přejít na hlavní stránku Fio API třídy

Pro připojení této třídy k FIO bance potřebujete token, který získáte v internetovém bankovnictví (Informace o účtu, potom úplně dole). PHP třída využívá knihovnu CURL a SSL. Bez toho ji na svém serveru nerozjedete.

1 Quick start

require_once('fioapi.class.php');

try {
    $fioapi = new FioApi('TOKEN');
    $fioapi->downloadByPeriod(new DateTime('-1 month'), new DateTime());

    print_r($fioapi->getTransactions());

} catch (FioApiException $e) {
    echo $e->getMessage();
}

Vypíše se pole, které obsahuje všechny transakce (pohyby na účtu) za poslední měsíc. Pole vypadá podobně jako toto:

Array
(
    [0] => Array
        (
            [transactionId] => 3541843462
            [instructionId] => 4066058524
            [date] => DateTime Object
                (
                    [date] => 2013-10-05 00:00:00
                    [timezone_type] => 3
                    [timezone] => Europe/Prague
                )

            [amount] => -100
            [currency] => CZK
            [account] => 1234567890
            [accountName] =>
            [bankCode] => 0100
            [bankName] => Komerční banka a.s.
            [constantSymbol] => 1234
            [variableSymbol] => 1234
            [specificSymbol] =>
            [user_note] => uživatelská identifikace
            [message] =>
            [type] => Bezhotovostní platba
            [performed] =>
            [specification] =>
            [comment] => komentář
            [bic] =>
        )
    [1] => Array
        (
            ...
        )
)

Jednotlivé transakce samozřejmě můžeme procházet:

foreach($fioapi->getTransactions() as $transaction){
    echo($transaction['date']->format('d.m.Y')." ".$transaction['amount']."<br>");
}

2 Spuštění, nastavení třídy

$fioapi = new FioApi('TOKEN');

Doporučuji využít možnosti zabezpečeného připojení. K tomu budeme potřebovat certifikát, který je možné stáhnout na adrese http://www.geotrust.com/…ertificates/ (Root 1 – Equifax Secure Certificate Authority). Certifikát si uložte např. do stejného adresáře, jako skript. Odkazujete pak na jeho plnou cestu:

$fioapi = new FioApi('TOKEN',__DIR__ . '/certificate.pem');

Certifikát můžete případně doplnit (před stažením dat, potom už je zbytečný) následující metodou. Obě možnost jsou rovnocenné.

$fioapi = new FioApi('FIO TOKEN');
$fioapi->setCertificate(__DIR__ . '/certificate.pem');

3 Stažení dat

Pro stažení dat jsou připraveny metody začínající na „download“. Tyto metody data stáhnou, zatím je nevypisují.

3.1 Transakce za určité období

$fioapi->downloadByPeriod(new DateTime('-1 month'), new DateTime());

Pozn.: Není možné zadávat konkrétní čas, bere se v úvahu pouze datum.

3.2 Transakce od posledního stažení (nebo od zarážky – viz dále)

$fioapi->downloadLast();

3.3 Výpis z účtu

$fioapi->downloadStatement(2014, 2);

4 Nastavení zarážky

Nastavení zarážky slouží k označení transakce nebo dne, od kterého se budou stahovat transakce metodou downloadLast().

4.1 Zarážka na ID transakce

Označuje ID transakce, které bylo jako poslední úspěšně zpracováno při předchozím zpracování. Při následném použití metody downloadLast() se stáhnou transakce, které následují po označené transakci.

$fioapi->setLastId(1234567);

4.2 Zarážka na datum

Označuje první den, které nebyl úspěšně zpracován. Při následném použití metody downloadLast() se stáhnou transakce, které proběhly v označený den a v následující dny.

$fioapi->setLastDate(new DateTime('-1 day'));

5 Získání dat

Metody začínající na „get“ vrací stažená data. Tyto metody volejte až po stažení dat, jinak se logicky nic nevrátí (tedy vrátí se prázdný Array()).

5.1 Výpis hlavičky

$header=$fioapi->getHeader();

Výsledkem je pole v této struktuře:

Array
(
    [accountId] => 1234567890
    [bankId] => 2010
    [currency] => CZK
    [iban] => CZ12345678901234567890
    [bic] => FIOBCZPPXXX
    [openingBalance] => 1000.25
    [closingBalance] => 2000.35
    [dateStart] => DateTime Object
        (
            [date] => 2013-09-13 00:00:00
            [timezone_type] => 3
            [timezone] => Europe/Prague
        )
    [dateEnd] => DateTime Object
        (
            [date] => 2014-02-13 00:00:00
            [timezone_type] => 3
            [timezone] => Europe/Prague
        )
    [yearList] =>
    [idList] =>
    [idFrom] => 3537322837
    [idTo] => 3572047687
    [idLastDownload] =>
)

5.2 Výpis transakcí

$header=$fioapi->getTransactions();

Pozn.: Jak vypadá vypsané pole transakcí můžete vidět v Quick Startu.

5.3 Zjednodušený výpis transakcí

Výpis pouze některých (zadefinovaných) hodnot každé transakce.

$header=$fioapi->getTransactionsSimple();

Výstupem je pole:

Array
(
    [0] => Array
        (
            [amount] => 29
            [currency] => CZK
            [variableSymbol] =>
        )

    [1] => Array
        (
            ...
        )

K čemu to je dobré? Můžete jednoduše kontrolovat, zda byla nějaká platba připsána na účet:

$order=array('amount'=>79,'currency'=>'CZK','variableSymbol'=>368228316);

if(in_array($order,$fioapi->getTransactionsSimple())){
    echo('zaplaceno');
}

Výchozí nastavení je, že jsou v tomto zjednodušeném výpisu částka, měna a variabilní symbol. Toto můžete změnit metodou, kterou volejte ideálně před stažením dat:

$fioapi->setArraySimple(array('amount','date'));

6 Výjimky

Výjimky odchytávejte přes FioApiException. Častou výjimkou je „No server response“. Možné důvody pro tuto výjimku jsou
FIO banka umožňuje přístup do API s jedním tokenem pouze každých 30 sekund. V reálu je to o něco kratší.
Máte neplatný token.
Máte neplatný certifikát (pokud jej využíváte).
Je problém s připojením do FIO banky nebo FIO banka má problém se svým API.

7 Řetězení metod

Metody můžete řetězit. Např.

$fioapi = new FioApi('TOKEN');
print_r($fioapi->setLastId(3537322837)->downloadLast()->getTransactionsSimple());

8 Vysvětlení proměnných z výpisu

8.1 Hlavička

proměnná popis příklad
accountId číslo účtu 1234562
bankId číslo banky 2010
currency měna účtu dle standardu ISO 4217 CZK
iban mezinárodní číslo bankovního účtu dle standardu ISO 13616 CZ78201000000­00001234562
bic bankovní identifikační kód dle standardu ISO 9362 FIOBCZPPXXX
openingBalance počáteční zůstatek na účtu na počátku zvoleného období 123.20
closingBalance konečný zůstatek na účtu na konci zvoleného období 123.22
dateStart počátek zvoleného období objekt Datetime()
dateEnd konec zvoleného období objekt Datetime()
yearList rok zvoleného výpisu 2012
idList číslo zvoleného výpisu 1
idFrom číslo prvního pohybu v daném výběru 1158152824
idTo číslo posledního pohybu v daném výběru 1158152824
idLastDownload číslo posledního úspěšně staženého pohybu 1158152824

8.2 Transakce

proměnná popis příklad
transactionId jedinečné číslo ID pohybu 1158152824
instructionId číslo příkazu 2102382863
date datum pohybu objekt Datetime
amount velikost přijaté/odeslané částky 12225.25
currency měna přijaté /odeslané částky dle standardu ISO 4217 EUR
account číslo protiúčtu 2212–2000000699
accountName název protiúčtu Béďa Trávníček
bankCode číslo banky protiúčtu 2010
bankName název banky protiúčtu Fio banka, a.s.
constantSymbol konstantní symbol 0558
variableSymbol variabilní symbol 1234567890
specificSymbol specifický symbol 1234567890
user_note uživatelská identifikace Nákup: PENNY MARKET s.r.o., Jaromer, CZ
message zpráva pro příjemce Libovolný text, který se zobrazí příjemci platby
type typ operace Platba převodem uvnitř banky
performed oprávněná osoba, která zadala příkaz Béďa Trávníček
specification upřesňující informace k pohybu. Zpravidla to bývá kurz 15.90 EUR
comment upřesňující informace Hračky pro děti v PENNY MARKET
bic bankovní identifikační kód banky protiúčtu dle standardu ISO 9362 UNCRITMMXXX