Faktero API dokumentácia

Úvod

Faktero REST API umožňuje plne automatizovať fakturáciu — vytvárať odberateľov, vystavovať faktúry, sťahovať PDF, posielať e-maily a prijímať webhooky o udalostiach. Všetky odpovede sú v JSON formáte (UTF-8).

Autentifikácia

Každú požiadavku autentifikujte hlavičkou Authorization s Bearer API kľúčom. Kľúče sú viazané na konkrétnu firmu a oprávnenia.

Authorization: Bearer fk_live_xxxxxxxxxxxxxxxxxxxxxxxx

Kľúč nikdy nezdieľajte ani neukladajte do verejných repozitárov. Stratený kľúč okamžite revokujte v sekcii API kľúče.

Kľúč pre viac firiem

Účtovná kancelária či integrátor nepotrebuje kľúč za každú firmu. Kľúč pre viac firiem (API kľúče → Kľúč pre viac firiem) platí pre všetky firmy, kde ste vlastník alebo admin, alebo len pre vybrané. Firmu vyberiete v každej požiadavke hlavičkou X-Company (id firmy alebo IČO) alebo parametrom ?company=. Bez nej vráti API chybu company_required so zoznamom firiem — okrem kľúča, ktorý smie len k jednej firme.

# Firmy, ku ktorým kľúč smie
curl https://faktero.sk/api/v1/companies \
  -H "Authorization: Bearer fk_live_..."

# Faktúry konkrétnej firmy (podľa IČO)
curl https://faktero.sk/api/v1/invoices \
  -H "Authorization: Bearer fk_live_..." \
  -H "X-Company: 12345678"

• GET/api/v1/companies— Firmy, ku ktorým kľúč smie (id, názov, IČO)

Testovací a ostrý režim

Faktero rozlišuje dva typy kľúčov podľa prefixu:

• fk_test_… — testovací režim — kľúč smie len čítať (GET). Zápis, odoslanie či úhrada vráti 403 s kódom test_key_read_only, takže skúšanie integrácie nič nezmení.
• fk_live_… — produkčný režim. Akcie sú reálne a fakturačné údaje sa zapisujú do ostrých dokumentov.

Chyby

Všetky chybové odpovede majú jednotný formát:

{
  "error": {
    "code": "validation_error",
    "message": "Human readable message",
    "details": {}
  }
}

Stavové kódy

Limity požiadaviek

Odberatelia

• POST/api/v1/customers— Vytvorenie odberateľa
• GET/api/v1/customers— Zoznam odberateľov
• GET/api/v1/customers/{id}— Detail odberateľa
• PUT/api/v1/customers/{id}— Úprava odberateľa
• POST/api/v1/customers/import— Hromadný prenos adresára (do 1000)

Hromadný prenos adresára

Prenesie odberateľov aj dodávateľov z iného programu naraz. Páruje podľa external_id, potom IČO, bez IČO podľa mena. Existujúci kontakt sa len doplní o prázdne polia; s update_existing: true sa prepíše. Odpoveď povie, čo sa založilo, doplnilo alebo ostalo bez zmeny, a chyby po riadkoch.

POST /api/v1/customers/import
{
  "update_existing": false,
  "contacts": [
    { "name": "Odberateľ s.r.o.", "ico": "12345678", "email": "fakturacia@odberatel.sk" },
    { "name": "Dodávateľ a.s.", "ico": "87654321", "supplier": true, "customer": false,
      "iban": "SK31 1200 0000 1987 4263 7541" }
  ]
}

Faktúry

• POST/api/v1/invoices— Vystavenie faktúry
• GET/api/v1/invoices— Zoznam faktúr
• GET/api/v1/invoices/{id}— Detail faktúry
• PUT/api/v1/invoices/{id}— Úprava: poznámka, splatnosť, VS, úhrada, dodací list, pečiatka, zaúčtovanie, stav a štítky
• GET/api/v1/invoices/{id}/pdf— Dočasný podpísaný odkaz na PDF
• POST/api/v1/invoices/{id}/send— Odoslanie e-mailom
• POST/api/v1/invoices/{id}/mark-paid— Označenie ako uhradené
• POST/api/v1/invoices/{id}/cancel— Storno faktúry

Vystavenie faktúry

Odberateľa pošlite ako customer_id z adresára alebo ako objekt customer (name, ico, dic, ic_dph, street, city, zip, country, email). Položka má name, quantity, unit, unit_price (bez DPH), vat_rate a voliteľne discount_percent (zľava riadku v %) a prenesenie (prenesenie daňovej povinnosti len pri tejto položke). Bez vat_rate platí základná sadzba krajiny firmy (neplatiteľ DPH 0 %), bez currency mena firmy. S external_id sa tá istá faktúra druhýkrát nevystaví — opakovaná požiadavka vráti existujúcu (200).

• discount_type (percent, amount) a discount_value — zľava na celý doklad; rozpočíta sa pomerne medzi sadzby DPH a v odpovedi je discount_total.
• reverse_charge: true a reverse_charge_type (domestic_69, eu_b2b, export) — prenesenie daňovej povinnosti; DPH faktúry je nula a PDF uvedie zákonnú vetu. Pri eu_b2b musí mať odberateľ IČ DPH z iného členského štátu (eu_plnenie: tovar, sluzba, trojstranny).
• currency — v cudzej mene Faktero doplní kurz (slovenská firma ECB zo dňa pred dodaním, česká ČNB) a sumy v domácej mene: exchange_rate, exchange_rate_date, vat_total_eur.
• subtotal, vat_amount pri položke — presné sumy z e-shopu (pri všetkých položkách alebo pri žiadnej). Musia sedieť s cenou a sadzbou, inak 400; so zľavou sa nekombinujú.
• order_number, variable_symbol, delivery_date, due_date (predvolene o 14 dní), payment_method, notes.

POST /api/v1/invoices
{
  "external_id": "eshop-10042",
  "customer": { "name": "Stavby s.r.o.", "ico": "12345678", "ic_dph": "SK2020123456" },
  "reverse_charge": true,
  "reverse_charge_type": "domestic_69",
  "discount_type": "percent",
  "discount_value": 5,
  "items": [
    { "name": "Montáž", "quantity": 10, "unit": "hod", "unit_price": 40, "vat_rate": 23,
      "discount_percent": 10 }
  ]
}

GET /invoices vráti najviac 200 faktúr (limit, offset, status) a has_more s next_offset. GET /invoices/{id}/pdf vráti url (podpísaný odkaz na PDF) a expires_in v sekundách — odkaz platí hodinu.

Dodací list, pečiatka a zaúčtovanie

Pri vystavení (POST) aj úprave (PUT) môžete poslať dodaci_list: true (faktúra slúži zároveň ako dodací list — iný nadpis a podpisy odovzdania a prevzatia v PDF), zobrazit_peciatku (true alebo false; bez neho podľa nastavenia firmy) a accounting { predkontacia, clenenie_dph, kv_clenenie, stredisko, cinnost, booked }. V odpovedi sú ako pohoda_predkontacia, pohoda_clenenie_dph a kv_clenenie. Faktúra prijíma aj stav, štítky, komentár a účtovnú poznámku (pozri Prijaté doklady a banka). Na faktúre odovzdanej do účtovníctva sa účtovné údaje, sumy ani dátumy nezmenia — API vráti 409 s kódom locked a v details sú dotknuté polia.

PUT /api/v1/invoices/{id}
{
  "dodaci_list": true,
  "zobrazit_peciatku": false,
  "accounting": { "predkontacia": "1Fv", "clenenie_dph": "UD", "kv_clenenie": "A1" },
  "stav": "Skontrolovať",
  "stitky_pridat": "Zákazka Novák",
  "komentar": "Overiť dodanie s Petrom"
}

Cenové ponuky

• POST/api/v1/quotes— Vytvorenie ponuky
• GET/api/v1/quotes— Zoznam ponúk
• GET/api/v1/quotes/{id}— Detail ponuky
• POST/api/v1/quotes/{id}/convert— Konverzia na faktúru

Ponuka prijíma rovnakého odberateľa a položky ako faktúra (bez vat_rate platí sadzba firmy, bez currency mena firmy). Konverzia vystaví faktúru s dnešným dátumom; opakovaná konverzia vráti tú istú faktúru.

Opakované faktúry

• POST/api/v1/recurring-invoices— Vytvorenie šablóny
• GET/api/v1/recurring-invoices— Zoznam šablón
• GET/api/v1/recurring-invoices/{id}— Detail šablóny
• PUT/api/v1/recurring-invoices/{id}— Úprava šablóny

Prijaté doklady a banka

Pre účtovný program alebo kanceláriu: prijaté faktúry a bločky so zaúčtovaním (predkontácia, členenie DPH, KV), zmeny od posledného stiahnutia a označenie odovzdaných — rovnako ako to robí konektor Pohody.

• GET/api/v1/purchase-invoices— Prijaté faktúry
• POST/api/v1/purchase-invoices— Zapísať prijatú faktúru (aj so súborom)
• PUT/api/v1/purchase-invoices/{id}— Úprava, úhrada (payment_date), zaúčtovanie
• GET/api/v1/purchase-invoices/{id}— Detail s položkami a odkazom na súbor (1 h)
• POST/api/v1/purchase-invoices/{id}/exported— Označiť ako odovzdanú
• GET/api/v1/purchase-invoices/{id}/payments— Úhrady prijatej faktúry a koľko zostáva uhradiť
• POST/api/v1/purchase-invoices/{id}/payments— Pridať úhradu (aj čiastočnú)
• DELETE/api/v1/purchase-invoices/{id}/payments/{paymentId}— Zmazať ručne pridanú úhradu
• GET/api/v1/receipts— Bločky
• POST/api/v1/receipts— Zapísať bloček
• PUT/api/v1/receipts/{id}— Úprava bločku
• GET/api/v1/receipts/{id}— Detail bločku s odkazom na súbor
• POST/api/v1/receipts/{id}/exported— Označiť ako odovzdaný
• POST/api/v1/unprocessed-documents— Nahrať doklad do Nespracovaných
• GET/api/v1/unprocessed-documents— Nespracované doklady a stav čítania
• GET/api/v1/bank-accounts— Bankové účty firmy (IBAN, banka, zostatok)
• GET/api/v1/bank-transactions— Pohyby na bankových účtoch
• POST/api/v1/bank-transactions/{id}/resolution— Vybaviť pohyb bez dokladu (aj transakčná daň)
• GET/api/v1/document-states— Vlastné stavy dokladov
• GET/api/v1/tags— Číselník štítkov
• GET/api/v1/accounting-codes— Predkontácie, členenia DPH, strediská, činnosti a číselné rady
• GET/api/v1/accounting-templates— Predlohy zaúčtovania
• POST/api/v1/bank-accounts— Pridať účet bez napojenia na banku
• POST/api/v1/bank-accounts/{id}/transactions— Preniesť pohyby na taký účet (do 2000)

Zápis prijatej faktúry

Sumy pošlite buď ako položky (ceny bez DPH, sadzba v %), alebo ako amount_total (+ amount_without_vat a vat_amount). Dodávateľ sa založí v adresári, ak tam nie je. S external_id je opakované volanie bezpečné; bez neho sa tá istá faktúra (IČO + číslo + suma) druhýkrát nezaloží (409). Súbor (PDF, JPG, PNG) ide ako base64 do 14 MB. Bez accounting.booked príde faktúra nezaúčtovaná.

POST /api/v1/purchase-invoices
{
  "external_id": "erp-2026-0042",
  "invoice_number": "FV2026118",
  "supplier": { "name": "Dodávateľ s.r.o.", "ico": "12345678",
                "ic_dph": "SK2020123456", "iban": "SK3112000000198742637541" },
  "issue_date": "2026-10-20",
  "delivery_date": "2026-10-20",
  "due_date": "2026-11-03",
  "variable_symbol": "2026118",
  "payment_method": "prevod",
  "items": [{ "name": "Servis", "quantity": 2, "unit_price": 50, "vat_rate": 23 }],
  "accounting": { "predkontacia": "1Fp", "clenenie_dph": "PD", "booked": false },
  "file": { "file_name": "FV2026118.pdf", "content_type": "application/pdf",
            "content_base64": "JVBERi0xLjQK..." }
}

Voliteľné pole buyer { name, ico, dic, ic_dph } je odberateľ uvedený na doklade. Keď nesedí s firmou kľúča (iné IČO, IČ DPH alebo názov), faktúra sa zapíše s príznakom odberatel_nesedi a nezaúčtuje sa ani s accounting.booked. Kým vo Fakteri nepotvrdíte, že patrí tejto firme, zaúčtovanie cez PUT vráti 409 s kódom buyer_mismatch.

PUT /api/v1/purchase-invoices/{id}
{ "accounting": { "booked": true } }

409 Conflict
{ "error": { "code": "buyer_mismatch",
             "message": "Faktúra nepatrí firme …, odberateľ je … Kým vo Fakteri nepotvrdíte, že faktúra patrí tejto firme, nedá sa zaúčtovať." } }

Úhradu zapíšete cez PUT s payment_date. Bloček: issue_date, total_amount (s DPH), vat_breakdown [{ rate, base, vat }] a payment_method (hotovost, karta, prevod) — hotovosť sa započíta do pokladne, ak nepošlete cash_register: false.

Úhrady prijatých faktúr

Prijatá faktúra môže mať viac úhrad, aj čiastočných. POST …/payments prijme amount (v mene faktúry), paid_at (RRRR-MM-DD, predvolene dnes), method (prevod, hotovost, karta) a note; s external_id je opakovanie bezpečné. Keď súčet úhrad dosiahne sumu na úhradu (celková suma mínus zaplatená zálohová faktúra), faktúra je uhradená — stav a payment_date prepočíta Faktero samo. GET vráti úhrady a súhrn amount_due, amount_paid, amount_remaining a payment_status (paid, partially_paid, unpaid). Úhradu zo spárovaného bankového pohybu (source: bank) cez API zmazať nejde (409 bank_payment). Úhrady nezamyká odovzdanie do účtovníctva ani uzávierka.

POST /api/v1/purchase-invoices/{id}/payments
{ "amount": 50.00, "paid_at": "2026-10-28", "method": "prevod",
  "external_id": "erp-uhrada-881" }

201 Created
{
  "objekt": "purchase_invoice_payment",
  "id": "2f0c…", "amount": 50, "currency": "EUR", "paid_at": "2026-10-28",
  "source": "manual", "deletable": true,
  "invoice": { "amount_due": 123, "amount_paid": 50, "amount_remaining": 73,
               "payment_status": "partially_paid" }
}

Stav, štítky, komentár a účtovná poznámka

Prijaté faktúry, bločky aj vystavené faktúry prijímajú pri zápise (POST) aj úprave (PUT): stav_id alebo stav (názov z GET /document-states; null stav zruší), stitky (nahradia celý zoznam, najviac 5) alebo stitky_pridat a stitky_odobrat (jeden štítok), komentar (pre ľudí vo firme, do účtovníctva nejde nikdy) a int_poznamka (účtovná poznámka, ide s dokladom do účtovníctva). Nový štítok sa zapíše aj do číselníka firmy (GET /tags). Stav, štítky a komentár sa menia aj na doklade odovzdanom do účtovníctva; účtovné údaje vrátane účtovnej poznámky nie — API vráti 409 locked, kým doklad nevrátite (exported: false).

PUT /api/v1/receipts/{id}
{ "stav": "Čaká na doklad od klienta", "stitky": ["Auto", "Služobná cesta"],
  "komentar": "Chýba druhá strana bločku" }

409 Conflict
{ "error": { "code": "locked", "message": "Doklad je odovzdaný do účtovníctva — …",
             "details": { "reason": "odovzdany", "fields": ["pohoda_predkontacia"] } } }

Číselníky zaúčtovania

GET /accounting-codes vráti číselník firmy (napr. prenesený z Pohody): druh, kod, popis, ucet_md, ucet_d, typ_dokladu a typ_platby. Filter kind (predkontacia, clenenie_dph, stredisko, cinnost, ciselny_rad); document_type (faktura, blocek) a payment_type (hotovost, karta, prevod) vrátia kódy pre daný typ aj tie, ktoré typ neurčujú; active=all vráti aj vypnuté. GET /accounting-templates vráti predlohy zaúčtovania (document_kind: blocek, prijata, vystavena). Kód z číselníka pošlite v accounting.predkontacia.

Pohyby bez dokladu

Nie každý pohyb má doklad — poplatok banky, mzda, odvod či transakčná daň. Každý pohyb nesie stav (sparovany, bez_dokladu, transakcna_dan, nesparovany) a vybavenie, vybavenie_poznamka a vybavene_at; filter state=nesparovany vráti len to, čo treba ešte vyriešiť. POST /bank-transactions/{id}/resolution s resolution bez_dokladu alebo transakcna_dan (a note do 200 znakov) pohyb vybaví, resolution: null označenie zruší. Spárovaný pohyb sa označiť nedá (409 already_matched). Transakčnú daň Faktero väčšinou spozná samo podľa popisu banky.

POST /api/v1/bank-transactions/{id}/resolution
{ "resolution": "bez_dokladu", "note": "Poplatok za vedenie účtu" }

Prenos bankového účtu

Pre banku, ku ktorej sa Faktero nepripojí, alebo pri prechode z iného programu: POST /bank-accounts založí účet (IBAN, mena, zostatok) a pohyby naň pošlete dávkou. Každý pohyb má mať reference (jedinečné id z banky); bez neho ho Faktero odvodí z dátumu, sumy a symbolov, takže opakované odoslanie nič nezdvojí. Na účet napojený priamo na banku pohyby cez API poslať nejde — vedie ich banka.

POST /api/v1/bank-accounts/{id}/transactions
{
  "transactions": [
    { "booking_date": "2026-10-22", "amount": 123.00, "variable_symbol": "2026001",
      "counterparty": "Odberateľ s.r.o.", "reference": "TX-88123" },
    { "booking_date": "2026-10-22", "amount": -12.30, "description": "Kancelárske potreby",
      "reference": "TX-88124" }
  ],
  "balance": 1098.40
}

Filtre zoznamu

• updated_since — len zmenené od (ISO 8601); zoznam je zoradený podľa updated_at, takže sa dá pokračovať od posledného.
• issued_from, issued_to — dátum vystavenia (RRRR-MM-DD).
• exported=false — ešte neodovzdané; booked=true — len zaúčtované (prijaté faktúry).
• stav_id (id stavu alebo none) a tag — len doklady s daným stavom alebo štítkom.
• limit (najviac 200) a offset; odpoveď má has_more a next_offset.
• Banka: date_from, date_to, bank_account_id, state; page + per_page (alebo offset + limit), najviac 500 na stranu. Odpoveď má total, has_more a next_offset — čítajte, kým je has_more true, inak vám riadky z rušného dňa chýbajú.

Bankové účty

id účtu je presne to bank_account_id, ktoré nesú pohyby. Vracajú sa aj odpojené účty (active: false), aby sa dalo priradiť každé id zo starších pohybov. Zostatok a jeho čas sú null, kým sa účet s bankou nesynchronizoval. Každý pohyb nesie aj iban a bank_name svojho účtu.

GET /api/v1/bank-accounts
{
  "data": [
    {
      "id": "7c9a8242-5b05-4ab6-bc25-f543cf62079b",
      "name": "Tatra banka — predaj",
      "iban": "SK1211000000002612345678",
      "bank_name": "Tatra banka, a.s.",
      "currency": "EUR",
      "active": true,
      "balance": 1234.56,
      "balance_at": "2026-10-24T18:00:00Z"
    }
  ]
}

Neznáma cesta pod /api/v1/ vráti 404 s telom {"error":{"code":"not_found",…}}.

Označenie odovzdaného

curl -X POST https://faktero.sk/api/v1/purchase-invoices/{id}/exported \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "exported": true, "accounting_number": "FP2026/0154" }'

"exported": false označenie zruší (doklad sa dá znova upraviť).

Nahratie dokladu

curl -X POST https://faktero.sk/api/v1/unprocessed-documents \
  -H "Authorization: Bearer fk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "faktura.pdf", "content_type": "application/pdf",
        "content_base64": "JVBERi0xLjQK...", "note": "zákazka Novák" }'

PDF, JPEG, PNG, WEBP, HEIC alebo XML do 14 MB. Doklad sa prečíta na pozadí (desiatky sekúnd) a čaká v Nespracovaných na kontrolu; stav (cita, vytazene, chyba) vráti GET.

Cenník

• GET/api/v1/products— Produkty a služby (q = hľadanie)
• POST/api/v1/products— Pridať do cenníka
• GET/api/v1/products/{id}— Detail produktu
• PUT/api/v1/products/{id}— Úprava produktu

Cena je bez DPH. S external_id sa ten istý produkt druhýkrát nezaloží — vhodné na synchronizáciu z e-shopu či skladového programu.

Firmy a používatelia

• GET/api/v1/companies— Firmy, ku ktorým kľúč smie
• POST/api/v1/companies— Založiť firmu (kľúč účtu)
• GET/api/v1/companies/{id}— Detail firmy
• PUT/api/v1/companies/{id}— Úprava údajov firmy
• GET/api/v1/companies/{id}/members— Používatelia a čakajúce pozvánky
• POST/api/v1/companies/{id}/invitations— Pozvať používateľa (kľúč účtu)

Pre účtovné kancelárie a integrátorov: kľúčom pre viac firiem založíte firmu nového klienta (stanete sa jej vlastníkom a kľúč k nej hneď smie) a pozvete do nej používateľov — účtovníka (accountant), admina alebo zamestnanca. Pozvánka príde e-mailom a platí 14 dní; v odpovedi je aj odkaz na prijatie. Firmu zakladať a pozývať smie len kľúč pre viac firiem, ktorého majiteľ je vo firme vlastník alebo admin — obyčajný firemný kľúč nie.

# Nová firma klienta
curl -X POST https://faktero.sk/api/v1/companies \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"name":"Klient s.r.o.","ico":"12345678","country":"SK","vat_payer":true}'

# Pozvánka pre účtovníčku
curl -X POST https://faktero.sk/api/v1/companies/{id}/invitations \
  -H "Authorization: Bearer fk_live_..." -H "Content-Type: application/json" \
  -d '{"email":"uctovnicka@kancelaria.sk","role":"accountant"}'

Webhooky

Webhooky vás v reálnom čase informujú o udalostiach vo Faktero. Endpoint nastavíte v sekcii Webhooky vo vašom účte, kde získate aj signing secret.

Udalosti

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

Kedy príde invoice.paid

Pri každej zmene faktúry na uhradenú — po spárovaní s bankovým pohybom (automaticky aj ručne), po hromadnom označení v zozname, cez POST /api/v1/invoices/…/mark-paid aj zmenou stavu v detaile faktúry. Pri mark-paid príde hneď, inak do minúty. Ak úhradu priniesla banka, payload má bank_transaction_id spárovaného pohybu.

{
  "event": "invoice.paid",
  "created_at": "2026-10-24T18:01:12Z",
  "data": {
    "invoice_id": "8958a73f-…",
    "invoice_number": "20260042",
    "status": "paid",
    "total": 370.04,
    "currency": "EUR",
    "external_id": "eshop-10042",
    "customer_id": "40f865bf-…",
    "customer_name": "Odberateľ s.r.o.",
    "customer_email": "fakturacia@odberatel.sk",
    "paid_at": "2026-10-24T18:00:58Z",
    "bank_transaction_id": null
  }
}

Ostatné udalosti faktúry (invoice.created, invoice.sent, invoice.cancelled) majú rovnaké data bez paid_at a bank_transaction_id; customer.created nesie customer_id, name, email, ico a external_id.

bank_transaction.created

Príde do minúty po tom, čo sa pohyb objaví vo Fakteri (synchronizácia s bankou, import výpisu, bankové notifikácie). Data majú rovnaký tvar ako položka z GET /api/v1/bank-transactions vrátane iban a bank_name, takže pohyby netreba dopytovať. Pri prvom pripojení banky príde udalosť za každý natiahnutý pohyb.

{
  "event": "bank_transaction.created",
  "created_at": "2026-10-24T18:01:12Z",
  "data": {
    "id": "0b6f…",
    "bank_account_id": "7c9a8242-5b05-4ab6-bc25-f543cf62079b",
    "iban": "SK1211000000002612345678",
    "bank_name": "Tatra banka, a.s.",
    "booking_date": "2026-10-24",
    "amount": 1230.00,
    "currency": "EUR",
    "variable_symbol": "20260042",
    "counterparty": "Odberateľ s.r.o.",
    "matched_invoice_id": null
  }
}

Overovanie podpisu

Každá požiadavka má hlavičku X-Faktero-Signature obsahujúcu HMAC SHA-256 podpis tela požiadavky vytvorený pomocou vášho signing secret. Názov udalosti nesie aj hlavička X-Faktero-Event.

import crypto from "crypto";

function verifyFaktero(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Opakovanie pri zlyhaní

Ak váš endpoint nevráti 2xx do 10 sekúnd, Faktero doručenie hneď zopakuje — celkovo 3 pokusy počas niekoľkých sekúnd. Neskôr sa už neposiela, preto pri výpadku dočítajte zmeny cez API (napr. updated_since alebo GET /bank-transactions). Všetky pokusy a ich stavy nájdete v sekcii Webhooky → Logy. Adresa musí byť https na verejnom serveri (port 443).

AI asistenti (MCP)

Faktero má MCP server — cez Model Context Protocol sa naň napojí Claude, ChatGPT, Cursor či iný AI asistent a pracuje s údajmi vašej firmy: povie, kto vám dlhuje, nájde faktúru, vystaví novú alebo pozrie pohyby na účte. Claude.ai a ChatGPT sa prihlásia cez Faktero, ostatní klienti API kľúčom.

• Adresa: https://www.faktero.sk/api/mcp (Streamable HTTP)
• Hlavička: Authorization: Bearer fk_live_… — na skúšanie použite testovací kľúč.
• Nástroje: faktúry a ich detail, faktúry po splatnosti, vystavenie faktúry, označenie úhrady, odberatelia aj ich hromadný prenos, cenové ponuky, cenník, prijaté faktúry a bločky (aj ich zápis, úhrady po častiach, stav, štítky a zaúčtovanie), predkontácie a predlohy zaúčtovania, bankové účty a pohyby (aj prenos na účet bez napojenia a vybavenie pohybu bez dokladu), založenie firmy, používatelia a pozvánky.
• Asistent zmaže nanajvýš ručne pridanú úhradu prijatej faktúry (nástroj je označený ako deštruktívny) a nič neposiela odberateľom — faktúru vystaví, ale odoslanie e-mailom či ako eFaktúru je na vás. Jediný e-mail, ktorý odíde, je pozvánka používateľa, keď o ňu výslovne požiadate. Zapisujúce nástroje sú označené, aby si ich klient dal potvrdiť.

Claude.ai a ChatGPT

Pridajte vlastný konektor (v Claude: Nastavenia → Konektory, v ChatGPT: Nastavenia → Aplikácie a konektory) a zadajte len adresu servera. Kľúč netreba — otvorí sa Faktero, prihlásite sa, vyberiete firmu a potvrdíte prístup. Prístup sa objaví medzi API kľúčmi ako „AI asistent (MCP)“ a zrušíte ho tam jedným klikom. Pri povolení môžete vybrať aj „Všetky moje firmy“ — asistent sa potom pri otázke spýta, o ktorú firmu ide.

https://www.faktero.sk/api/mcp

Claude Code

claude mcp add --transport http faktero https://www.faktero.sk/api/mcp \
  --header "Authorization: Bearer fk_live_..."

Ostatní klienti (konfigurácia JSON)

{
  "mcpServers": {
    "faktero": {
      "type": "http",
      "url": "https://www.faktero.sk/api/mcp",
      "headers": { "Authorization": "Bearer fk_live_..." }
    }
  }
}

Príklady kódu

Vytvorenie odberateľa

curl -X POST https://faktero.sk/api/v1/customers \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme s.r.o.",
    "ico": "12345678",
    "ic_dph": "SK2020123456",
    "street": "Hlavná 1",
    "city": "Bratislava",
    "zip": "81101",
    "country": "SK",
    "email": "fakturacia@acme.sk"
  }'

const res = await fetch("https://faktero.sk/api/v1/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fk_live_xxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme s.r.o.",
    ico: "12345678",
    email: "fakturacia@acme.sk",
  }),
});
const customer = await res.json();

<?php
$ch = curl_init("https://faktero.sk/api/v1/customers");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer fk_live_xxx",
    "Content-Type: application/json",
  ],
  CURLOPT_POSTFIELDS => json_encode([
    "name" => "Acme s.r.o.",
    "ico" => "12345678",
    "email" => "fakturacia@acme.sk",
  ]),
]);
$customer = json_decode(curl_exec($ch), true);

Vystavenie faktúry

curl -X POST https://faktero.sk/api/v1/invoices \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_123",
    "issue_date": "2026-06-12",
    "due_date": "2026-06-26",
    "currency": "EUR",
    "items": [
      { "name": "Konzultácia", "quantity": 4, "unit": "hod",
        "unit_price": 75, "vat_rate": 23 }
    ]
  }'

Daňový režim: bez poľa reverse_charge ho Faktero určí podľa odberateľa. Firma s IČ DPH iného štátu EÚ dostane faktúru bez DPH ako dodanie do EÚ (reverse_charge_type "eu_b2b"), odberateľ mimo EÚ ako vývoz ("export"); tovar alebo službu povie eu_plnenie ("tovar", "sluzba"; predvolene tovar). Ak niektorá položka nesie nenulovú sadzbu DPH, režim sa nemení — počíta sa s tým, že DPH ste účtovali zámerne. Režim nastavíte aj sami: "reverse_charge": true s reverse_charge_type ("domestic_69", "eu_b2b", "export"), alebo "reverse_charge": false pre tuzemskú DPH.

Stiahnutie PDF

const res = await fetch(
  "https://faktero.sk/api/v1/invoices/inv_123/pdf",
  { headers: { Authorization: "Bearer fk_live_xxx" } }
);
const { url, expires_in } = await res.json();
// url platí hodinu (expires_in = 3600 s) — stiahnite alebo presmerujte používateľa

Odoslanie faktúry e-mailom

curl -X POST https://faktero.sk/api/v1/invoices/inv_123/send \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipient_email": "klient@example.com" }'

Pri prvom odoslaní musí byť dátum vystavenia dnešný. Faktúru so starším dátumom API odmietne odpoveďou 409 s kódom issue_date_in_past (v details je issue_date, today, new_due_date a can_update). Pošlite požiadavku znova s "update_issue_date": true — dátum vystavenia sa zmení na dnes, splatnosť sa posunie o rovnaký počet dní a dátum dodania ostáva. Keď sa dátum zmeniť nedá (can_update: false — uzamknuté obdobie alebo export do účtovníctva), faktúru odošle s pôvodným dátumom až "keep_issue_date": true. Upomienky a opätovné odoslanie sa nekontrolujú.

Keď má firma zapnuté schvaľovanie a voľbu odoslať faktúru až po schválení, neschválenú faktúru API neodošle — vráti 409 s kódom approval_pending. Odošlite ju znova po schválení.

HTTP/1.1 409 Conflict
{
  "error": {
    "code": "issue_date_in_past",
    "message": "Dátum vystavenia nie je dnešný. …",
    "details": {
      "issue_date": "2026-10-20",
      "today": "2026-10-21",
      "new_due_date": "2026-11-04",
      "can_update": true
    }
  }
}

curl -X POST https://faktero.sk/api/v1/invoices/inv_123/send \
  -H "Authorization: Bearer fk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "recipient_email": "klient@example.com", "update_issue_date": true }'

Označiť faktúru ako uhradenú

curl -X POST https://faktero.sk/api/v1/invoices/inv_123/mark-paid \
  -H "Authorization: Bearer fk_live_xxx"

Prijatie webhooku (PHP)

<?php
$secret = getenv("FAKTERO_WEBHOOK_SECRET");
$payload = file_get_contents("php://input");
$sig = $_SERVER["HTTP_X_FAKTERO_SIGNATURE"] ?? "";
$expected = hash_hmac("sha256", $payload, $secret);

if (!hash_equals($expected, $sig)) {
  http_response_code(401);
  exit;
}

$event = json_decode($payload, true);
// $event["event"] === "invoice.paid" …
http_response_code(200);

Pre vývojárov