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

Přejít na 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 → Správa účtu přes API → Nastavení API). Pro zadávání transakcí potřebujete token s nastavením „Sledovat účet a zadávat platební příkazy a inkasa“.

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.

Zadané transakce je nutné potvrdit (podepsat) přes SMS v internetovém bankovnictví (Přehledy – K podpisu).

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

1 Quick start

Zadání standardní domácí transakce.

require_once 'fioapi.class.php';
require_once 'fioapiupload.class.php';

try {
    $fioapi = new FioApi\FioApiUpload('TOKEN');

    $transaction=new FioApi\DomesticTransaction();
    $transaction->setAccountFrom(2900072500)
                ->setAccountTo(2900072746)
                ->setBankCode(2010)
                ->setAmount(200)
                ->setCurrency('CZK')
                ->setDate(new Datetime());

    $result=$fioapi->addTransaction($transaction)
                   ->upload();

    print_r($result);


} catch (FioApi\FioApiException $e) {
    echo 'Exception '.$e->getCode().': '.$e->getMessage();
}

Výsledkem je následující pole:

Array
(
    [status] => ok
    [transactions] => Array
        (
            [0] => Array
                (
                    [status] => ok
                    [message] => OK
                )

        )

)

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

Spuštění je podobné jako u stahování transakcí.

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

Jestliže server nezná certifikační autoritu, tak je nutné stáhnout certifikát ze stránky http://www.geotrust.com/…ertificates/ (Root 5 – GeoTrust Primary Certification Authority – G3). Certifikát si uložte např. do stejného adresáře, jako skript. Odkazujete pak na jeho plnou cestu. Na localhostu doporučuji certifikát nevyužívat.

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

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

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

Při posílání plateb se využívají dočasné soubory, můžete proto nastavit TEMP adresář. Defaultně je nastaven TEMP adresář z PHP (není tedy nutné jej nastavovat).

$fioapi->setTempDir(__DIR__.'/temp');

Do TEMP adresáře musí mít skript zapisovací právo – jinak systém vyhodí výjimku č. 7: „Temp directory is not writeable“. Tato situace nastává, pokud necháte výchozí TEMP adresář, ale defaultně je zároveň nastaveno omezení open_basedir.

3 Vytvoření transakcí

Transakce se vytvářejí jako samostatné objekty:
FioApi\Domestic­Transaction, FioApi\Target2Tran­saction a FioApi\Foreig­nTransaction.
Tedy domácí transakce, Europlatba (Target2Transac­tion) a zahraniční transakce.

3.1 Domácí transakce

$transaction=new FioApi\DomesticTransaction();
$transaction->setAccountFrom(2900072500)
            ->setAccountTo(2900072746)
            ->setBankCode(2010)
            ->setAmount(202)
            ->setCurrency('CZK')
            ->setDate(new Datetime());

Všechny metody pro nastavení domácí transakce jsou:

//POVINNÉ: číslo účtu, ze kterého chcete poslat peníze
$transaction->setAccountFrom($value);

//POVINNÉ: kód měny, např. CZK
$transaction->setCurrency($value);

//POVINNÉ: částka
$transaction->setAmount($value);

//POVINNÉ: číslo účtu příjemce
$transaction->setAccountTo($value);

//POVINNÉ: kód banky příjemce
$transaction->setBankCode($value);

//POVINNÉ: datum, kdy bude provedená transakce (dnes nebo v budoucnosti)
$transaction->setDate(new Datetime());

//komentář transakce
$transaction->setComment($value);

//variabilní symbol
$transaction->setVariableSymbol($value);

//konstantní symbol
$transaction->setConstantSymbol($value);

//specifický symbol
$transaction->setSpecificSymbol($value);

//zpráva pro příjemce
$transaction->setMessage($value);

//typ platby: 431001 standardní; 431005 prioritní; 431022 příkaz k inkasu
$transaction->setPaymentType($value);

3.2 Europlatba (Target2)

$transaction=new FioApi\Target2Transaction();
$transaction->setAccountFrom(2900072500)
            ->setAccountTo('AT611904300234573201')
            ->setAmount(100)
            ->setCurrency('EUR')
            ->setBic('ABAGATWWXXX')
            ->setBenefName('Hans Gruber')
            ->setBenefStreet('Gugitzgasse 2')
            ->setBenefCity('Wien')
            ->setBenefCountry('AT')
            ->setDate(new Datetime());

Všechny metody pro nastavení Target2 transakce jsou:

//POVINNÉ: číslo účtu, ze kterého chcete poslat peníze
$transaction->setAccountFrom($value);

//POVINNÉ: kód měny, např. EUR
$transaction->setCurrency($value);

//POVINNÉ: částka
$transaction->setAmount($value);

//POVINNÉ: číslo účtu příjemce
$transaction->setAccountTo($value);

//POVINNÉ: datum, kdy bude provedená transakce (dnes nebo v budoucnosti)
$transaction->setDate(new Datetime());

//POVINNÉ: jméno příjemce
$transaction->setBenefName($value);

//komentář transakce
$transaction->setComment($value);

//platební titul – POVINNÝ jen u účtů vedených Fio bankou pobočce zahraniční banky v SR pouze při platbě nad 50 000 EUR
$transaction->setPaymentReason($value);

//variabilní symbol
$transaction->setVariableSymbol($value);

//konstantní symbol
$transaction->setConstantSymbol($value);

//specifický symbol
$transaction->setSpecificSymbol($value);

//BIC (Bank Identifier Code)
$transaction->setBic($value);

//ulice příjemce
$transaction->setBenefStreet($value);

//město příjemce
$transaction->setBenefCity($value);

//stát příjemce (dvoupísmenný kód - viz tabulka na http://www.fio.cz/docs/cz/API_Bankovnictvi.pdf str. 37)
$transaction->setBenefCountry($value);

//informace pro příjemce
$transaction->setRemittanceInfo1($value);
$transaction->setRemittanceInfo2($value);
$transaction->setRemittanceInfo3($value);

//typ platby: 431008 standardní; 431009 prioritní
$transaction->setPaymentType($value);

3.3 Zahraniční transakce

$transaction=new FioApi\ForeignTransaction();
$transaction->setAccountFrom(2900072500)
            ->setAccountTo('PK36SCBL0000001123456702')
            ->setAmount(100)
            ->setCurrency('USD')
            ->setBic('ALFHPKKAXXX')
            ->setBenefName('Amir Khan')
            ->setBenefStreet('Nishtar Rd 13')
            ->setBenefCity('Karachi')
            ->setBenefCountry('PK')
            ->setDetailsOfCharges(470502)
            ->setPaymentReason(348)
            ->setRemittanceInfo1('Payment for hotel')
            ->setDate(new Datetime('+1 day'));

Všechny metody pro nastavení zahraniční transakce jsou:

//POVINNÉ: číslo účtu, ze kterého chcete poslat peníze
$transaction->setAccountFrom($value);

//POVINNÉ: kód měny, např. EUR
$transaction->setCurrency($value);

//POVINNÉ: částka
$transaction->setAmount($value);

//POVINNÉ: číslo účtu příjemce
$transaction->setAccountTo($value);

//POVINNÉ: datum, kdy bude provedená transakce (dnes nebo v budoucnosti)
$transaction->setDate(new Datetime());

//POVINNÉ: důvod platby - kód z tabulky na http://www.fio.cz/docs/cz/API_Bankovnictvi.pdf str. 45
$transaction->setPaymentReason($value);

//POVINNÉ: BIC (Bank Identifier Code)
$transaction->setBic($value);

//komentář transakce
$transaction->setComment($value);

//POVINNÉ: jméno příjemce
$transaction->setBenefName($value);

//POVINNÉ: ulice příjemce
$transaction->setBenefStreet($value);

//POVINNÉ: město příjemce
$transaction->setBenefCity($value);

//POVINNÉ: stát příjemce (dvoupísmenný kód - viz tabulka na http://www.fio.cz/docs/cz/API_Bankovnictvi.pdf str. 37)
$transaction->setBenefCountry($value);

//informace pro příjemce
$transaction->setRemittanceInfo1($value); //POVINNÉ
$transaction->setRemittanceInfo2($value);
$transaction->setRemittanceInfo3($value);
$transaction->setRemittanceInfo4($value);

//POVINNÉ: kdo bude platit poplatky: 470501 - vše plátce; 470502 - vše příjemce; 470503 - každý sám své
$transaction->setDetailsOfCharges($value);

4 Odeslání transakcí

Nejdříve přidáte vytvořenou transakci:

$fioapi->addTransaction($transaction);

Tímto způsobem můžete přidat více transakcí zaráz (klidně i rozdílných – jednu domácí, druhou zahraniční, …).
Následně transakce zadáte a výstup uložíte do proměnné, kterou poté můžete vypsat:

$result=$fioapi->upload();
print_r($result);

Pokud vše proběhne v pořádku, výstup bude následující (pro 2 transakce):

Array
(
    [status] => ok
    [transactions] => Array
        (
            [0] => Array
                (
                    [status] => ok
                    [message] => OK
                )

            [1] => Array
                (
                    [status] => ok
                    [message] => OK
                )

        )

)

5 Chyby, výjimky

Vě výpisu je důležité pole „status“. To může nabývat 3 hodnot

ok – příkaz přijat

error – hrubá chyba v příkazu, dávka se všemi příkazy nebude přijata

warning – varování, některý z údajů nesouhlasí (např. měna platby a měna účtu) nebo např. když zadáte identický pokyn, který byl zadán nedávno, příkazy s odpovědí warning byly přijaty bankou

fatal – chyba na straně bankovního systému banky, všechny pokyny se odmítly

Při statusu error bude vyvolána výjimka FioApi\FioApi­Exception. Pokud byste ji chtěli nevyvolávat, stačí před uploadem zadat:

$fioapi->setExceptionOnError(false);

Při statusu warning se výjimka nevyvolává (protože transakce se uloží). Pokud byste ji vyvolat chtěli, tak zadejte před uploadem:

$fioapi->setExceptionOnWarning(true);

5.1 Zachytávání výjimek

Pro zachytávání můžete používat následující kód:

try{
    //zadání transakcí
}
catch (FioApi\FioApiException $e) {
    echo 'Exception '.$e->getCode().': '.$e->getMessage();
}

Pokud nastane nějaká chyba v transakci, objeví se výjimka:

Exception 3: Error in transaction(s). See $e->getTransactions();

Abyste zjistili, kde se chyba nachází, je vhodné mít při zachytávání v „catch“ navíc řádek:

print_r($e->getTransactions());

Díky němu zjistíte, kde nastala chyba:

Array
(
    [status] => error
    [transactions] => Array
        (
            [0] => Array
                (
                    [status] => ok
                    [message] => OK
                )

            [1] => Array
                (
                    [status] => error
                    [message] => Payment date is in the past
                )

        )

)

Chybová zpráva se přebírá z odpovědi z Fio banky. Ta odpovědi předává vesměs v angličtině, ale i tak se občas může objevit čeština. Následující je chyba ve struktuře, konkrétně chybí v zahraniční transakci parametr paymentReason:

Array
(
    [status] => error
    [message] => Soubor má chyby ve struktuře: cvc-complex-type.2.4.b: The content of element 'ForeignTransaction' is not complete. One of '{paymentReason}' is expected. řádek: 2 pozice: 915.
)

Č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“)

1: Incorrect PATH to certificate.

2: No server response, CURL error. Konkrétní důvod bude přiložen, např. SSL certificate problem: unable to get local issuer certificate

3: Error in transaction(s). See $e->getTransactions();

4: Warning in transaction(s). See $e->getTransactions();

5: setArraySimple(): Param is not array.

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

7: Temp directory is not writeable.

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.

V případě problému s certifikátem zkuste následující postup doporučený FIO bankou:

Při importu příkazů do bankovního systému probíhá kontrola certifikátu certifikační autority. Tato kontrola selhala a je nutné získat nový používaný certifikát a to buď dle bodu 6.1., a nebo přímo ze stránek Fio banky

a. https://www.fio.cz/ib2/login

b. kliknout na zelený název Fio banka v URL prohlížeče

c. tlačítko více informací

d. záložka bezpečnost

e. tlačítko zobrazit certifikát

f. záložka detaily

g. klikne nejvýše položený řádek v tabulce Hierarchie certifikátu

h. tlačítko exportovat

i. uložit, použít

6 Řetězení metod

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

$result=$fioapi->addTransaction($transaction)->addTransaction($transaction2)->upload();