Faktúry online : Faktúry online API Manuál pre vývojárov

Faktúry online API - Manuál pre vývojárov

Faktúry online API manuál

Predtým ako začnete...

Je potrebné, aby ste poznali svoj API kľúč. API kľúč je 32 znakový reťazec nutný pre používanie API. Svoj API kľúč nikomu nedávajte. Unikátny API kľúč si nájdete vo Vašom profile hneď po prihlásení sa na uvítacej stránke.

Vytvorenie novej faktúry

Volanie API pre vytvorenie novej faktúry:

https://www.faktury-online.com/api/nf?data={JSON}

Nasledujúce tabuľky uvádzajú zoznam parametrov, pomocou ktorých môžete vytvoriť novú faktúru.

Základné parametre:

Parameter	Atribút	Popis
key	povinný parameter	API kľúč.
email	povinný parameter	Email (alebo používateľské meno), ktorým sa prihlasujete do Faktúr online.
apitest	nepovinný parameter	Parameter apitest určuje, či vytvorená faktúra/dokument slúži na testovacie účely. Tento parameter by mal slúžiť iba vývojárom, ktorý implementujú Faktúry online API. Systém bude brať vytvorenú faktúru ako testovaciu a v rozmedzí 5 – 10 minút ju odstráni. Odporúčame mať túto hodnotu zapnutú pri testovaní nasadzovania API. V produkčnej prevádzke túto hodnotu vypnite, inak sa faktúry odstránia automaticky. Možné hodnoty: 1 alebo 0 Predvolená hodnota: 0

Parametre dodávateľa:
Dodávateľa môžeme vybrať buď pomocou parametra d_id, ktorého máme uloženého v zozname Moje spoločnosti (možnosť 1) alebo všetky potrebné údaje vyplníme v parametroch (možnosť 2).

Parameter	Atribút	Popis
d_id	možnosť 1 / povinný paramater	ID dodávateľa (ID nájdete v zozname Moje spoločnosti).
d_name	možnosť 2 / povinný paramater	Obchodný názov dodávateľa.
d_street	možnosť 2 / nepovinný paramater	Ulica dodávateľa.
d_city	možnosť 2 / nepovinný paramater	Mesto dodávateľa.
d_state	možnosť 2 / nepovinný paramater	Štát dodávateľa.
d_zip	možnosť 2 / nepovinný paramater	PSČ dodávateľa.
d_ico	možnosť 2 / nepovinný paramater	IČO dodávateľa.
d_dic	možnosť 2 / nepovinný paramater	DIČ dodávateľa.
d_icdph	možnosť 2 / nepovinný paramater	IČDPH dodávateľa.
d_vatpayer	možnosť 2 / nepovinný paramater	Platca DPH. Možné hodnoty: Platca DPH: 1 Neplatca DPH: 0 Predvolená hodnota: 0
d_viewpayer	možnosť 2 / nepovinný paramater	Zobraziť na faktúre informáciu, či je dodávateľ platcom DPH. Možné hodnoty: Áno: 1 Nie: 0 Predvolená hodnota: 1
d_info	možnosť 2 / nepovinný paramater	Info o dodávateľovi.
d_bankaccount	možnosť 2 / nepovinný paramater	Číslo účtu dodávateľa.
d_bank	možnosť 2 / nepovinný paramater	Názov banky dodávateľa.
d_iban	možnosť 2 / nepovinný paramater	IBAN dodávateľa.
d_swift	možnosť 2 / nepovinný paramater	SWIFT dodávateľa.
d_email	možnosť 2 / nepovinný paramater	Email dodávateľa.
d_web	možnosť 2 / nepovinný paramater	Web dodávateľa.
d_phone	možnosť 2 / nepovinný paramater	Telefón dodávateľa.

Parametre odberateľa:

Parameter	Atribút	Popis
o_name	povinný paramater	Obchodný názov odberateľa.
o_street	nepovinný paramater	Ulica odberateľa.
o_city	nepovinný paramater	Mesto odberateľa.
o_state	nepovinný paramater	Štát odberateľa.
o_zip	nepovinný paramater	PSČ odberateľa.
o_ico	nepovinný paramater	IČO odberateľa.
o_dic	nepovinný paramater	DIČ odberateľa.
o_icdph	nepovinný paramater	IČDPH odberateľa.
o_email	nepovinný paramater	Email odberateľa.
o_name_d	nepovinný paramater	Adresa dodania - Obchodný názov.
o_street_d	nepovinný paramater	Adresa dodania - Ulica.
o_city_d	nepovinný paramater	Adresa dodania - Mesto.
o_state_d	nepovinný paramater	Adresa dodania - Štát.
o_zip_d	nepovinný paramater	Adresa dodania - PSČ.

Parametre faktúry:

Parameter	Atribút	Popis
f_number	nepovinný paramater	Číslo faktúry. Ak nie je vyplnené, číslo sa automaticky zvýši o 1 z posledne vytvorenej faktúry (rozhodujúci je dátum vystavenia, číslo faktúry musí mať numerický formát).
f_vs	nepovinný paramater	Variabilný symbol.
f_ks	nepovinný paramater	Konštantný symbol.
f_date_issue	nepovinný paramater	Dátum vystavenia. Vo formáte RRRR-MM-DD. Predvolená hodnota: Aktuálny dátum
f_date_delivery	nepovinný paramater	Dátum dodania. Vo formáte RRRR-MM-DD. Predvolená hodnota: Aktuálny dátum
f_date_due	nepovinný paramater	Dátum splatnosti. Vo formáte RRRR-MM-DD. Predvolená hodnota: 14 dní od aktuálneho dátumu
f_issued_by	nepovinný paramater	Faktúru vystavil.
f_payment	nepovinný paramater	Typ úhrady. Možné hodnoty: Peňažný prevod: prevod Poštová poukážka: poukazka Hotovosť: hotovost Dobierka: dobierka Registračná pokladňa: pokladna Internetový platobný poskytovateľ: eprovider Iná: ina Predvolená hodnota: prevod
f_note	nepovinný paramater	Poznámka vo faktúre. Zobrazenie poznámky pod fakturačnými položkami. V prípade, že je dodávateľ vybraný pomocou parametra d_id a f_note je prázdne, zobrazí sa príslušná uložená poznámka k tomuto dodávateľovi.
f_logo	nepovinný paramater	Zobrazenie loga. Možné hodnoty: Nezobrazí sa: 0 Zobrazí sa: 1 (iba v prípade, že dodávateľ bol načítaný pomocou d_id a logo má uložené)
f_stamp	nepovinný paramater	Zobrazenie pečiatky. Možné hodnoty: Nezobrazí sa: 0 Zobrazí sa: 1 (iba v prípade, že dodávateľ bol načítaný pomocou d_id a pečiatku má uloženú)
f_currency	nepovinný paramater	Mena na faktúre. Označenie meny. Predvolená hodnota je EUR. Predvolená hodnota: EUR
f_proforma	nepovinný paramater	Zálohova faktúra. V prípade, že sa jedná o zálohovu faktúru, je potrebné vložiť hodnotu 1. Predvolená hodnota: 0
f_paid	nepovinný paramater	Už uhradené. Suma. Predvolená hodnota: 0
f_style	nepovinný paramater	Vizuálny štýl faktúry. Možné hodnoty: standard classic clear Predvolená hodnota: standard
f_language	nepovinný paramater	Jazyk faktúry. Možné hodnoty: SK, EN, DE, CZ, FR, ES, IT, HU, PL, RU, NO Predvolená hodnota: SK
f_qr	nepovinný paramater	Zobraziť QR kód platby. Možné hodnoty: 1 0 Predvolená hodnota: 1
f_omit_stats	nepovinný paramater	Vynechať hodnotu zo štatistiky. Možné hodnoty: 0 1 Predvolená hodnota: 0

Parametre položiek faktúry:

Parameter	Atribút	Popis
p_text	povinný paramater	Text fakturačnej položky.
p_quantity	povinný paramater	Množstvo. Číslo.
p_unit	povinný paramater	Merná jednotka. Napríklad kg, ks,...
p_price	možnosť 1 / nepovinný paramater	Cena za jednu mernú jednotku bez dane. Na základe tejto hodnoty sa vypočíta cena s DPH. V príde, že tento atribút nie je zadaný, musí byť zadaný atribút p_pricevat. Pre neplatcov DPH je tento parameter povinný.
p_vat	nepovinný paramater	Daň v percentách. Vypĺňa sa iba vtedy, ak je dodávateľ platca DPH.
p_pricevat	možnosť 2 / nepovinný paramater	Cena za jednu mernú jednotku vrátane dane. V prípade, že je tento atribút zadaný, vypočíta sa cena bez dane bez ohľadu, či bol atribút p_price zadaný.

Formát dát pred odoslaním:

Zoznam návratových kódov:

Status ID	Význam	Popis
1	OK	Všetko prebehlo v poriadku, faktúra bola vytvorená
2	Chyba	Parameter data nebol odoslaný metódou GET.
3	Chyba	API kľúč nie je zadaný alebo nie je platný počet reťazcov.
4	Chyba	API kľúč nie je zadaný správne.
5	Chyba	Parameter email nie je zadaný.
6	Chyba	Používateľské meno alebo API kľúč nie sú uvedené správne.
7	Chyba	Používateľ neexistuje.
8	Chyba	Potrebné zadať ID dodávateľa alebo jeho názov..
9	Chyba	Zrušené
10	Chyba	Vložené ID dodávateľa nie je správne.
11	Chyba	Nie je zadané meno dodávateľa.
12	Chyba	Nie je zadané meno odberateľa.
13	Chyba	Chýbajú fakturačné údaje.
14	Chyba	Chýbajú položky faktúry alebo nie sú zadané správne.
15	Chyba	Chyba vo fakturačnej položke chýba povinný údaj.
16	Chyba	Množstvo vo fakturačnej položke nie je číslo.
17	Chyba	Cena bez dane vo fakturačnej položke nie je číslo.
18	Chyba	Daň v percentách nie je zadaná správne.
19	Chyba	Vo fakturačnej položke nie je vložená cena bez dane alebo cena vrátane dane.
20	Chyba	Nepovolený jazyk vo faktúre.
21	Chyba	Vo fakturačnej položke nie je vložená cena bez dane, pričom dodávateľ nie je platcom DPH.
22	Chyba	Cena vrátane dane vo fakturačnej položke nie je číslo.

Ukážka zdrojového kódu:

<?php

// Príprava základných dát:
$data = array();

// Váš API kľúč:
$data['key'] = "dJyMc*53@687*wGhofIWi!WDcEEQUdmj";

// Váš email (príp. používateľské meno):
$data['email'] = "name@example.com";

// V prípade, že budeme testovať API, zvolíme hodnotu 1
// Znamená to, že všetky vytvorené faktúry sa automaticky odstránia o 5 - 10 minút a nebudú sa 
// započítavať k skutočne vytvoreným faktúram.
$data['apitest'] = 1; //hodnota môže byť 1 alebo 0


// Príprava dát dodávateľa
$dodavatel = array();

// Dodávateľa môžeme použiť už existujúceho (uloženého v zozname Moje spoločnosti)
// alebo dodávateľa vytvoríme ručne vložením dát.
// Ak použijeme existujúceho dodávateľa, vložíme iba jeho ID:
// $dodavatel['d_id'] = 123; // ID dodávateľa nájdeme v zozname Moje spoločnosti

// alebo (nie obe):
$dodavatel['d_name'] = "Moja spoločnosť s.r.o."; // Obchodný názov dodávateľa
$dodavatel['d_street'] = "Mostová 56"; // Ulica
$dodavatel['d_city'] = "Trenčín"; // Mesto
$dodavatel['d_zip'] = "843 21"; // PSČ
$dodavatel['d_state'] = "Slovenská republika"; // Štát
$dodavatel['d_ico'] = "43226520"; // IČO
$dodavatel['d_dic'] = "2165052345"; // DIČ
$dodavatel['d_icdph'] = "SK2165052345"; // IČDPH
$dodavatel['d_vatpayer'] = "1"; // Platca DPH. Pokiaľ je dodávateľ platca DPH ponechajte hodnotu 1,
				                // ak nie je platca DPH, napíšte 0.
$dodavatel['d_viewpayer'] = "0"; // Pokiaľ nechcete zobraziť informáciu na faktúre,
                                 // že dodávateľ je alebo nie je platcom DPH.
$dodavatel['d_info'] = "Zapísaný v OR Trenčín,oddiel:Sro, vl.č.1234/X"; //Info o dodávateľovi
$dodavatel['d_bankaccount'] = "1234567890/0200"; // Číslo účtu
$dodavatel['d_bank'] = "VÚB"; // Názov banky
$dodavatel['d_iban'] = ""; // IBAN
$dodavatel['d_swift'] = ""; // SWIFT
$dodavatel['d_email'] = "info@example.com"; // E-mail
$dodavatel['d_web'] = "www.example.com"; // WEB
$dodavatel['d_phone'] = "+421 903 111 111"; // Telefón

// Pridanie dodávateľa k dátam:
$data['d'] = $dodavatel;


// Príprava dát odberateľa
$odberatel = array();
$odberatel['o_name'] = "Andrej Klačanský"; // Názov odberateľa
$odberatel['o_street'] = "Štefánikova 455/2"; // Ulica
$odberatel['o_city'] = "Martin"; // Mesto
$odberatel['o_zip'] = "876 54"; // PSČ
$odberatel['o_state'] = ""; // Štát
$odberatel['o_ico'] = ""; // IČO
$odberatel['o_dic'] = ""; // DIČ
$odberatel['o_icdph'] = ""; // IČDPH
$odberatel['o_email'] = "client@example.com"; // Email odberateľa

// Pridanie odberateľa k dátam:
$data['o'] = $odberatel;



// Príprava fakturačných údajov
$faktura = array();

// Číslo faktúry môžeme zadať ručne:
$faktura['f_number'] = "2015099";
// Ak chceme vypočítať číslo automaticky, toto pole neuvedieme
$faktura['f_vs'] = "2015099"; // Variabilný symbol
$faktura['f_ks'] = "308"; // Konštantný symbol
$faktura['f_date_issue'] = '2015-02-14'; // Dátum vystavenia vo formáte RRRR-MM-DD
$faktura['f_date_delivery'] = '2015-02-14'; // Dátum dodania vo formáte RRRR-MM-DD
$faktura['f_date_due'] = '2015-02-28'; // Dátum splatnosti vo formáte RRRR-MM-DD
$faktura['f_issued_by'] = "Moja spoločnosť s.r.o.";  //Faktúru vystavil
$faktura['f_payment'] = "prevod";   //Druh plaby. Na výber sú "prevod", "poukazka",
                                    // "hotovost", "dobierka", "registracna_pokladna", "ina",
                                    // "eprovider"
$faktura['f_logo'] = "0";   // Zobraziť logo dodávateľa. Iba v prípade, že bol dodávateľ
                            //vybraný pomocou ID a má priradené logo
$faktura['f_stamp'] = "1";  // Zobraziť pečiatku dodávateľa. Iba v prípade, že bol 
                            // dodávateľ vybraný pomocou ID a má priradenú pečiatku
$faktura['f_currency'] = "EUR";  //Mena faktúry
$faktura['f_proforma'] = "0";  // Zálohová faktúra. Ak je zálohová, potom hodnota 1
$faktura['f_paid'] = "";  // Už uhradená suma
$faktura['f_style'] = "standard";  // Štýl faktúry. Možnosti sú standard alebo classic
$faktura['f_language'] = "SK";   // Jazyk faktúry, povolené sú: SK, EN alebo DE
$faktura['f_qr'] = "1";   // Zobraziť QR kód (PAY by square)

// Pridanie fakturačných údajov k dátam:
$data['f'] = $faktura;


// Príprava fakturačných položiek
$polozky = array();
// prvá položka:
$polozka = array();
$polozka['p_text'] = "Maliarske práce"; // Názov služby alebo tovaru
$polozka['p_quantity'] = "3"; // Množstvo
$polozka['p_unit'] = "hod"; // Merná jednotka
$polozka['p_price'] = "15"; // Cena za jednu jednotku bez DPH (Cena s DPH sa vypočíta)
$polozka['p_vat'] = "20"; // Daň v %
// priradenie k položkám:
$polozky[] = $polozka;

// druhá položka:
$polozka = array();
$polozka['p_text'] = "Upratovacie práce"; // Názov služby alebo tovaru
$polozka['p_quantity'] = "2"; // Množstvo
$polozka['p_unit'] = "hod"; // Merná jednotka
$polozka['p_vat'] = "20"; // Daň v %
$polozka['p_pricevat'] = "14.4"; // Cena za jednu jednotku vrátane DPH (Cena bez DPH sa vypočíta)
// priradenie k položkám:
$polozky[] = $polozka;

// priradenie fakturačných položiek k dátam:
$data['p'] = $polozky;


// Dáta sa uložia do formátu JSON:
$data_json = json_encode($data);

// Dáta sa odošlú (prípadne pomocou CURL):
$url =  'https://www.faktury-online.com/api/nf?data='.urlencode($data_json); 
$output = file_get_contents($url);

// Výsledok:
$result = json_decode($output, true);
if ($result['status'] == 1)
	echo "Uložené, nová faktúra má kód: ".$result['code'];
else
	echo "Vyskytla sa chyba č.".$result['status'];

Odpoveď:

Array
(
    [status] => 1
    [code] => 1a35b89cd48eaf8940a6409ff45a0cc5
)

Inicializácia sedenia

Inicialializácia sedenia je potrebná pre zobrazenie faktúry. Volanie API pre vytvorenie inicializácie sedenia:

https://www.faktury-online.com/api/init?data={JSON}

Základné parametre:

Parameter	Atribút	Popis
key	povinný parameter	API kľúč.
email	povinný parameter	Email (alebo používateľské meno), ktorým sa prihlasujete do Faktúr online.

Základné parametre:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [username] => peterM22
)

Zoznam návratových kódov:

Status ID	Význam	Popis
1	OK	Všetko prebehlo v poriadku, inicializácia sedenia bola vytvorená
102	Chyba	Parameter data nebol odoslaný metódou GET.
103	Chyba	API kľúč nie je zadaný alebo nie je platný počet reťazcov.
104	Chyba	API kľúč nie je zadaný správne.
105	Chyba	Parameter email nie je zadaný.
106	Chyba	Používateľské meno alebo API kľúč nie sú uvedené správne.
107	Chyba	Používateľ neexistuje.

Ukážka zdrojového kódu:

<?php

function grabPage($url)
{
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_COOKIEJAR, 'cookie.txt');
    curl_setopt($ch, CURLOPT_COOKIEFILE, 'cookie.txt');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    return curl_exec($ch);
}

// Príprava základných dát:
$data = array();

// Váš API kľúč:
$data['key'] = "dJyMc*53@687*wGhofIWi!WDcEEQUdmj";

// Váš email (príp. používateľské meno):
$data['email'] = "name@example.com";

// Dáta sa uložia do formátu JSON:
$data_json = json_encode($data);

// Inicializácia sedenia
$url =  'https://www.faktury-online.com/api/init?data='.urlencode($data_json); 
$output = grabPage($url);

// Výsledok:
$result = json_decode($output, true);
if ($result['status'] == 1)
	echo "Sedenie bolo vytvorené";
else
	echo "Vyskytla sa chyba č.".$result['status'];

Odpoveď:

Array
(
    [status] => 1
)

Zobrazenie faktúry

Pred týmto volaním je potrbné inicializovať sedenie (viď vyššie). Volanie API pre zobrazenie faktúry:

https://www.faktury-online.com/api/zf?data={JSON}

Základné parametre:

Parameter	Atribút	Popis
key	povinný parameter	API kľúč.
email	povinný parameter	Email (alebo používateľské meno), ktorým sa prihlasujete do Faktúr online.
code	povinný parameter	kód faktúry (získaný z odpovede API vytvorenia faktúry)
download	nepovinný parameter	Hodnotou download sa výsledná faktúra nezobrazí ako PDF súbor, ale priamo sa stiahne.

Základné parametre:

Array
(
    [key] => vJyMc*4@2754*wGhofIWi!QDcEEQUdmj
    [username] => peterM22
    [code] => 26915945a67c8b7ba74dac59c5badfbf
    [download] => download
)

Zoznam návratových kódov:

Status ID	Význam	Popis
1	OK	Všetko prebehlo v poriadku, url na zobrazenie faktúry sa vygenerovalo
202	Chyba	Parameter data nebol odoslaný metódou GET.
203	Chyba	API kľúč nie je zadaný alebo nie je platný počet reťazcov.
204	Chyba	API kľúč nie je zadaný správne.
205	Chyba	Parameter email nie je zadaný.
206	Chyba	Nie je vytvorené sedenie
207	Chyba	Vytvorené sedenie nie je správne
208	Chyba	Používateľské meno alebo API kľúč nie sú uvedené správne.
209	Chyba	Používateľ neexistuje.
210	Chyba	Nie je zadaný kód faktúry.
211	Chyba	Kód faktúry nie je zadaný správne.
212	Chyba	Chyba pri výbere faktúry
213	Chyba	Chyba pri výbere faktúry

Ukážka zdrojového kódu:

<?php

function grabPage($url)
{
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_COOKIEJAR, 'cookie.txt');
    curl_setopt($ch, CURLOPT_COOKIEFILE, 'cookie.txt');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 5);
    return curl_exec($ch);
}

// Príprava základných dát:
$data = array();

// Váš API kľúč:
$data['key'] = "dJyMc*53@687*wGhofIWi!WDcEEQUdmj";

// Váš email (príp. používateľské meno):
$data['email'] = "name@example.com";

// Dáta sa uložia do formátu JSON:
$data_json = json_encode($data);

// Inicializácia sedenia
$url =  'https://www.faktury-online.com/api/init?data='.urlencode($data_json); 
$output = grabPage($url);

// Výsledok:
$result = json_decode($output, true);
if ($result['status'] != 1)
	die ("Vyskytla sa chyba č.".$result['status']);


// Faktúru chceme stiahnuť
$data['download'] = "download";

// Kód faktúry:
$data['code'] = "14915945a66c8b7be74dac59c5badfbf";

// Dáta sa uložia do formátu JSON:
$data_json = json_encode($data);


// Dáta sa odošlú (pomocou CURL):
$url =  'https://www.faktury-online.com/api/zf?data='.urlencode($data_json);
$output = grabPage($url);

// Výsledok:
$result = json_decode($output, true);
if ($result['status'] == 1)
	// Presmerovanie na faktúru
	header('location: '.$result['url']);
else
	echo "Vyskytla sa chyba č. ".$result['status'];

Odpoveď:

Array
(
    [status] => 1
    [url] => https://www.faktury-online.com/faktury/detail-subor?f=26915945a67c8b7ba74dac59c5badfbf&download=1
)