- Připojení k API
- Vytvoření klienta
- Vystavení faktury
- Vystavení objednávky (doporučený způsob)
- URL notifikace
- Logování chybových hlášení
Pro připojení k API můžete použít knihovnu FAPIClient pro PHP (stáhnout).
Soubor FAPIClient.php si zkopírujte do své webové aplikace. Pro přístup k API si vytvořte instanci objektu FAPIClient:
require_once __DIR__ . '/(relativní cesta k souboru FAPIClient.php z aktuálního adresáře)';
$fapi = new FAPIClient('uživatelské jméno', 'API klíč');API klíč lze vygenerovat na stránce https://web.fapi.cz/account-settings/api-tokens. Pro zpětnou kompatibilitu API podporuje i uživatelské jméno a heslo do FAPI, z důvodu bezpečnosti však doporučujeme použít API klíč.
Vytvoření klienta lze provést pomocí následujícího příkazu. Všechna pole s výjimkou e-mailové adresy jsou nepovinná.
$client = $fapi->client->create([
'first_name' => 'Josef',
'last_name' => 'Novák',
'email' => 'josef.novak@example.com',
'phone' => '+420 123 456 789',
'company' => 'Firma s.r.o.',
'ic' => '12345678',
'dic' => 'CZ12345678',
'address' => [
'street' => 'Ulice a č.p.',
'city' => 'Město',
'zip' => '123 45',
'country' => 'CZ', // kód státu dle normy ISO 3166-1
],
'shipping_address' => [
'name' => 'Karel',
'surname' => 'Novák',
'street' => 'Ulice a č.p.',
'city' => 'Město',
'zip' => '123 45',
'country' => 'CZ', // kód státu dle normy ISO 3166-1
],
]);Faktury lze vytvářet pomocí tohoto příkazu:
$invoice = $fapi->invoice->create([
'client' => $client['id'], // ID klienta
'form' => 123, // ID prodejního formuláře
'vat_date' => date('Y-m-d'), // datum uskutečnění zdanitelného plnění (pouze pro plátce DPH)
'proforma' => true, // jedná se o zálohovou fakturu?
'reverse_charge' => false, // jedná se o fakturu v režimu přenesené daňové povinnosti?
'notes' => 'Poznámka', // interní poznámka k faktuře (nepovinné pole)
'currency' => 'CZK', // kód měny dle normy ISO 4217
'items' => [
[
'name' => 'Položka', // název
'description' => 'Popis', // popis (nepovinné pole)
'price' => 123.45, // cena
'vat' => 21, // sazba DPH (pouze pro plátce DPH)
'count' => 1, // počet
'including_vat' => false, // je uvedená částka včetně DPH? (výchozí hodnota = false)
],
],
]);Parametr proforma určuje, zda se má vytvářet zálohová faktura nebo daňový doklad. Pokud není uvedený, použije se automaticky to nastavení, které je nastaveno v nastavení fakturace.
Parametr reverse_charge určuje, zda je faktura v režimu přenesené daňové povinnosti. V takovém případě se na faktuře v patičce zobrazí věta "Daň odvede zákazník." a odečte se DPH od všech položek. Pokud není tento parametr uvedený, použije se autodetekce (pokud je zákazník z jiného státu a má platné DIČ, přepne se faktura automaticky do režimu přenesené daňové povinnosti).
Parametr vat_date určuje datum uskutečnění zdanitelného plnění. Pokud není uveden, považuje se faktura za fakturu neplátce DPH.
Parametr form specifikuje ID prodejního formuláře ve FAPI, pod kterým se má faktura vystavit. Prodejní formulář ovlivňuje nastavení e-mailových šablon, číselných řad, upomínek a URL notifikací. Chcete-li tedy upravit tato nastavení (např. po zaplacení objednávky vykonat nějakou URL notifikaci), vytvořte si ve FAPI prodejní formulář a proveďte v něm příslušná nastavení. Z URL adresy stránky, na které se upravuje prodejní formulář, si pak zkopírujte ID prodejního formuláře (např. pokud je stránka pro úpravu prodejního formuláře https://web.fapi.cz/user-form/edit/123?projectId=456, pak je ID prodejního formuláře 123).
Výše uvedený způsob vytváření klientů a faktur má však několik úskalí:
-
Je třeba správně párovat klienty podle e-mailu a IČ, aby se nevytvářeli duplicitní klienti. Párování klientů musí zohledňovat i to, aby se klienti se stejným e-mailem a různým IČ považovali za různé klienty. Jinak by se faktury nepřiřazovaly ke klientům správně.
-
Je třeba přepočítávat ceny z CZK na EUR, pokud se jedná o zahraničního zákazníka.
-
Je třeba správně nastavit parametr reverse_charge, aby se zákazníkům z jiného členského státu EU, kteří jsou plátci DPH, poslala faktura v režimu přenesené daňové povinnosti.
-
Musí se ručně implementovat platební proces přes platební bránu GoPay.
Proto jsme do FAPI přidali ještě alternativní způsob vystavení objednávky, který všechny tyto problémy řeší:
$order = $fapi->order->create([
// ID prodejního formuláře
'form' => 123,
// Údaje zákazníka
'first_name' => 'Josef',
'last_name' => 'Novák',
'email' => 'josef.novak@example.com',
'phone' => '+420 123 456 789',
'company' => 'Firma s.r.o.',
'ic' => '12345678',
'dic' => 'CZ12345678',
'address' => [
'street' => 'Ulice a č.p.',
'city' => 'Město',
'zip' => '123 45',
'country' => 'CZ', // kód státu dle normy ISO 3166-1
],
'shipping_address' => [
'name' => 'Karel',
'surname' => 'Novák',
'street' => 'Ulice a č.p.',
'city' => 'Město',
'zip' => '123 45',
'country' => 'CZ', // kód státu dle normy ISO 3166-1
],
// Položky
'items' => [
[
'item_template' => 777, // ID šablony položky, ze které se mají údaje předvyplnit (nepovinné pole)
'name' => 'Položka', // název
'description' => 'Popis', // popis (nepovinné pole)
'code' => '777', // kód položky
'price_czk' => 2700.00, // cena v CZK
'price_eur' => 100.00, // cena v EUR
'vat' => 21, // sazba DPH (pouze pro plátce DPH)
'count' => 1, // počet kusů
'including_vat' => false, // je uvedená částka včetně DPH? (výchozí hodnota = false)
],
],
// Způsob platby
'payment_type' => 'wire', // cash | collect on delivery | credit card | wire | sms
'bank' => 'wire', // Pokud je payment_type = 'wire', pak je možné specifikovat banku:
// cz_fio | cz_kb | cz_mbank | cz_rb | sk_slsp | sk_unicredit |
// sk_tatrabanka | sk_sberbank | sk_pabanksk | sk_vub | wire
// Parametr bank = 'wire' znamená ruční platbu bankovním převodem. Ostatní
// možnosti přesměrují zákazníka na platební bránu GoPay. U nové platební
// brány GoPay je možné uvést parametr bank = null. Když je nastaven tento
// parametr, tak se zákazníkovi zobrazí nabídka dostupných bank v platební
// bráně GoPay.
]);
$nextUrl = $order['next_url'];Při vystavení objednávky tímto způsobem je klient automaticky spárován a ve vráceném poli najdete pod indexem next_url adresu, kam máte zákazníka přesměrovat. Jedná se buď o adresu GoPay platební brány, nebo děkovací stránku, pokud zákazník vybral třeba platbu na dobírku nebo bankovním převodem ručně.
Je tedy potřeba nastavit u daného prodejního formuláře údaje ke GoPay a adresu děkovací a chybové stránky.
Pokud mají být vystavovány zálohové faktury, je potřeba zaškrtnout v nastavení prodejního formuláře pole Vystavovat zálohové faktury.
Dále je potřeba nastavit správně pole DPH pro zahraniční klienty, které určuje, v jakých případech se má faktura vystavit v režimu přenesené daňové povinnosti.
Na adresu URL notifikace, kterou si nastavíte v prodejním formuláři, pošle FAPI v okamžiku, kdy bude doklad označen jako zaplacený, HTTP požadavek metodou POST. V POST parametru s názvem id najdete ID dokladu.
Stáhněte si tedy doklad s daným ID z FAPI a zkontrolujte si, zda je opravdu zaplacený (bez této kontroly by mohl útočník při zjištění vaší notifikační URL podvrhnout URL notifikaci z FAPI u nezaplacené faktury).
Při vykonávání URL notifikací si dejte pozor na to, že FAPI posílá notifikaci jak při zaplacení zálohové faktury, tak při zaplacení daňového dokladu. Pokud tedy máte zapnuté vystavování zálohových faktur a v notifikaci provádíte dodání produktu zákazníkovi, přidejte si do notifikace ještě dodatečnou podmínku, že se má notifikace provést jenom pro zálohovou fakturu a nikoliv pro daňový doklad.
$invoiceId = isset($_POST['id']) ? (int) $_POST['id'] : null;
$invoice = null;
if ($invoiceId) {
$invoice = $fapi->invoice->get($invoiceId);
}
if ($invoice && $invoice['paid']) { // pokud je notifikace v pořádku
if ($invoice['proforma']) { // pokud se jedná o zálohovou fakturu
$client = $fapi->client->get($invoice['client']);
// (dodání produktu zákazníkovi)
}
}V případě, že dojde při volání API k nějaké chybě, vyhazují všechny výše uvedené příkazy výjimku FAPIClient_Exception. Doporučujeme tyto výjimky logovat, například pomocí nástroje Tracy.
Stačí, když si stáhnete soubor tracy.phar (stáhnout) a vytvoříte si na svém webu složku log, do které má PHP skript právo zapisovat. Tato složka by neměla být veřejně přístupná z webového prohlížeče, aby návštěvníci vašeho webu nemohli přistupovat k vašim logům.
Tracy lze do vaší aplikace integrovat tímto způsobem:
use Tracy\Debugger;
require_once __DIR__ . '/(relativní cesta k souboru tracy.phar z aktuálního adresáře)';
Debugger::enable(Debugger::PRODUCTION, __DIR__ . '/(relativní cesta ke složce log z aktuálního adresáře)');
try {
// (volání FAPI API)
} catch (\FAPIClient_Exception $e) {
Debugger::log($e, Debugger::ERROR);
// (zobrazení chybové hlášky uživateli)
}Pokud při volání API nastane nějaká chyba, naleznete podrobný report o této chybě ve složce log.
V notifikačním skriptu si můžete také logovat, zda byla v pořádku provedena notifikace.
use Tracy\Debugger;
Debugger::log('URL notification has been received. POST: ' . http_build_query($_POST), Debugger::DEBUG);Tato hlášení se pak budou automaticky ukládat do souboru debug.log.