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

Přejít na zadávání transakcí | Changelog | 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 → Správa účtu přes API → Nastavení API).

Chraňte svůj soubor nebo uložená data s konfigurací k API proti jejich zneužití, zejména proti odcizení, okopírování apod. Zneužitím Vašich konfiguračních údajů (zejména tokenu) může jiná osoba předstírat Vaši identitu a zadávat pokyny Vaším jménem či získávat informace o pohybech. Zneužití souboru s konfigurací nebo dat Vám může způsobit škodu.

PHP třída využívá knihovny CURL, SSL a SimpleXML. Bez toho ji na svém serveru nerozjedete (SimpleXML se používá jen pro karetní transakce). Samozřejmostí jsou komentáře jednotlivých metod PHPDoc, díky kterým je použití třídy ještě snazší.

1 Quick start

Stažení transakcí za poslední měsíc.

require_once 'fioapi.class.php';
require_once 'fioapidownload.class.php';

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

    print_r($fioapi->getTransactions());

} catch (FioApi\FioApiException $e) {
    echo 'Exception '.$e->getCode().': '.$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']."");
}

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

$fioapi = new FioApi\FioApiDownload('TOKEN');

Úprava ve verzi 2.2 – certifikát nemá opodstatnění při stahování transakcí

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);

3.4 Karetní transakce

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

Pozn.: Není možné zadávat konkrétní čas, bere se v úvahu pouze datum. Získaná data v hlavičce i v getTransactions mají trochu jinou strukuru, než pohyby na účtu – vysvětleno dále

3.5 Číslo posledního vytvořeného oficiálního výpisu

$fioapi->downloadLastStatement();

Pozn.: Data získáte v hlavičce (dále), po této metodě již nevoláte getTransactions()

4 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()).

4.1 Výpis hlavičky

$header=$fioapi->getHeader();

Výsledkem je pole v následující struktuře. Podrobné vysvětlivky jsou na konci této stránky.

4.1.1 Hlavička pro pohyby na účtu

Týká se metod downloadByPeriod, downloadLast, downloadStatement

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] =>
)

4.1.2 Hlavička pro karetní transakce

Týká se metody downloadMerchant

Array
(
    [accountId] => 1234567890
    [bankId] => 2010
    [currency] => CZK
    [iban] => CZ5020100000002900072500
    [bic] => FIOBCZPPXXX
    [dateStart] => DateTime Object
        (
            [date] => 2019-07-13 00:00:00.000000
            [timezone_type] => 3
            [timezone] => Europe/Prague
        )

    [dateEnd] => DateTime Object
        (
            [date] => 2020-07-13 00:00:00.000000
            [timezone_type] => 3
            [timezone] => Europe/Prague
        )

)

4.1.3 Hlavička pro číslo posledního vytvořeného oficiálního výpisu

Týká se metody downloadLastSta­tement

Array
(
    [yearList] => 2020
    [idList] => 1
)

4.2 Výpis pohybů na účtu a karetních transakcí

$header=$fioapi->getTransactions();

4.2.1 Výpis pohybů na účtu

Týká se metod downloadByPeriod, downloadLast, downloadStatement
Podrobné vysvětlivky jsou na konci této stránky.

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
        (
            ...
        )
)

4.2.2 Zjednodušený výpis pohybů na účtu

Týká se metod downloadByPeriod, downloadLast, downloadStatement

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'));

4.2.3 Výpis karetních transakcí

Podrobné vysvětlivky jsou na konci této stránky.

Array
(
    [0] => Array
        (
            [operationId] => 8216165940
            [orderId] => 9277937165
            [date] => DateTime Object
                (
                    [date] => 2020-10-05 00:00:00
                    [timezone_type] => 3
                    [timezone] => Europe/Prague
                )
            [amount] => 4700
            [note] =>
            [branchName] => Provozovna Ječná
            [transactionId] => 28
            [deviceId] => 00203O999999 1
            [transactionDateTime] => DateTime Object
                (
                    [date] => 2020-10-05 15:01:00
                    [timezone_type] => 3
                    [timezone] => Europe/Prague
                )
            [autorizationNumber] => 997476
            [cardNumber] => 553553******5553
            [transactionAmount] => 200
            [transactionCurrency] => CZK
            [type] => ON_US
            [cardIssuer] => MASTERCARD
            [totalFees] => 20
            [fioFee] => 5
            [interchangeFee] => 5
            [cardAsosiationFee] => 10
            [settlement] => true
            [settlementDate] => DateTime Object
                (
                    [date] => 2020-10-05 00:00:00
                    [timezone_type] => 3
                    [timezone] => Europe/Prague
                )
        )
    [1] => Array
        (
            ...
        )
)

5 Nastavení zarážky

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

5.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);

5.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'));

6 Výjimky

Výjimky odchytávejte přes FioApi\FioApi­Exception. Častou výjimkou je časté stahování/zadávání transakcí. FIO banka umožňuje přístup do API s jedním tokenem pouze každých 30 sekund.

Seznam možný výjimek (ve formátu „kód: zpráva“)

2: No server response.

5: setArraySimple(): Param is not array.

6: setArraySimple(): You can use only values, which are predefined (see documentation or top of FioApiDownload class).

409: You can download or upload transactions with same token only every 30 seconds.

404: The requested resource is not available. Maybe some problem with Internet banking.

500: Internal Error. There is probably a wrong token.

7 Řetězení metod

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

print_r($fioapi->setLastId(3537322837)->downloadLast()->getTransactionsSimple());

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

8.1 Hlavička

Podrobnější informace o formátu najdete na https://www.fio.cz/…ovnictvi.pdf

8.2 Pohyby na účtu

Podrobnější informace o formátu najdete na https://www.fio.cz/…ovnictvi.pdf

8.3 Karetní transakce

Podrobnější informace o formátu najdete na https://www.fio.cz/…ovnictvi.pdf