Faktero API pre vývojárov

Faktero API je REST rozhranie, ktoré umožňuje vašej aplikácii vytvárať faktúry, spravovať odberateľov a počúvať na udalosti cez webhooky.

Všetky endpointy bežia pod https://www.faktero.sk/api/v1 a používajú JSON.

1. Otvorte Nastavenia → API kľúče.
2. Kliknite na Vytvoriť nový kľúč a pomenujte ho (napr. „Eshop produkcia“).
3. Kľúč sa zobrazí iba raz — uložte ho na bezpečnom mieste.

Kľúč posielajte v hlavičke Authorization: Bearer fk_live_….

Viac firiem jedným kľúčom: v API kľúčoch zvoľte Kľúč pre viac firiem. Platí pre všetky firmy, kde ste vlastník alebo admin (alebo len pre vybrané) — firmu potom uvádzate v každej požiadavke hlavičkou X-Company (id alebo IČO). Zoznam firiem vráti GET /api/v1/companies.

Pri vytváraní kľúča vyberáte režim:

• Test — kľúč smie len čítať (zoznamy, detaily, PDF). Na skúšanie integrácie bez rizika, že niečo vystaví alebo odošle zákazníkovi. Pokus o zápis vráti chybu 403 test_key_read_only.
• Live (produkcia) — číta aj zapisuje: reálne faktúry, ktoré sa rátajú do mesačného limitu plánu.

Test kľúče majú prefix fk_test_, live kľúče fk_live_. Zneplatnený kľúč ostáva v zozname so zneplatnením, aby bolo v denníku volaní vidno, čím čo prišlo.

Príklad cURL volania:

curl -X POST https://www.faktero.sk/api/v1/invoices \
  -H "Authorization: Bearer fk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "ACME s.r.o.", "ico": "12345678" },
    "items": [
      { "name": "Konzultácia", "quantity": 2, "unit_price": 50, "vat_rate": 23 }
    ],
    "due_date": "2026-07-01"
  }'

Odpoveď obsahuje id, invoice_number a URL na PDF.

Webhooky pošlú HTTP POST na vašu URL, keď nastane udalosť:

• invoice.created
• invoice.sent
• invoice.paid
• invoice.cancelled
• bank_transaction.created

invoice.paid príde pri každej zmene faktúry na uhradenú — aj po spárovaní s bankovým pohybom. Udalosť bank_transaction.created oznámi každý nový pohyb na účte, takže pohyby netreba dopytovať.

Každý webhook je podpísaný hlavičkou X-Faktero-Signature (HMAC SHA-256 z tela správy a tajného kľúča webhooku). Vždy podpis overte pred spracovaním.

Na WooCommerce netreba nič programovať — hotový doplnok vystavuje faktúry z objednávok sám. Návod a stiahnutie: Faktúry z e-shopu na WooCommerce.

API nielen číta, ale aj zapisuje — hodí sa pri prechode z iného programu aj pri trvalom napojení e-shopu, skladu či účtovnej kancelárie:

• Prijaté faktúry a bločky — zapíšete ich aj so súborom (PDF, fotka), dodávateľ sa sám založí v adresári. Úhrady (aj po častiach), zaúčtovanie, stav, štítky a komentár doplníte neskôr.
• Adresár — naraz prenesiete až 1000 odberateľov a dodávateľov. Existujúci kontakt sa nezdvojí, len sa doplní.
• Cenník — produkty a služby, ktoré sa dajú synchronizovať napríklad z e-shopu.
• Bankové účty — účet banky, ku ktorej sa Faktero nepripojí, založíte cez API a pohyby naň posielate dávkami. Duplicity sa preskočia. Poplatok, mzdu či transakčnú daň označíte ako vybavené bez dokladu.
• Firmy a používatelia — kľúčom pre viac firiem založíte firmu nového klienta a pozvete do nej účtovníka či kolegu (pozvánka príde e-mailom).

Pri každom zápise môžete poslať vlastné external_id — opakované odoslanie potom nič nezdvojí. Cez API sa maže len ručne pridaná úhrada prijatej faktúry; faktúra sa dá len stornovať. Presný tvar údajov je v API dokumentácii.

Faktero sa dá napojiť na AI asistenta cez MCP (Model Context Protocol). Asistent potom odpovie, kto vám dlhuje, nájde faktúru, vystaví novú, zapíše prijatú faktúru či bloček, založí odberateľa, produkt alebo firmu, prenesie kontakty a bankové pohyby, označí úhradu (aj čiastočnú), nastaví stav, štítky či zaúčtovanie dokladu, vybaví bankový pohyb bez dokladu, pozve kolegu alebo pozrie pohyby na účte. Zmaže nanajvýš ručne pridanú úhradu prijatej faktúry a nič neposiela odberateľom.

1. V claude.ai otvorte Nastavenia → Konektory, v ChatGPT Nastavenia → Aplikácie a konektory a pridajte vlastný konektor.
2. Ako adresu zadajte https://www.faktero.sk/api/mcp. Kľúč netreba.
3. Otvorí sa Faktero — prihláste sa, vyberte firmu (alebo Všetky moje firmy) a kliknite na Povoliť prístup. Povoliť ho môže majiteľ alebo admin firmy.

Pri voľbe Všetky moje firmy sa asistent pri otázke spýta, o ktorú firmu ide. Prístup uvidíte v API kľúčoch ako „AI asistent (MCP)“ a zrušíte ho tam jedným klikom. Pri neznámej aplikácii Faktero pred povolením upozorní — povoľte len to, čo ste pridávali vy.

Claude Code, Cursor či iní klienti sa pripoja s API kľúčom v hlavičke Authorization: Bearer fk_live_… — návod je v dokumentácii API.

Úplný zoznam endpointov, parametrov a chybových kódov nájdete v API dokumentácii. Tlačidlom Stiahnuť PDF si ju stiahnete celú (v slovenčine, češtine alebo nemčine podľa jazyka webu), tlačidlom Tlačiť ju vytlačíte.

Volania si viete vyskúšať bez písania kódu v API playgrounde — vyberiete endpoint, doplníte parametre a hneď vidíte odpoveď servera aj hotový príkaz pre curl. Playground volá ostré dáta vašej firmy, takže zápisové volania naozaj vytvárajú doklady.