SF API umožňuje propojení externích aplikací se SuperFakturou a dovoluje tak vzdáleně vytvářet faktury a získavat údaje o nich. Umožňuje také posílat faktury emailem nebo poštou.
🚨 Upozornění: Tento repozitář už není aktivně spravovaný, jako alternativu doporučujeme: superfaktura/apiclient 🚨
Abyste se nemuseli trápit s přímým voláním API funkcí a způsobem přenosu dat, připravili jsme pro Vás jednoduchého API klienta, díky kterému můžete Vaše faktury vystavovat nadálku s minimálním úsilím.
Pokud si však chcete vytvořit vlastního API klienta, máme i obecnou dokumentaci.
Pokud chcete API integraci vyzkoušet, máme pro vás testovací prostředí - sandbox.
- vytvořte si adresář, který má obsahovat SuperFaktura PHP-API např. ($> Mkdir / var / www / myproject / libs)
- přepněte se do nově vytvořeného adresáře a spusťte přes konzoli příkaz $> git clone https://github.com/superfaktura/apiclient.git
- Stáhněte si SuperFaktúra PHP-API kliknutím na tlačítko "Stáhnout ZIP", které se nachází na github stránce našeho API.
Abychom vám usnadnili práci při implementaci našeho API, vytvořili jsme ukázky kódu (sample.php a sample2.php), které demonstrují jeho funkcionalitu a dpĺňajú naši dokumentaci o fungující příklady.
Na to, abyste mohli začít API na plno využívat, je třeba:
- Na stránce https://moje.superfaktura.cz/registracia proveďte registraci. Automaticky získáte 30 dní zdarma.
- Po přihlášení vystavte zkušební fakturu přes GUI SuperFaktury
Pokud chcete zkoušet API klienta na sandboxu, zaregistrujte se na sandboxu a v kódu stačí zavolat metodu useSandbox.
$api = new SFAPIclient(SFAPI_EMAIL, SFAPI_KEY);
$api->useSandBox();
- Vytvořit novou instance třídy SFAPIclientCZ
- Poskytnout v konstruktoru přihlašovací údaje do API
- Email - přihlašovací email do SuperFaktúry
- Token - API token, který najdete v SuperFaktúre po přihlášení do svého účtu "Nástroje> API přístup"
require_once('SFAPIclient/SFAPIclient.php'); // inc. SuperFaktúra PHP-API
$login_email = '[email protected]'; // moje.superfaktura.cz login email
$api_token = 'abcd1234'; // token from my account
$sf_api = new SFAPIclientCZ($login_email, $api_token); // create SF PHP-API objectNíže je uveden seznam všech možných volání, které obsahuje nejnovější verze našeho API. Všechny PHP funkce našeho API jsou veřejné členské funkce třídy SFAPIclient. Příklad vystavení jednoduché faktury (pokračování předch. příkladu)
// set client for new invoice
$sf_api->setClient(array(
'name' => 'MyClient',
'address' => 'MyClient address 1',
'zip' => 12345,
'city' => 'MyClientCity'
));
// set invoice attributes
$sf_api->setInvoice(array(
'name' => 'MyInvoice'
));
// add new invoice item
$sf_api->addItem(array(
'name' => 'MyInvoiceItem',
'description' => 'Inv. item no. 1',
'unit_price' => 10,
'tax' => 20
));
// save invoice in SuperFaktura
$json_response = $sf_api->save();
// TODO: handle exceptions- __construct($email, $apikey, $apptitle = '', $module = 'API', $company_id = '')
- addItem($item = array())
- addStockItem($item = array())
- addStockMovement($item = array())
- addTags($tag_ids = array())
- clients($params = array(), $list_info = true)
- delete($id)
- deleteInvoiceItem($invoice_id, $id)
- deleteExpense($id)
- deleteStockItem($id)
- edit()
- expense()
- expenses()
- getCountries()
- getSequences()
- getPDF($invoice_id, $token, $language = 'slo')
- getTags()
- invoice($id)
- invoices($params = array(), $list_info = true)
- markAsSent($invoice_id, $email, $subject = '', $message = '')
- payInvoice($invoice_id, $amount, $currency = 'EUR', $date = null, $payment_type = 'transfer')
- payExpense($expense_id, $amount, $currency = 'EUR', $date = null, $payment_type = 'transfer')
- save()
- setClient($key, $value = '')
- setExpense($key, $value = '')
- setInvoice($key, $value = '')
- sendInvoiceEmail($options = array())
- sendInvoicePost($options = array())
- stockItemEdit($item = array())
- stockItems($params = array(), $list_info = true)
- stockItem($id)
- addContactPerson($data)
- getExpenseCategories()
- setInvoiceSettings($settings)
- setInvoiceExtras($extras)
- cashRegister($cash_register_id)
- sendSMS($data)
- setMyData($key, $value = '')
- getInvoiceDetails($ids = '')
- getUserCompaniesData($getAllCompanies = false)
- createRegularFromProforma($proforma_id)
- setEstimateStatus($estimate_id, $status)
- getBankAccounts()
- addBankAccount(array $data)
- updateBankAccount(int $id, array $data)
- deleteBankAccount(int $id)
- addTag(array $data)
- updateTag(int $id, array $data)
- deleteTag(int $id)
- client(int $id)
- addRelatedItemToInvoice(int $item_id, int $related_item_id, string $related_item_type)
- addRelatedItemToExpense(int $item_id, int $related_item_id, string $related_item_type)
- deleteRelatedItemFromInvoice(int $connection_id)
- deleteRelatedItemFromExpense(int $connection_id)
Konstruktor. Nastaví email a API token pro autorizaci.
- $email string povinný
- $token string povinný
- $apptitle string nepovinný, název aplikace
- $module string nepovinný, název modulu
- $company_id integer nepovinný, ID společnosti, se kterou přes API pracujete (v případě, že máte jen jednu společnosti nemusíte uvádět)
Přidá položku na fakturu.
- $item pole povinné
- $item_type string typ položky. Možné hodnoty Invoice(default) a Expense
array(
'name' => 'Název položky',
'description' => 'Popis',
'quantity' => 1, //množství
'unit' => 'ks', //jednotka
'unit_price' => 40.83, //cena bez DPH, resp. celková cena, pokud nejste platci DPH
'tax' => 20, //sazba DPH, pokud nejste plátcem DPH, zadajte 0
'stock_item_id' => 123, //id skladové položky
'sku' => 'SKU123', //skladové označení
'discount' => 50, //Sleva na položku v %
'discount_description' => 'Popis slevy',
'load_data_from_stock' => true //Načíst nevyplněné údaje položky ze skladu
'use_document_currency' => true //V případě, že je zadáno load_data_from_stock, tak přepočítá skladovou položku, do měny dokladu.
'AccountingDetail' => array( // účtovnícke detaily položky,
'place' => 'Stredisko Bratislava', //nazov strediska
'order' => 'názov', //nazov zákazky
'operation' => 'názov', //činnosť
'type' => 'item', // typ polozky (item(tovar), service(služba))
'analytics_account' => '311', //analytický účet
'synthetic_account' => '000', //syntetický účet
'preconfidence' => '5ZV' // predkontácia
)
)Přidá faktuře tagy podle číselníku
- $tags_ids pole povinné. Pole ID tagů.
Kvůli možnému konfliktu názvů tagů a jejich ID-ček (např. 2019 - rok vs ID) nelze přidávat přímo názvy tagů.
Chcete-li uložit nový tag, je třeba jej předtím přidat addTag.
Vrátí seznam klientů
(všeobecná REST API dokumentace)
- $params pole povinné. Parametry pro filtrování a stránkování.
- $list_info bool nepovinné. Určí zda vrácené data budou obsahovat i údaje o seznamu (celkový počet položek, počet stránek...)
array(
'search' => '', //Hledaný výraz v klientovi. Prohledává všechy pole.
){
"itemCount": 67,
"pageCount": 7,
"perPage": 10,
"page": 1,
"items": [{ "Client": {...}, },...]
}Smaže fakturu
(všeobecná REST API dokumentace)
- $id int povinné. Získané z Invoice->id.
Smaže položku na faktuře.
(všeobecná REST API dokumentace)
- $invoice_id int povinné. Získané z Invoice->id.
- $id int povinné. Získané z InvoiceItem->id.
Smaže náklad.
(všeobecná REST API dokumentace)
- $id int povinné. Získané z Expense->id.
Smaže skladovou položku.
(všeobecná REST API dokumentace)
- $id int povinné. Získané z StockItem->id.
Uloží nastavené data a aktualizuje fakturu
(všeobecná REST API dokumentace)
- 1 Id dokladu nemá správný formát
- 2 Neexistující id dokladu
- 3 Chyba při editaci faktury. Volání třeba opakovat.
- 6 Chyba při validaci údajů. Povinné údaje chýbějí nebo nemají správný formát.
Vrátí seznam nákladů
(všeobecná REST API dokumentace)
- $params pole povinné. Parametry pro filtrování a stránkování.
- $list_info bool nepovinné. Určuje zda vrácené data budou obsahovat i údaje o seznamu (celkový počet položek, počet stránek...)
Vrátí detaily nákladu
(všeobecná REST API dokumentace)
- $expense_id int povinné. Získané z Expense->id.
Vrátí číselník zemí.
(všeobecná REST API dokumentace)
Vrátí číselník číselných řad podle typů dokumentů.
(všeobecná REST API dokumentace)
Vrátí PDF soubor s fakturou
(všeobecná REST API dokumentace)
- $invoice_id int povinné. Získané z Invoice->id.
- $token string povinné. Získané z Invoice->token.
- $language string nepovinné. Jazyk požadovaného PDF. Možné hodnoty jsou {slo, cze, eng, deu, rus, ukr, hun, pol, rom, hrv, slv, spa, ita, nld}
Vrátí číselník existujících tagů
(všeobecná REST API dokumentace)
Vrátí detail faktury
(všeobecná REST API dokumentace)
- $invoice_id int povinné. Získané z Invoice->id.
Vrátí seznam vystavených faktur
(všeobecná REST API dokumentace)
- $params pole povinné. Parametry pro filtrování a stránkování.
- $list_info bool nepovinné. Určuje zda vrácená data budou obsahovat i údaje o seznamu (celkový počet položek, počet stránek...)
array(
'page' => 1, //Stránka
'per_page' => 10, //Počet položek na stránku
'created' => 0, //Datum vystavení.
'delivery' => 0, //Datum dodání.
'modified' => 0, //Datum poslední změny.
'type' => 'regular', //Typ faktury. Více typů je možné kombinovat pomocí "|" např. "regular|cancel"
'delivery_type' => 'mail', //Typ faktúry. Viíce typů je možné kombinovat pomocí "|" např. "mail|personal" 'payment_type' => 'transfer', //Typ faktúry. Více typů je možné kombinovat pomocí "|" např. "mail|personal"
'status' => 0, //Stav faktury.
'client_id' => 1, //ID klienta. Seznam klientů je možné získat metodou clients()
'amount_from' => 0, //Suma faktury od
'amount_to' => 0, //Suma faktury do
'paid_since' => 0, //Faktura uhrazená od
'paid_to' => 0, //Faktura uhrazená do
'search' => '', //Hledaný výraz ve faktuře. Prohledává všechny pole.
'ignore' => '1|2|3', //ID faktur, které se mají ignorovat.
'order_no'=> '2016001', //číslo cenové nabídky z níž byla FA vytvořena
){
"itemCount": 67,
"pageCount": 7,
"perPage": 10,
"page": 1,
"items": [{
"Client": {...},
"Invoice": {"id": "8358",...}
"InvoicePayment": {},
"InvoiceEmail": {},
"PostStamp": {}
},...]
} Array (
[0] => Všechno
[1] => Dnes
[2] => Včera
[4] => Tento měsíc
[5] => Minulý měsíc
[8] => Tento kvartál
[7] => Minulý rok
[6] => Tento rok
[3] => od - do //v případě hodnoty od - do je potřeba uvést i parametry created_since a created_to
)Typ faktury
Array (
[regular] => Bežná
[proforma] => Zálohová faktura
[estimate] => Cenová nabídka
[cancel] => Dobropis
[order] => Přijatá objednávka
[delivery] => Dodací list
)Způsob dodání
Array (
[mail] => Poštou
[courier] => Kurýrem
[personal] => Osobní odběr
[haulage] => Nákladní doprava
[pickup_point] => Odběrní místo
)Způsob úhrady
Array (
[transfer] => Bankovním převodem
[cash] => Hotovost
[paypal] => Paypal
[credit] => Kreditní karta
[debit] => Debitní karta
[cod] => Dobírka
[accreditation] => Vzájemný zápočet
[inkaso] => Inkaso
[gopay] => GoPay
)Stav faktury
Array (
[0] => Všechno
[1] => Čekají na uhrazení
[2] => Částečně uhrazené
[3] => Uhrazené
[99] => Po splatnosti
)Příklad filtrování faktur pomocí ID číselníku
require_once('SFAPIclient/SFAPIclient.php'); // inc. SuperFaktúra PHP-API
$login_email = '[email protected]'; // moje.superfaktura.cz login email
$api_token = 'abcd1234'; // token from my account
$sf_api = new SFAPIclient($login_email, $api_token); // create SF PHP-API object
$json_response = $sf_api->invoices(array(
'sequence_id' => ID, // integer
'type' => 'regular'
));Označí fakturu jako odeslanou e-mailem. Užitečné, pokud vytvořené faktury odosíláte vlastním systémem, avšak chcete toto odoslání evidovat i v SuperFaktuře.
(všeobecná REST API dokumentace)
- $invoice_id int povinné. Získané z Invoice->id
- $email string povinné. E-mailová adresa, kam byla faktura odeslaná.
- $subject string nepovinné. Předmět e-mailu.
- $message string nepovinné. Text e-mailu.
Dodatečně přidá úhradu k faktuře.
(všeobecná REST API dokumentace)
- $invoice_id int povinné. Získané z Invoice->id
- $amount float povinné. Uhrazená suma.
- $currency string nepovinné. Měna úhrady, předvolená CZK.
- $date string nepovinné. Datum úhrady, předvolený aktuální datum.
- $payment_type string nepovinné. Způsob úhrady, předvolený typ transfer. Možné hodnoty {transfer, cash, paypal, credit, debit, cod, accreditation, inkaso, gopay}
- $cash_register_id int nepovinné. ID pokladny
Dodatečně přidá úhradu k nákladu.
(všeobecná REST API dokumentace)
- $expense_id int povinné. Získané z Expense->id
- $amount float povinné. Uhradená suma.
- $currency string nepovinné. Měna úhrady, předvolená CZK.
- $date string nepovinné. Datum úhrady, předvolený aktuální datum.
- $payment_type string nepovinné. Způsob úhrady, předvolený typ transfer. Možné hodnoty {transfer, cash, paypal, credit, debit, cod, accreditation, inkaso, gopay}
Uloží nastavené data a vystaví fakturu
(všeobecná REST API dokumentace)
{
"error": 0,
"error_message": "Invoice created",
"data": {
"Invoice": {
"id": "947592",
"user_id": "15968",
"user_profile_id": "10156",
"client_id": "518992",
"parent_id": null,
"proforma_id": null,
"estimate_id": null,
"sequence_id": "41008",
"import_type": null,
"import_id": null,
"import_parent_id": null,
"type": "regular",
"tax_document": null,
"name": "Faktura test",
"lang": null,
"client_data": "{\"Client\":{\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"country_id\":\"191\",\"name\":\"Klient test\",\"ico\":987654321,\"dic\":314,\"ic_dph\":null,\"bank_account\":null,\"email\":null,\"address\":null,\"city\":null,\"zip\":null,\"state\":null,\"country\":null,\"delivery_name\":null,\"delivery_address\":null,\"delivery_city\":null,\"delivery_zip\":null,\"delivery_state\":null,\"delivery_country\":null,\"delivery_country_id\":null,\"phone\":null,\"fax\":null,\"due_date\":null,\"default_variable\":null,\"discount\":null,\"currency\":\"EUR\",\"comment\":null,\"tags\":null,\"demo\":\"0\",\"update_addressbook\":true}}",
"my_data": "{\"MyData\":{\"id\":\"10156\",\"user_id\":\"15968\",\"country_id\":\"191\",\"company_name\":\"Jan Doczy\",\"ico\":\"41432312\",\"dic\":\"CZ29413893fdsafdasfdsadfasfdjasf\",\"ic_dph\":\"012345678fjdksjfkldajklfdjasklfj\",\"business_register\":\"Okr. s\\u00fad BA 1, odd. SRO, vl. \\u010d 1234\\/B\",\"address\":\"\",\"city\":\"\",\"zip\":\"\",\"tax_payer\":\"1\",\"country\":\"Slovensko\",\"BankAccount\":[{\"id\":\"9998\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":\"1\",\"country_id\":\"191\",\"bank_name\":\"UniCredit Bank Slovakia\",\"bank_code\":\"1111\",\"account\":\"1119090001\",\"iban\":\"SK8011110000001119090001\",\"swift\":\"UNCRSKBX\",\"created\":\"2014-10-06 13:25:30\",\"modified\":\"2015-08-21 08:09:07\"},{\"id\":\"10121\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":null,\"country_id\":\"191\",\"bank_name\":\"\",\"bank_code\":\"\",\"account\":\"\",\"iban\":\"\",\"swift\":\"\",\"created\":\"2014-10-17 09:05:54\",\"modified\":\"2014-10-17 09:05:54\"},{\"id\":\"10434\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":null,\"country_id\":\"191\",\"bank_name\":\"\",\"bank_code\":\"\",\"account\":\"\",\"iban\":\"\",\"swift\":\"\",\"created\":\"2014-11-18 14:29:46\",\"modified\":\"2014-11-18 14:29:46\"},{\"id\":\"10502\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":null,\"country_id\":\"191\",\"bank_name\":\"\",\"bank_code\":\"\",\"account\":\"\",\"iban\":\"\",\"swift\":\"\",\"created\":\"2014-11-25 09:33:31\",\"modified\":\"2014-11-25 09:33:31\"},{\"id\":\"10530\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":null,\"country_id\":\"191\",\"bank_name\":\"\",\"bank_code\":\"\",\"account\":\"\",\"iban\":\"\",\"swift\":\"\",\"created\":\"2014-11-27 09:20:29\",\"modified\":\"2014-11-27 09:20:29\"},{\"id\":\"10774\",\"user_id\":\"15968\",\"user_profile_id\":\"10156\",\"default\":null,\"country_id\":\"191\",\"bank_name\":\"\",\"bank_code\":\"\",\"account\":\"\",\"iban\":\"\",\"swift\":\"\",\"created\":\"2014-12-15 14:29:54\",\"modified\":\"2014-12-15 14:29:54\"}]}}",
"items_data": "Polozka test , ",
"invoice_no": "9",
"order_no": null,
"invoice_no_formatted": "201500009",
"mask": "YYYYNNN",
"variable": "201500009",
"constant": "0308",
"specific": null,
"payment_type": null,
"status": "1",
"home_currency": "EUR",
"invoice_currency": "EUR",
"exchange_rate": "1.00000000000000",
"amount": "15.00",
"vat": "0.00",
"discount": "0",
"items_name": null,
"issued_by": null,
"issued_by_phone": "+421000000000",
"issued_by_email": "[email protected]",
"paid": "0.00",
"amount_paid": "0.00",
"deposit": "0.00",
"header_comment": "",
"comment": "Toto je poznamka.",
"internal_comment": null,
"created": "2015-09-02 00:00:00",
"modified": "2015-09-02 08:53:35",
"recurring": null,
"paydate": null,
"delivery": "2015-09-02 00:00:00",
"delivery_type": null,
"due": "2015-09-16",
"demo": "0",
"token": "bd1f145f",
"tags": "",
"rounding": "item",
"vat_transfer": null,
"special_vat_scheme": null,
"issued_by_web": null,
"summary_invoice": "0",
"show_items_with_dph": false,
"show_special_vat": false
},
"Client": {
"id": "518992",
"user_id": "15968",
"user_profile_id": "10156",
"country_id": "191",
"name": "Klient test",
"ico": "987654321",
"dic": "314",
"ic_dph": null,
"bank_account": null,
"email": null,
"address": null,
"city": null,
"zip": null,
"state": null,
"country": null,
"delivery_name": null,
"delivery_address": null,
"delivery_city": null,
"delivery_zip": null,
"delivery_state": null,
"delivery_country": null,
"delivery_country_id": null,
"phone": null,
"fax": null,
"due_date": null,
"default_variable": null,
"discount": null,
"currency": "EUR",
"comment": null,
"tags": null,
"created": "2015-09-02 08:52:49",
"modified": "2015-09-02 08:53:35",
"demo": "0"
},
"InvoicePayment": [],
"InvoiceEmail": [],
"PostStamp": [],
"Tag": [],
"Logo": [
{
"id": "24688",
"model": "User",
"foreign_key": "10156",
"dirname": "img",
"basename": "10156_logo.jpg",
"checksum": "5239f6774ced537687cf90c4561dd438",
"group": "logo",
"alternative": null,
"created": "2014-11-27 09:20:29",
"modified": "2014-11-27 09:20:29"
}
],
"Signature": {
"id": "25789",
"model": "User",
"foreign_key": "10156",
"dirname": "img",
"basename": "10156_sig.png",
"checksum": "d20820f675efdedaef5839a6da30bf97",
"group": "signature",
"alternative": null,
"created": "2014-12-16 14:28:09",
"modified": "2015-04-15 09:41:08"
},
"MyData": {
"id": "10156",
"user_id": "15968",
"country_id": "191",
"company_name": "Jan Doczy",
"ico": "41432312",
"dic": "CZ29413893fdsafdasfdsadfasfdjasf",
"ic_dph": "012345678fjdksjfkldajklfdjasklfj",
"business_register": "Okr. súd BA 1, odd. SRO, vl. č 1234/B",
"address": "",
"city": "",
"zip": "",
"tax_payer": "1",
"country": {
"id": "191",
"name": "Slovensko",
"iso": "sk",
"eu": "1"
},
"BankAccount": [
{
"id": "9998",
"user_id": "15968",
"user_profile_id": "10156",
"default": "1",
"country_id": "191",
"bank_name": "UniCredit Bank Slovakia",
"bank_code": "1111",
"account": "xxxxxxxx",
"iban": "SKxxxxxxxxxxxxxxxxxxxxxxx",
"swift": "UNCRSKBX",
"created": "2014-10-06 13:25:30",
"modified": "2015-08-21 08:09:07"
}
]
},
"ClientData": {
"user_id": "15968",
"user_profile_id": "10156",
"country_id": "191",
"name": "Klient test",
"ico": 987654321,
"dic": 314,
"ic_dph": null,
"bank_account": null,
"email": null,
"address": null,
"city": null,
"zip": null,
"state": null,
"country": null,
"delivery_name": null,
"delivery_address": null,
"delivery_city": null,
"delivery_zip": null,
"delivery_state": null,
"delivery_country": null,
"delivery_country_id": null,
"phone": null,
"fax": null,
"due_date": null,
"default_variable": null,
"discount": null,
"currency": "EUR",
"comment": null,
"tags": null,
"demo": "0",
"update_addressbook": true,
"Country": {
"id": "191",
"name": "Slovensko",
"iso": "sk",
"eu": "1"
}
},
"InvoiceItem": [
{
"id": "2384612",
"invoice_id": "947592",
"user_id": "15968",
"user_profile_id": "10156",
"stock_item_id": null,
"name": "Polozka test",
"description": "",
"sku": null,
"quantity": null,
"unit": null,
"unit_price": 15,
"tax": "0",
"discount": 0,
"discount_description": null,
"ordernum": "0",
"unit_price_discount": 15,
"item_price": 15,
"item_price_no_discount": 15,
"discount_no_vat": 0,
"discount_with_vat": 0,
"discount_with_vat_total": 0,
"discount_no_vat_total": 0,
"unit_price_vat": 15,
"unit_price_vat_no_discount": 15,
"item_price_vat": 15,
"item_price_vat_no_discount": 15,
"item_price_vat_check": 15
}
],
"Summary": {
"vat_base_separate": [
15
],
"vat_base_total": 15,
"vat_separate": [
0
],
"vat_total": 0,
"invoice_total": 15,
"discount": 0
},
"SummaryInvoice": {
"vat_base_separate_positive": [
15
],
"vat_base_separate_negative": [
0
],
"vat_separate_positive": [
0
],
"vat_separate_negative": [
0
]
},
"UnitCount": [],
"Paypal": "https://www.paypal.com/",
"PaymentLink": ""
}
}- 2 Data nebyly odeslané metodou POST.
- 3 Špatná data. Odeslané data nemají správný formát.
- 5 Validačný chyba. Povinné údaje chýbějí nebo nejsou správně vyplněné.
Nastaví hodnoty pro náklad
- $key mixed povinné. Může být string nebo pole. Pokud je string, nastaví se konkrétní hodnota v $data['Expense'][$key]. Pokud je pole, nastaví se více hodnot najednou.
- $value mixed nepovinné. Pokud je $key string, hodnota $value se nastaví v $data['Expense'][$key]. Pokud je $key pole, $value se ignoruje.
Příklad použití:
$api->setExpense('name', 'název nákladu');$api->setExpense(array(
'name' => 'název nákladu', // povinný udaj
'amount' => 10, // suma bez DPH
'vat' => 20, // DPH v procentech
'variable' => '123456', // variabilní symbol
'constant' => '0308', // konstanuložítní symbol
'attachment' => base64_encode(file_get_contents('/tmp/foo.pdf')),
));Seznam možných vlastností nákladu
- name - název nákladu (povinný údaj)
- amount - suma bez daně
- vat - DPH (v procentech)
- already_paid - byla už faktura uhrazená? true/false
- created - datum vystavení
- comment - komentář
- constant - konstantní symbol
- delivery - datum dodání
- due - datum splatnosti
- currency - měna, ve které je faktura vystavená. Možnosti: EUR, USD, GBP, HUF, CZK, PLN, CHF, RUB
- payment_type - Způsob úhrady, číselník hodnot
- specific - specifický symbol
- type - typ faktury. Možnosti: invoice - přijatá faktura, bill - pokladní blok, internal - interní doklad, contribution - odvody
- variable - variabilní symbol
- taxable_supply - Datum uplatnění DPH
- document_number - Číslo dokladu. Například číslo došlé faktury, číslo pokladního bloku a podobně.
- expense_category_id - ID příslušné kategorie. Seznam všech kategorií je možné získat pomocí funkce getExpenseCategories().
- atttachment - soubor přílohy ve formátu base64. Maximální velikost souboru jsou 4MB. Povolené typy:
jpg,jpeg,png,tif,tiff,gif,pdf,tmp,xls,xlsx,ods,doc,docx,xml,csv,msg
Nastaví hodnoty pro fakturu
- $key mixed povinné. Může být string nebo pole. Pokud je string, nastaví se konkrétní hodnota v $data['Invoice'][$key]. Pokud je pole, nastaví se více hodnot najednou.
- $value mixed nepovinné. Pokud je $key string, hodnota $value se nastaví v $data['Invoice'][$key]. Pokud je $key pole, $value se ignoruje.
Příklad použití:
$api->setInvoice('name', 'nazov faktury');$api->setInvoice(array(
'name' => 'nazov faktury',
'variable' => '123456',
'constant' => '0308',
'bank_accounts' => array(
array(
'bank_name' => 'MyBank',
'account' => '012345678',
'bank_code' => '1234',
'iban' => 'SK0000000000000000',
'swift' => '12345',
)
)
));Seznam možných vlastností faktury
- already_paid - byla už faktura uhrazená? true/false
- cash_register_id - int nepovinné. ID pokladny do které bude evidovaná platba (v případě EET pokladny bude tato úhrada zaevidována do EET)
- created - datum vystavení
- comment - komentář
- constant - konstantný symbol
- delivery - Zdanitelné plnění
- delivery_type - spůsob dodání, číselník hodnot
- deposit - uhrazená záloha
- discount - sleva v %
- discount_total - nominální sleva, použije se pouze pokud není nastavena vlastnost discount
- due - datum splatnosti
- estimate_id - ID cenové nabídky, na základě které je faktura vystavená
- header_comment - Text nad položkami faktury
- internal_comment - Interní poznámka, nezobrazuje se klientovi
- invoice_currency - měna, ve ktoré je faktura vystavená. Možnosti: EUR, USD, GBP, HUF, CZK, PLN, CHF, RUB
- invoice_no_formatted - číslo faktury
- issued_by - fakturu vystavil jméno
- issued_by_phone - fakturu vystavil telefon
- issued_by_email - fakturu vystavil e-mail
- issued_by_web - webová stránka zobrazená na faktuře
- name - název faktury
- paydate - datum úhrady
- payment_type - Způsob úhrady, číselník hodnot
- proforma_id - ID proforma faktury, na základě ktoré se vystavuje ostrá faktura. Ostrá faktura tak přebere údaje o uhrazené záloze
- parent_id - ID faktury, ke které chcete vystavit dobropis (opravný daňový doklad)
- rounding - Způsob zaokrouhlování DPH. 'document' => za celý dokument, 'item' => po položkách (předvolená hodnota), 'item_ext' => maloobchod (doporučený typ pro eshopy)
- specific - specifický symbol
- sequence_id - ID číselníku, seznam číselníků je možné získat metodou getSequences
- type - typ faktury. Možnosti: regular - běžná faktura, proforma - zálohová faktura, cancel - dobropis, estimate - cenová nabídka, order - přijatá objednávka
- variable - variabilní symbol (v případě nevyplnění variabilního symbolu se automaticky doplní číslo faktury)
- bank_accounts - (pole) seznam bankovních účtů (viz příklad výše)
- order_no - číslo objednávky
- logo_id - ID loga
- add_rounding_item - (boolean) přidá zaokrouhlení na doklad (při měně EUR zaokrouhluje na 5 centů a u CZK zaokrouhluje na celé číslo)
Odešle fakturu emailem
(všeobecná REST API dokumentace)
- $options array, povinné. Príklad použitia:
$api->sendInvoiceEmail(array(
'invoice_id' => 123456, // povinné
'to' => '[email protected]', // povinné
'cc' => array( '[email protected]' ),
'bcc' => array( '[email protected]' ),
'pdf_language' => eng, //pokud není nastavený nastaví se automaticky
// 'subject' => 'Předmět', // pokud není nastavený subject nastaví se automaticky z e-mailové šablony v nastavení
// 'body' => 'Zpráva' // pokud není nastavené body nastaví se automaticky z e-mailové šablony v nastavení
));Seznam možných nastavení
- invoice_id integer, id faktury, kterou chcete odeslat (povinné)
- to string, na kterou e-mailovou adresu se má faktura odeslat (povinné)
- cc array, cc
- bcc array, bcc
- subject string, předmět
- body string, tělo zprávy
- pdf_language string, jazyk dokladu
Seznam možných jazyků pro doklady:
- 'slo' => slovenština
- 'cze' => čeština
- 'eng' => angličtina
- 'deu' => němčina
- 'rus' => ruština
- 'ukr' => ukrajinština
- 'hun' => maďarština
- 'pol' => poľština
- 'rom' => rumunština
- 'hrv' => chorvatština
- 'slv' => slovinština
- 'spa' => španělština
- 'ita' => italština
- 'nld' => nizozemština
Odešle fakturu poštou
(všeobecná REST API dokumentace)
- $options array, povinné.
Příklad použití:
$api->sendInvoicePost(array(
'invoice_id' => 123456, // povinné
/** > POKUD NEJSOU NASTAVEÉ VYTÁHNOU SE Z FAKTURY < *
******************************************************
'delivery_name' => 'SuperFaktura',
'delivery_address' => 'Adresa 123',
'delivery_city' => 'Město',
'delivery_zip' => '12345',
'delivery_state' => 'Česká republika'
******************************************************/
));Seznam možných nastavení invoice_id integer, id faktury, kterou chcete odeslat (povinné)
Aktualizuje skladovou položku
(všeobecná REST API dokumentace)
- $item array, povinné.
Příklad použití:
$api->stockItemEdit(array(
'stock_item_id' => 123456, // povinné
'name' => '*New stock item name', // nový název skladové položky
'sku' => 'NEWST06K1T3M1D' // nové SKU
));Seznam možných nastavení
- id integer, id skladové položky
- name string, název skladové položky
- description string, popis skladové položky
- sku string, skladové číslo
- unit_price integer, jednotková cena bez DPH
- vat integer, DPH v procentech
- stock integer, počet kusů na skladu. Pokud se vynechá nebude se sledovat stav zásob.
- unit string, jednotka např. ks, mm, m2, dm3, l.
Přidá skladovou položku
(všeobecná REST API dokumentace)
- $item array, povinné.
Příklad použití:
$api->addStockItem(array(
'name' => 'Stock item example', // název skladové položky
'description' => 'Stock item description',
'sku' => 'SKU12345REF', // skladové číslo
'unit_price' => 10, // jednotková cena bez DPH
'vat' => 20, // DPH v procentech
'stock' => 100 // počet kusů na skladu, pokud není definované nebudou se sledovat pohyby
));Seznam možných nastavení
- name string, název skladové položky
- description string, popis skladové položky
- sku string, skladové číslo
- unit_price integer, jednotková cena bez DPH
- vat integer, DPH v procentech
- stock integer, počet kusů na skladu. Pokud se vynechá nebude se sledovat stav zásob.
- unit string, jednotka např. ks, mm, m2, dm3, l.
Přidá pohyb na skladě
(všeobecná REST API dokumentace)
- $item array, povinné.
Příklad použití:
$api->addStockMovement(array(
'stock_item_id' => 0, // id skladové položky
'name' => 'Stock item example', // název skladové položky
'description' => 'Stock item description',
'sku' => 'SKU12345REF', // skladové číslo
'unit_price' => 10, // jednotková cena bez DPH
'vat' => 20, // DPH v procentech
'stock' => 100 // počet kusů na skladu, pokud není definovaný nebudou se sledovat pohyby
));Seznam možných nastavení
- stock_item_id iteger, id skladové položky, ke které chceme přidat pohyb
- quantity integer, pohyb - záporné číslo je výdaj, kladné příjem
- note string, popis pohybu
- created date 'YEAR-MONTH-DAY' format, datum
Nastaví hodnoty pro klienta
Shodné se setInvoice
Seznam možných vlastností klienta
- address - adresa
- bank_account - bankovní účet
- city - město
- comment - komentář
- country_id - ID země, číselník zemí je možné získat metodou getCountries
- country_iso_id ISO 3166-1 (Alpha-2) kód země
- country - vlastní název země
- delivery_address - dodací adresa
- delivery_city - dodací město
- delivery_country - vlastní dodací země
- delivery_country_id - ID dodací země
- delivery_country_iso_id ISO 3166-1 (Alpha-2) kód země
- delivery_name - název klienta pro dodání
- delivery_zip - dodací PSČ
- dic - DIČ
- email - e-mail
- fax - fax
- ic_dph - IČ DPH
- ico - IČ
- name - název klienta
- phone - telefon
- delivery_phone - telefonní číslo pro dodání
- zip - PSČ
- match_address (boolean) - pokud je tento parameter nastavený, do hledaní klienta vstupuje i adresa.
- update_addressbook (boolean) - při vystavení faktury aktualizuje údaje klienta
V případě zahraničního klienta je potřebné správně vyplnit country_id. Když country_id zůstane prázdné, použije se předdefinovaná hodnota pro Českou republiku. Na zjištění country_id konkrétní krajiny použijte funkci getCountries().
Vrátí seznam skladových položek
(všeobecná REST API dokumentace)
- $params pole povinné. Parametry pro filtrování a stránkování.
- $list_info bool nepovinné. Určuje, jestli vrácené data budou obsahovat i údaje o seznamu (celkový počet položek, počet stránek...)
array(
'page' => 1, //Stránka
'per_page' => 10, //Počet položek na stránku
'price_from' => 0, //Cena od
'price_to' => 0, //Cena do
'sku' => '', // Unikátní číslo skladové položky pomůže položku jednoduše identifikovat
'search' => '', //Hledaný výraz. Prohledáva všechny pole.
)Formát vrácených dat { "itemCount": 67, "pageCount": 7, "perPage": 10, "page": 1, "items": [{ "StockItem": {...}, }, ...] }
Vrátí detail skladové položky
(všeobecná REST API dokumentace)
- $stock_item_id int povinné. Získané z StockItem->id.
Přidá novou kontaktní osobu ke stávajícímu klientovi. Návratová hodnota je objekt (JSON). Pokud operace proběhla bez problémů je nastaven atribut status na hodnotu (string) 'SUCCESS'.
(všeobecná REST API dokumentace)
$result = $api->addContactPerson(array(
'client_id' => ID_KLIENTA, // ID existujuceho klienta
'name' => 'Contact Person', // Nazov kotaktnej osoby
'email' => '[email protected]' // Email pre kontaktnu osobu
));
if ($result->status === 'SUCCESS')
...;Vrátí detaily všech log. Návratová hodnota je objekt (JSON).
(všeobecná REST API dokumentace)
Vrátí seznam všech kategorií nákladů. Návratová hodnota je objekt (JSON).
(všeobecná REST API dokumentace)
nastaví vlastnosti pri zobrazovaní faktúry
- $settings array, povinné. Zoznam možných vlastností faktúry:
- language string, nastaví jazyk faktúry.
- signature boolean, zobrazovat podpis.
- payment_info boolean, zobrazovať informáciu o úhrade.
- online_payment boolean, zobrazovat online platby.
- bysquare boolean, zobrazovat pay by square
- paypal boolean, zobrazovat PayPal
- callback_payment string, URL, která sa automaticky zavolá po přidání úhrady k faktuře. GET parametr
invoice_idbude přidán k URL. Pro odeslanou URLhttps://example.com/callback/, výsledná URL pro invoice_id 123 budehttps://example.com/callback/?invoice_id=123nebohttps://example.com/callback/?invoice_id=123&secret_key={KEY}. Parametrsecret_keymůže být součástí poslané URL (https://example.com/callback/?secret_key=SECRET-KEY) nebo být nastaven v profilu. - summary_bg_color string, barva souhrnu dokumentu. Tvar
#rrggbb, kderr,ggabbjsou hexadecimální hodnoty00-FF
rozšířené parametry faktury
- $extras array, povinné.
Zoznam možných parametrov:
- pickup_point_id int ID odběrného místa pro Zásilkovnu
- weight float, váha balíku,
- parcel_count int, počet balíků,
- insurance, float, hodnota pojištění,
- dimension, string, rozměr balíku v cm (d x š x v)
- tracking_number string, podací číslo
- uuid string, volitelný jednoznačný identifikátor faktury
- oss boolean, Zvláštní režim jednoho správního místa OSS
Vrátí detail pokladny včetne pohybů
(všeobecná REST API dokumentace)
- cash_register_id int ID pokladny
Odešle SMS.
(všeobecná REST API dokumentace)
- $data array, povinné.
Zoznam možných parametrov:
- $invoice_id int, povinné. ID faktury
- $text string, povinné Text SMS.
- $phone string, pokud není zadané tel. číslo použije se tel. číslo klienta z faktury
Nastaví hodnoty pro údaje dodavatele na faktuře
- $key mixed povinné. Může být string nebo pole. Pokud je string, nastaví se konkrétní hodnota v $data['MyData'][$key]. Pokud je pole, nastaví se více hodnot najednou.
- $value mixed nepovinné. Pokud je $key string, hodnota $value se nastaví v $data['MyData'][$key]. Pokud je $key pole, $value se ignoruje.
Příklad použití:
$api->setMyData('ic_dph', 'SK1234567890');$api->setMyData(array(
'company_name' => 'Testovacia firma',
'ic_dph' => 'SK1234567890',
'country_id' => '57'
));Seznam možných úprav v údajích dodavatele:
- country_id - ID země, číselník zemí je možné získat metodou getCountries
- company_name - Název společnosti
- dic - DIČ
- ic_dph - IČ DPH
- business_register - Zápis v obchodním rejstříku
- address - Adresa společnosti - ulice a číslo
- city - Adresa společnosti - město
- zip - Adresa společnosti - PSČ
- update_profile - Boolean hodnota. Pokud se pošle s hodnotou true, aktualizují se i údaje v profilu. Pokud se pošle s hodnotou false nebo nepošle vůbec, údaje se změní jen na faktuře, ale profilové údaje zůstanou nezměněny.
vrátí detaily faktur
(všeobecná REST API dokumentace)
- $ids array, limit 100
Příklad použití:
$api->getInvoiceDetails(array(1, 2, 3, 4, 5, 6, 7, 8));Vrátí údaje o firmě, do které jste momentálně přihlášen, případně o všech firmách, ke kterým má účet přístup.
(všeobecná REST API dokumentace)
- $getAllCompanies bool nepovinné. Pokud je parametr true, vrací údaje o všech firmách, ke kterým má účet přístup. Default je false - vrátí údaje pouze o firmě, ve které je účet momentálně přihlášen.
Příklad použití:
$api->getUserCompaniesData();
$api->getUserCompaniesData(true);vystaví ostrou fakturu ze zálohové faktury
- $proforma_id int povinné. Id zálohové faktury
Příklad použití:
$api->createRegularFromProforma(123);změní stav cenové nabídky
- $estimate_id int povinné. Id enové nabídky
- $status int povinné. Id stavu nabídky
Seznam možných stavů cenové nabídky:
- 1 => neschválena
- 2 => schválena
- 3 => zamítnuta
Vrátí seznam bankovních účtů.
(všeobecná REST API dokumentace)
$api->getBankAccounts();Přidá bankovní účet.
(všeobecná REST API dokumentace)
- $data array povinné. Údaje o bankovním účtu
Seznam možných vlastností bankovního účtu:
- bank_account - číslo účtu
- bank_code - čislo banky
- bank_name - název banky
- default - je účet přednastavený?
- iban - IBAN
- show - zobrazuj účet na dokumentech
- swift - SWIFT
$api->addBankAccount([
'iban' => 'CZ0000000123',
'swift' => 'ABCDE12',
'bank_name' => 'AbcBanka',
'default' => 1,
]);Uprav bankovní účet.
(všeobecná REST API dokumentace)
- $id int povinné. ID bankovního účtu
- $data array povinné. Údaje o bankovním účtu
Seznam možných vlastností bankovního účtu:
- bank_account - číslo účtu
- bank_code - čislo banky
- bank_name - název banky
- default - je účet přednastavený?
- iban - IBAN
- show - zobrazuj účet na dokumentech
- swift - SWIFT
$api->updateBankAccount(123, [
'bank_name' => 'Originálna Fiktívna Banka',
'default' => 0,
]);Smaže bankovní účet.
(všeobecná REST API dokumentace)
- $id int povinné. ID bankovního účtu
$api->deleteBankAccount(123);Přidá nový tag.
(všeobecná REST API dokumentace)
- $data array povinné. Údaje o tagu
Seznam možných vlastností tagu:
- name - název tagu
$api->addTag(['name' => 'nový tag',]);Upraví existující tag.
(všeobecná REST API dokumentace)
- $id int povinné. ID tagu
- $data array povinné. Údaje o tagu
Seznam možných vlastností tagu:
- name - název tagu
$api->editTag(123, ['name' => 'starý tag',]);Smaže tag.
(všeobecná REST API dokumentace)
- $id int povinné. ID tagu
$api->deleteTag(123);Vrátí detail klienta.
(všeobecná REST API dokumentace)
- $id int povinné. ID klienta
$api->client(123);Připojí související doklad k faktuře.
- $item_id int povinné. ID faktury
- $related_item_id int povinné. ID připojovaného dokumentu
- $related_item_type string povinné. Typ připojovaného dokument (invoice|expense)
$response = $api->addRelatedItemToInvoice(89, 76, 'invoice');Připojí související doklad k nákladu.
- $item_id int povinné. ID nákladu
- $related_item_id int povinné. ID připojovaného dokumentu
- $related_item_type string povinné. Typ připojovaného dokument (invoice|expense)
$response = $api->addRelatedItemToExpense(32, 89, 'invoice');Odstraní související doklad z faktury.
- $connection_id int povinné. ID faktury
$response = $api->deleteRelatedItemFromInvoice(100);Odstraní související doklad z nákladu.
- $connection_id int povinné. ID nákladu
$response = $api->deleteRelatedItemFromExpense(102);Pro přihlášení se do API je potřebný e-mail, na který je účet zaregistrovaný a API Token, který je možné nalézt v Nástroje > API. Samotná autorizace se vykonáva pomocí hlavičky "Authorization", která má nasledující tvar:
"Authorization: SFAPI email=EMAIL&apikey=APITOKEN&company_id=COMPANYID"company_id je nepovinný údaj, uvádí se pouze v případě, že máte pod vaším emailů vytvořených více společností a potřebujete určit, se kterou chcete pracovat
Tuto hlavičku musí obsahovat každý request na SF API!
Pokud se Vám nelíbí náš SF API klient a chcete si faktury vystavovat po svém: Endpoint pro vystavání faktury se nachází na adrese https://moje.superfaktura.cz/invoices/create Data pro vystavení faktury jsou očekávána ve formátu JSON v $POST['data'] v nasledující formě:
$data = array(
'Invoice' => array( //všechny položky jsou nepovinné, v připadě že nejsou uvedené, budu doplněné automaticky
'name' => 'název faktury',
'variable' => '123456',
'constant' => '0308',
'specific' => '2015',
//specifický symbol
'already_paid' => true, // byla už faktura uhrazena?
'invoice_no_formatted' => '2015001', //pokud není uvedené, SF ho doplní podle číselníku
'created' => '2015-12-28', //datum vystavení
'delivery' => '2015-12-28', //datum dodaní
'due' => '2015-12-28', //datum splatnosti
'comment' => 'komentář',
),
'Client' => array(
'name' => 'Tomáš Janák',
'ico' => '12345678',
'dic' => '12345678',
'ic_dph' => 'CZ12345678',
'email' => '[email protected]',
'address' => 'adresa',
'city' => 'město',
'zip' => 'psč',
'phone' => 'telefon',
),
'InvoiceItem' => array( array(
'name' => 'Superfaktura.cz',
'description' => 'Předplatné',
'quantity' => 1,
'unit' => 'ks',
'unit_price' => 150.83,
'tax' => 21
),
array(
'name' => 'Druhá položka',
'description' => '',
'quantity' => 10,
'unit' => 'ks',
'unit_price' => 5,
'tax' => 15
)
) );
// Samotný request s použitím např. Requests knihovna potom může vypadat následovně:
Requests::register_autoloader();
$response = Requests::post('https://moje.superfaktura.cz/invoices/create',
$headers,
array('data' => json_encode($data))
);
$response_data = json_decode($response->body, true);
// výsledkem tohto volání je JSON odpověď v nasledující formě
$response_data = array(
'error' => 0,
'error_message' => 'Chybová hláška',
'data' => array(),
);V případě, pokud došlo k chybě, bude error = 1 a error_message bude obsahovat popis chyby, která nastala. V případě, že chyb nastalo více, bude error_message obsahovat pole s chybovými hláškami.
Pokud byla faktura úspešně vytvořená, bude v klíči data uložené kompletní informace o vytvořené faktuře.
Po vytvoření faktury je možné stáhnut její PDF na adrese
https://moje.superfaktura.cz/invoices/pdf/ID_FAKTURY/token:TOKENkde ID FAKTURY se nachází v $data['Invoice']['id'] a token v $data['Invoice']['token'].
Pro správné zaevidování platby do EET je potřebné mít vytvořenou EET pokladnu s platným certifikátem a odpovídajícím ID provozovny. Pohyb můžeme zaevidovat dvěma způsoby, při obou je nutné znát ID EET pokladny vytvořené v SuperFaktuře.
- Při vytváření faktury je nutné do setInvoice nastavit already_paid (což rozhoduje o tom, zda se faktura vystaví jako uhrazená, nebo neuhrazená) na true, dále je nutné nastavit cash_register_id (ID EET pokladny) s odpovídající měnou faktury
$api->setInvoice(array(
'type' => "regular",
'already_paid' => true,
'cash_register_id' => 879
));- Pomocí funkce payInvoice (měna úhrady a EET pokladny musí být shodná)
$api->payInvoice(1459738, null, 'CZK', null, 'transfer', 879);V případě, že volání vystavení faktury nevrátilo response - vypadl internet, nepřišla odpověď do timeoutu a pod. - je možné dodatečně zjistit response pro toto volání a zamezit tak např. duplicitnímu vystavení faktury.
K faktuře je možné získat unikátní identifikátor (ne invoice id).
Vzhledem k tomu, že jde o checksum, doporučujeme v datech faktury uvádět jedinečný údaj ke každé objednávce (např. číslo objednávky).
Postup:
- standardní vystavení faktury
$api->save()$checksum = $api->getChecksum()- vybuchly internety a nemáme odpověď do timeoutu
$response = $api->getResponseByChecksum($checksum)
$response obsahuje původní response faktury, který jste poprvé nedostali.
Response je možné získat pro volání staré maximálně 3 měsíce.
Samozřejmě volání getResponseByChecksum je nutné také zkontrolovat pro případnou chybovou odpověď.