GPC export z Fio banky

Úvod

Existuje mnoho druhů formátů umožňujících export dat z internetového bankovnictví. Ne každý formát má natolik pevnou strukturu, aby jej bylo možné snadno a spolehlivě zpracovávat pomocí programových prostředků. Česká banka Fio nabízí jako jednu z možností exportu formát GPC. Pokud potřebujete provádět automatické stahování dat v tomto formátu z internetového bankovnictví u zmíněné banky, tak můžete použít zde prezentované již hotové třídy. Pomocí nich lze snadno vyčítat periodicky informace o nových pohybech na účtu.

Třída GPC v gpc.php

Tato třída slouží pro dekódování GPC formátu na asociativní pole, s kterým se pak už snadno pracuje v PHP.

<?php

define('GPC_TYPE_REPORT', '074');
define('GPC_TYPE_ITEM', '075');

class GPC
{
  function ParseLine(string $Line): array
  {  
    $Line = ' '.$Line;
    $Type = substr($Line, 1, 3);                                                    
       
    if ($Type == GPC_TYPE_REPORT)
    {
      $GPCLine = array
      (
        'Type' => GPC_TYPE_REPORT,
        'AccountNumber' => substr($Line, 4, 16),
        'AccountName' => trim(substr($Line, 20, 20)),
        'OldBalanceDate' => mktime(0, 0, 0, substr($Line, 42, 2), substr($Line, 40, 2), '20'.substr($Line, 44, 2)),
        'OldBalanceValue' => (substr($Line, 60, 1).substr($Line, 46, 14)) / 100, 
        'NewBalanceValue' => (substr($Line, 75, 1).substr($Line, 61, 14)) / 100,
        'DebitValue' => (substr($Line, 90, 1).substr($Line, 76, 14)) / 100,    
        'CreditValue' => (substr($Line, 105, 1).substr($Line, 91, 14)) / 100,    
        'SequenceNumber' => intval(substr($Line, 106, 3)),
        'Date' => mktime(0, 0, 0, substr($Line, 111, 2), substr($Line, 109, 2), '20'.substr($Line, 113, 2)),
        //'DataAlignment' => substr($Line, 115, 14),
        'CheckSum' => sha1(md5($Line).$Line),
      );
    } else    
    if ($Type == GPC_TYPE_ITEM)
    {    
      $GPCLine = array
      (
        'Type' => GPC_TYPE_ITEM,
        'AccountNumber' => substr($Line, 4, 16),
        'OffsetAccount' => substr($Line, 20, 16), 
        'RecordNumber' => substr($Line, 36, 13), 
        'Value' => substr($Line, 49, 12) / 100,
        'Code' => substr($Line, 61, 1),    
        'VariableSymbol' => intval(substr($Line, 62, 10)),
        'BankCode' => substr($Line, 74, 4),
        'ConstantSymbol' => intval(substr($Line, 78, 4)),
        'SpecificSymbol' => intval(substr($Line, 82, 10)), 
        'Valut' => substr($Line, 92, 6),
        'ClientName' => substr($Line, 98, 20), 
        //'Zero' => substr($Line, 118, 1),
        'CurrencyCode' => substr($Line, 119, 4),
        'DueDate' => mktime(0, 0, 0, substr($Line, 125, 2), substr($Line, 123, 2), substr($Line, 127, 2)),
        'CheckSum' => sha1(md5($Line).$Line),
      );
    } else $GPCLine = NULL;
    
    return $GPCLine;
  }
}

Přístup přes bankovní API

Fio banka od 6.11.2012 zprovoznila své bankovní API, díky kterému je možné standardizovanou formou vyčítat informace o pohybech na účtech. Export lze provést do formátů XML, OFX, GPC, CSV, HTML, JSON a MT940. Zde je použit formát GPC. Detailní popis API najdete v API_Bankovnictvi.pdf.

• Pro přístup přes API je nutno si vygenerovat v internetovém bankovnictví pro každý účet unikátní token.
• Kódování GPC exportu je Windows-1250, takže se provádí konverze kódování na UTF-8

Třída Fio v fio_api.php

<?php
 
include('gpc.php');
 
class FioAPI
{
  public string $Token;
  public string $Encoding;
  
  function __construct()
  {
    $this->Encoding = 'utf-8';
  }
 
  function Import($TimeFrom, $TimeTo)
  {
    if ($this->Token == '') throw new Exception('Missing value for Token property.');
 
    $fp = fsockopen('ssl://www.fio.cz', 443, $errno, $errstr, 30);
    if (!$fp) 
    {
      throw new Exception('Connection error: '.$errstr);
    } else 
    {
      // Send request
      $RequestURL = '/ib_api/rest/periods/'.$this->Token.'/'.
        date('Y-m-d', $TimeFrom).'/'.date('Y-m-d', $TimeTo).'/transactions.gpc';
      $Request = "GET ".$RequestURL." HTTP/1.1\r\n";
      $Request .= "Host: www.fio.cz\r\n";
      $Request .= "User-Agent: PHP Script\r\n";
      $Request .= "Content-Type: text/html\r\n";
      $Request .= "Connection: Close\r\n\r\n";
      fwrite($fp, $Request);
 
      // Read response
      $Response = array();
      while (!feof($fp)) 
      {
        $Response .= trim(fgets($fp, 1024))."\n";
      }
      fclose($fp);      
      $Response = iconv('windows-1250', $this->Encoding, $Response);
      $Response = explode("\n", $Response);
 
      // Strip HTTP header
      while ($Response[0] != '') array_shift($Response);
      array_shift($Response); // Remove empty line
 
      // Parse all GPC lines
      $GPC = new GPC();
      $Result = array();
      foreach ($Response as $Index => $Line)
      {
	    if (($Index == 0) and (substr($Line, 0, strlen(GPC_TYPE_REPORT)) != GPC_TYPE_REPORT)) $this->NoValidDataError($Response);
        $GPCLine = $GPC->ParseLine($Line);
        if ($GPCLine != NULL) $Result[] = $GPCLine;
      }
      return $Result;
    }
  }
 
  function NoValidDataError(array $Response)
  {
    // Try to get error message
    // If something go wrong fio show HTML login page and display error message
	$Response = implode('', $Response);
    $ErrorMessageStart = '<div id="oldform_warning">';
    if (strpos($Response, $ErrorMessageStart) !== false) 
	{
	  $Response = substr($Response, strpos($Response, $ErrorMessageStart) + strlen($ErrorMessageStart));
	  $ErrorMessage = trim(substr($Response, 0, strpos($Response, '</div>')));
	} else $ErrorMessage = '';
	throw new Exception('No valid GPC data: '.$ErrorMessage);
  }
}

Ukázka použití v demo_fio_api.php

<?php

include('fio_api.php');

$Fio = new FioAPI();
$Fio->Token = 'unikátní vygenerovaný token';
$Records = $Fio->Import(time() - 3600 * 24 * 31 * 2, time());

echo('<!DOCTYPE html>');
echo('<html><head><meta charset="utf-8"></head><body>');
echo('<table border="1">');
foreach ($Records as $Record)
{
  echo('<tr>');
  if ($Record['Type'] == GPC_TYPE_REPORT) 
  {
    echo('<td>Jméno účtu: '.$Record['AccountName'].'</td>');
    echo('<td>Číslo účtu: '.$Record['AccountNumber'].'</td>');
    echo('<td>Ke dni '.date('j.n.Y', $Record['OldBalanceDate']).' je stav účtu '.$Record['OldBalanceValue'].' Kč</td>');
    echo('<td>Ke dni '.date('j.n.Y', $Record['Date']).' je stav účtu '.$Record['NewBalanceValue'].' Kč</td>');
    echo('<td>Suma příjmů: '.$Record['CreditValue'].' Kč</td>');
    echo('<td>Suma výdajů: '.$Record['DebitValue'].' Kč</td>');

    echo('</tr></table><br><br>');
    echo('<table border="1"><tr>');

    echo('<th>Datum</th>');
    echo('<th>Částka</th>');
    echo('<th>Účet protistrany</th>');
    echo('<th>Kód banky</th>');
    echo('<th>KS</th>');
    echo('<th>VS</th>');
    echo('<th>SS</th>');
    echo('<th>Uživatelská identifikace</th>');
  } else
  if ($Record['Type'] == GPC_TYPE_ITEM) 
  {
    echo('<td>'.date('j.n.Y', $Record['DueDate']).'</td>');
    echo('<td>'.$Record['Value'].'</td>');
    echo('<td>'.$Record['OffsetAccount'].'</td>');
    echo('<td>'.$Record['BankCode'].'</td>');
    echo('<td>'.$Record['ConstantSymbol'].'</td>');
    echo('<td>'.$Record['VariableSymbol'].'</td>');
    echo('<td>'.$Record['SpecificSymbol'].'</td>');
    echo('<td>'.$Record['ClientName'].'</td>');
  }          
  echo('</tr>');
}
echo('</table>');
echo('</body></html>');

Přístup přes přímé webové rozhraní

Přímý přístup byla jediná použitelná metoda v době, kdy neexistovalo samostatné bankovní API rozhraní. Data bylo možné získat ve formátu GPC, CSV nebo přímým rozkládáním HTML. Zde je použit export do formátu GPC.

• Kódování webu Fio je Windows-1250, takže se provádí konverze kódování na UTF-8
• Při zasílání formuláře se generuje aktuální čas pomocí funkce time() v parametru LOGIN_TIME podle času počítače, na kterém běží skript. Čas na vašem počítači musí být blízký času na Fio serveru. Tedy synchronizovaný přes NTP z internetu. Pokud je čas zpožděn o více než asi 3-5 minut, dojde ke zobrazení hlášení "Přihlašovací formulář byl již neplatný. Zkuste se přihlásit znovu".

Třída Fio v fio.php

<?php
 
include('gpc.php');
 
class Fio 
{
  public string $UserName;
  public string $Password;
  public string $Account;  
  public string $Encoding;
 
  function __construct()
  {
    $this->Encoding = 'utf-8';
  }

  function Import($TimeFrom, $TimeTo)
  {
    if ($this->UserName == '') throw new Exception('Missing value for UserName property.');
    if ($this->Password == '') throw new Exception('Missing value for Password property.');
    if (!is_numeric($this->Account)) throw new Exception('Missing or not numeric value for Account property.');
	
    $fp = fsockopen('ssl://www.fio.cz', 443, $errno, $errstr, 30);
    if (!$fp) 
    {
      throw new Exception('Connection error: '.$errstr);
    } else 
    {
      // Send request
      $RequestURL = "/scgi-bin/hermes/dz-pohyby.cgi?ID_ucet=".$this->Account.
        "&LOGIN_USERNAME=".$this->UserName."&SUBMIT=Odeslat&LOGIN_TIME=".time().
        "&LOGIN_PASSWORD=".$this->Password."&pohyby_DAT_od=".date('d.m.Y', $TimeFrom).
        "&pohyby_DAT_do=".date('d.m.Y', $TimeTo)."&export_gpc=1";
      $Request = "GET ".$RequestURL." HTTP/1.1\r\n";
      $Request .= "Host: www.fio.cz\r\n";
      $Request .= "User-Agent: PHP Script\r\n";
      $Request .= "Content-Type: text/html\r\n";
      $Request .= "Connection: Close\r\n\r\n";
      fwrite($fp, $Request);
 
      // Read response
      $Response = array();
      while (!feof($fp))
      {
        $Response .= trim(fgets($fp, 1024))."\n";
      }
      fclose($fp);      
      $Response = iconv('windows-1250', $this->Encoding, $Response);
      $Response = explode("\n", $Response);
 
      // Strip HTTP header
      while ($Response[0] != '') array_shift($Response);
      array_shift($Response); // Remove empty line
      
      // Parse all GPC lines
      $GPC = new GPC();
      $Result = array();
      foreach ($Response as $Index => $Line)
      {
	    if (($Index == 0) and (substr($Line, 0, strlen(GPC_TYPE_REPORT)) != GPC_TYPE_REPORT)) $this->NoValidDataError($Response);
        $GPCLine = $GPC->ParseLine($Line);
        if ($GPCLine != NULL) $Result[] = $GPCLine;
      }
      return $Result;
    }
  }
  
  function NoValidDataError(array $Response)
  {
    // Try to get error message
    // If something go wrong Fio show HTML login page and display error message
	$Response = implode('', $Response);
    $ErrorMessageStart = '<div id="oldform_warning">';
    if (strpos($Response, $ErrorMessageStart) !== false) 
	{
	  $Response = substr($Response, strpos($Response, $ErrorMessageStart) + strlen($ErrorMessageStart));
	  $ErrorMessage = trim(substr($Response, 0, strpos($Response, '</div>')));
	} else $ErrorMessage = '';
	throw new Exception('No valid GPC data: '.$ErrorMessage);
  }
}

Ukázka použití v demo_fio.php

<?php

include('fio.php');

$Fio = new Fio();
$Fio->Account = '123456789';
$Fio->UserName = 'user';
$Fio->Password = 'pass';
$Records = $Fio->Import(time() - 3600 * 24 * 31 * 2, time());

echo('<!DOCTYPE html>');
echo('<html><head><meta charset="utf-8"></head><body>');
echo('<table border="1">');
foreach ($Records as $Record)
{
  echo('<tr>');
  if ($Record['Type'] == GPC_TYPE_REPORT) 
  {
    echo('<td>Jméno účtu: '.$Record['AccountName'].'</td>');
    echo('<td>Číslo účtu: '.$Record['AccountNumber'].'</td>');
    echo('<td>Ke dni '.date('j.n.Y', $Record['OldBalanceDate']).' je stav účtu '.$Record['OldBalanceValue'].' Kč</td>');
    echo('<td>Ke dni '.date('j.n.Y', $Record['Date']).' je stav účtu '.$Record['NewBalanceValue'].' Kč</td>');
    echo('<td>Suma příjmů: '.$Record['CreditValue'].' Kč</td>');
    echo('<td>Suma výdajů: '.$Record['DebitValue'].' Kč</td>');

    echo('</tr></table><br><br>');
    echo('<table border="1"><tr>');

    echo('<th>Datum</th>');
    echo('<th>Částka</th>');
    echo('<th>Účet protistrany</th>');
    echo('<th>Kód banky</th>');
    echo('<th>KS</th>');
    echo('<th>VS</th>');
    echo('<th>SS</th>');
    echo('<th>Uživatelská identifikace</th>');
  } else
  if ($Record['Type'] == GPC_TYPE_ITEM) 
  {
    echo('<td>'.date('j.n.Y', $Record['DueDate']).'</td>');
    echo('<td>'.$Record['Value'].'</td>');
    echo('<td>'.$Record['OffsetAccount'].'</td>');
    echo('<td>'.$Record['BankCode'].'</td>');
    echo('<td>'.$Record['ConstantSymbol'].'</td>');
    echo('<td>'.$Record['VariableSymbol'].'</td>');
    echo('<td>'.$Record['SpecificSymbol'].'</td>');
    echo('<td>'.$Record['ClientName'].'</td>');
  }          
  echo('</tr>');
}
echo('</table>');
echo('</body></html>');

Pokud něco nefunguje jak má

• Třídy jsou navrženy tak, aby při výskytu chyby vyvolaly výjimku. Pokud z popisu chyby není zřejmá příčina, je potřeba chybu ladit a do kódu přidávat dočasně ladící výpisy. Především ze zobrazení obsahu načítané stránky z webu Fio by mělo vyplynout odkud vítr vane.

Vnější odkazy

• Struktura GPC formátu
• Specifikace Fio API
• Parsování GPC souborů v PHP
• Fio banka