API: Faktury

Fakturu vytvoříš POST /faktury. Odběratele zadáš buď jako odberatelId (existující), nebo jako objekt odberatel (vytvoří se / spáruje — viz Odběratelé).

curl -X POST https://zafakturujto.cz/api/v1/faktury \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "odberatel": { "nazev": "Firma s.r.o.", "ico": "12345678" },
    "splatnostDny": 14,
    "polozky": [
      { "popis": "Konzultace", "pocet": 2, "jednotkovaCenaBezDPH": 1000, "sazbaDPH": "S_21" }
    ]
  }'

Vybraná pole požadavku

Bez polí uhrada, vystavit a odeslatEmailem vzniká faktura jako rozpracovaná (koncept nejde odeslat e-mailem, proto odeslatEmailem doklad vždy vystaví, i s vystavit: false). Odpověď obsahuje cislo, stav, celkemKUhrade, cestu k pdf, příznak jizExistoval a částky dokladu tak, jak jsou na něm uložené: zaklad, danCelkem, zaokrouhleni, rekapitulace po sazbách, kurz a kurzDatum (den kurzovního lístku ČNB), u cizí měny czk s částkami v Kč (shodně s PDF a exportem) a zapsané platby.

Idempotence

Doklad rovnou uhrazený

Když platba proběhla dřív, než doklad vystavuješ (typicky kartou), pošli objekt uhrada. Doklad vznikne vystavený a zaplacený v jednom kroku, se záznamem platby, a jeho PDF je bez QR platby.

curl -X POST https://zafakturujto.cz/api/v1/faktury \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "externiId": "in_1Qx2Yz",
    "odberatel": { "externiId": "zakaznik_42", "nazev": "Jan Novák", "email": "jan@example.cz" },
    "datumVystaveni": "2026-09-29",
    "duzp": "2026-09-28",
    "uhrada": {
      "datum": "2026-09-28T09:30:00Z",
      "zpusob": "KARTOU",
      "zdroj": "stripe",
      "externiId": "pi_3Abc",
      "potlacitPotvrzeni": true
    },
    "polozky": [
      { "popis": "Roční členství", "jednotkovaCenaBezDPH": 1000, "sazbaDPH": "S_21" }
    ]
  }'

Stejný objekt uhrada přijímá i PATCH /faktury/{cislo}/stav se stavem ZAPLACENA. Bez něj se platba zapíše s dnešním datem jako dosud.

Ceny s DPH

Když znáš cenu včetně DPH (třeba částku zaplacenou kartou), pošli cenySDPH: true a u každé položky jednotkovaCenaSDPH místo jednotkovaCenaBezDPH. Základ a DPH se spočítají „shora“ po sazbách (§ 37 zákona o DPH): základ = cena s DPH / (1 + sazba) zaokrouhlený na haléře, DPH = rozdíl. Celkem dokladu je přesně součet cen s DPH — s zaokrouhlitNaCele: false i u CZK na haléř.

curl -X POST https://zafakturujto.cz/api/v1/faktury \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{
    "externiId": "in_1Qx2Yz",
    "odberatel": { "nazev": "Jan Novák", "email": "jan@example.cz" },
    "cenySDPH": true,
    "zaokrouhlitNaCele": false,
    "uhrada": { "zdroj": "stripe", "externiId": "pi_3Abc" },
    "polozky": [
      { "popis": "Měsíční předplatné", "jednotkovaCenaSDPH": 261.79, "sazbaDPH": "S_21" }
    ]
  }'

Doklad vyjde 216,36 Kč základ + 45,43 Kč DPH = 261,79 Kč. Ceny s DPH jdou jen u typDokladu FAKTURA a bez odecistZalohy; kombinace cen s DPH a bez DPH v jednom dokladu se odmítne (HTTP 400). Cena s DPH a počet mají nejvýš 4 desetinná místa, sleva nejvýš 2 (víc HTTP 400). Doklad s cenami s DPH nejde upravit v aplikaci — opravuje se dobropisem.

Dobropis

POST /faktury/{cislo}/dobropis bez pole castka vystaví dobropis na celou fakturu. Volitelně pošli duvod, externiId, datum a ciselnaRadaId (aktivní řada dobropisů; výchozí je výchozí řada). Opakované volání vrátí existující dobropis s HTTP 200. Odpověď obsahuje číslo dobropisu, cestu k jeho PDF, jeho částky a zbyvaDobropisovat faktury.

curl -X POST https://zafakturujto.cz/api/v1/faktury/FV2026-010/dobropis \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{ "duvod": "Zrušení členství", "externiId": "re_3Def", "datum": "2026-09-30" }'

Částečný dobropis

Vracíš-li jen část platby, pošli castka — částku s DPH v měně faktury — a vždy externiId (třeba ID refundace). K jedné faktuře jde vystavit víc dobropisů, dokud jejich součet nepřesáhne fakturu. Základ a DPH se po sazbách určí rozdílovou metodou (§ 45 zákona o DPH), takže po vrácení celé částky dají dobropisy dohromady přesně zápor faktury. Stornovaný dobropis se do součtu nepočítá.

curl -X POST https://zafakturujto.cz/api/v1/faktury/VEU26-0026/dobropis \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{ "castka": 14.70, "externiId": "re_3Ghi", "duvod": "Částečná refundace", "datum": "2026-10-24" }'

Dobropis na částku jde vystavit k faktuře typu FAKTURA bez odečtené zálohy. Detail faktury vrací všechny dobropisy v poli dobropisy, součet v dobropisovano a zbytek v zbyvaDobropisovat.

Vrácení peněz k dobropisu

Když peníze k dobropisu odběrateli vrátíš (třeba refundací na kartu), zapiš to přes PATCH /faktury/{cislo dobropisu}/stav se stavem ZAPLACENA a objektem uhrada. U dobropisu vznikne jedna platba se zápornou částkou na zbytek dobropisu a dobropis bude uhrazený s datem z uhrada.datum. Odběrateli nic neodejde a webhook INVOICE_PAID se neposílá. Opakované volání nic dalšího nezapíše, externí ID platby použité u jiného dokladu vrátí HTTP 409. Bez uhrada dobropis zaplacený označit nejde (HTTP 400), stejně jako dobropis z importu. Vrácení nejde vzít zpět změnou stavu. Storno dobropisu zapsané vrácení odstraní (refund se nepovedl, nebo dobropis nahradí jiný a vrácení se zapíše k němu).

curl -X PATCH https://zafakturujto.cz/api/v1/faktury/DB2026-001/stav \
  -H "Authorization: Bearer fakt_TVUJ_KLIC" \
  -H "Content-Type: application/json" \
  -d '{ "stav": "ZAPLACENA", "uhrada": { "datum": "2026-10-24", "zpusob": "KARTOU", "zdroj": "stripe", "externiId": "re_3Ghi" } }'

Odeslání e-mailem

POST /faktury/{cislo}/email odešle doklad (i dobropis) s PDF v příloze na e-mail odběratele. Jiného příjemce zadáš polem email. Každé volání odešle e-mail znovu.

Čtení

GET /faktury přijímá filtry externiId, odberatelId a odberatelExterniId. Bez filtrů vrací běžné a konečné faktury; filtr externiId najde doklad libovolného typu, tedy i zálohovou fakturu nebo dobropis. Detail GET /faktury/{cislo} vrací i externiId, cisloObjednavky, zapsané platby, položky se základem a DPH, částky dokladu (jako odpověď vytvoření) a dobropisy k faktuře (dobropisy, dobropisovano, zbyvaDobropisovat). PDF stáhneš z GET /faktury/{cislo}/pdf.