15. Pravidelné fakturace (Recurring invoices)

Šablony pro automatické generování faktur v pravidelných intervalech. Hodí se pro paušální platby (hosting, předplatné, retainer …), kde se fakturuje stále stejná částka stejnému klientovi.

Šablona drží konfiguraci (periodicita, položky, klient, dodavatel) a cron cron-generate-recurring-invoices.php (běží denně) podle ní vytváří nové faktury. Volitelně je rovnou vystaví (přidělí číslo faktury) a/nebo odešle klientovi e-mailem.

15.1 Kdy použít

Pro jednorázové znovuvystavení stávající faktury (např. „udělej ze faktury 5/2026 fakturu 6/2026") slouží klasický klon faktury v detailu faktury — ne pravidelná šablona.

15.2 Vytvoření šablony

V menu Systém → Pravidelné fakturace klikni + Nová šablona, nebo v detailu existující faktury tlačítko Vytvořit šablonu z této faktury (předvyplní klienta, položky, měnu, jazyk i payment method).

15.2.1 Sekce „Periodicita"

15.2.2 Sekce „Faktura"

Tady nastavíš metadata, která se zkopírují na každou vygenerovanou fakturu:

15.2.3 Položky

Položky šablony se 1:1 kopírují na každou vygenerovanou fakturu (popis, mn., cena/j, sazba DPH). Sazba se bere podle vybraného vat_rate_id ze šablony.

⚠️ Změna sazby DPH státem — sazba je v šabloně přišpendlená na konkrétní řádek číselníku. Když se sazba změní (např. 21 % → 22 %), vznikne v vat_rates nový řádek a starý dostane konec platnosti. Šablona pak ukazuje na vypršelou sazbu — generování se zastaví s jasnou chybou (viz banner v § 15.3) a ty ve šabloně vybereš aktuální sazbu. Tím se nikdy tiše nevystaví doklad se starou sazbou. (Totéž hlídá i klonování faktury.)

💡 Neplátce DPH — pokud je dodavatel neplátce, pravidelná fakturace se chová stejně jako jednorázové vystavení: výběr sazby DPH se v šabloně skryje a každá vygenerovaná faktura je bez DPH (0 % „Osvobozeno"). Platí to i pro šablony založené dřív s nominální sazbou — generátor sazbu při vystavení sám sjednotí na 0 %.

Placeholdery období *(od v4.14.0)* — do popisu položky (a do poznámek nad/pod položkami šablony) lze vložit tokeny, které se při každém vygenerování faktury nahradí podle DUZP (u proformy podle data vystavení). Šablona se nikdy nemění, do faktury jde vyhodnocený text. Inline přehled je přímo v editoru šablony (rozbalovací nápověda nad položkami). Pro DUZP 15. 5. 2026:

TokenVýsledekPoznámka
{YYYY}, {YY}2026, 26rok; posun po letech: {YYYY+1} → 2027, {YY-1} → 25
{M}, {MM}5, 05měsíc; posun po měsících vč. přetečení roku: {MM+8} → 01
{MMMM}květennázev měsíce dle jazyka dokladu (cs/en); {MMMM+1} → červen
{Q}2čtvrtletí 1–4; posun po čtvrtletích: {Q+1} → 3
{D}, {DD}15, 15den; posun po dnech: {D+14} → 29
{DATE}15. 5. 2026celé ref. datum, formát dle jazyka dokladu (en: May 15, 2026)
{DATE+1Y-1D}14. 5. 2027datová aritmetika — kombinace ±N jednotek D/M/Y, zleva doprava
{BOM}, {EOM}1. 5. 2026, 31. 5. 2026začátek/konec měsíce (celé datum); posun po měsících: {EOM+1} → 30. 6. 2026, {EOM-1} → 30. 4. 2026

Typický příklad (prodloužení domény na rok):

Prodloužení domény example.cz na období {DATE} - {DATE+1Y-1D}
→ Prodloužení domény example.cz na období 15. 5. 2026 - 14. 5. 2027

Další ukázky: sezóna {YY}/{YY+1} → „sezóna 26/27", servis {Q}Q/{YYYY} → „servis 2Q/2026", úklid za {MMMM} {YYYY} → „úklid za květen 2026", služby za období {BOM} - {EOM} → „služby za období 1. 5. 2026 - 31. 5. 2026".

💡 Přetečení měsíce je ošetřené. Posun po měsících/letech v {DATE±…} se ořezává na poslední den cílového měsíce (jako MySQL DATE_ADD): 31. 1. {DATE+1M} → 28. 2. (ne 3. 3., jak by dalo holé PHP), 29. 2. 2028 {DATE+1Y} → 28. 2. 2029. Posun po dnech ({DATE+30D}) zůstává exaktní. Měsíční tokeny ({M}, {MMMM}, {EOM}…) jsou kotvené na měsíc, takže přetečení u nich nehrozí vůbec (31. 1. {M+1} → 2).

💡 Tokeny se píší velkými písmeny. Cokoli nerozpoznaného ({foo}, {yyyy}, obyčejné závorky v textu) zůstává beze změny — existující šablony fungují beze změny a nic není potřeba escapovat. Placeholdery fungují nezávisle na volbě „Synchronizovat měsíc" níže (lze kombinovat; obojí míří na stejné referenční datum).

15.2.4 Sekce „Automatizace"

Default pro nové šablony je obojí (vystavit + odeslat) zapnuté a režim konceptu „Až při vystavení" → plně automatická pravidelná fakturace.

15.2.5 Otevřený koncept (průběžný výkaz víceprací)

Řeší fakturaci typu fixní SLA + nepravidelné vícepráce: část faktury je stálý paušál, ke kterému během měsíce přibývá proměnný seznam víceprací.

Přepínač „Kdy vytvořit koncept" má dvě hodnoty:

Datum vystavení i DUZP konceptu jsou od začátku nastavené na plánovaný konec období (next_run_date + zvolený režim DUZP) a při vystavení se nemění — i kdyby cron běžel o den později.

Podmínky režimu „Na začátku období":

Typický scénář (fakturace za červen, vystavení a DUZP ke konci měsíce):

  1. Šablona: měsíčně, *Poslední den měsíce*, DUZP *Stejné jako datum vystavení*, režim konceptu *Na začátku období*, vystavit + odeslat zapnuto.
  2. 1.6. cron otevře koncept s fixním SLA řádkem (datum vystavení i DUZP = 30.6.).
  3. Během června doplňuješ vícepráce do výkazu práce na tom konceptu.
  4. 29.6. (1 den předem) ti přijde e-mailová připomínka.
  5. 30.6. cron koncept uzavře, vystaví (SLA + vícepráce) a odešle klientovi.

Pokud koncept během měsíce vystavíš ručně, cron to pozná a v den vystavení už nic nevytvoří — jen posune rozvrh na další měsíc.

15.3 Lifecycle šablony

Šablona má tři stavy:

V seznamu (a na detailu) šablony jsou tlačítka Pozastavit / Obnovit, Vygenerovat teď a Vygenerovat koncept (jednorázový manuál run — užitečné pro testování i pro ruční vytvoření dokladu mimo rozvrh).

⚠️ Banner „Generování selhalo" — když poslední automatické (cronové) generování selže (typicky kvůli vypršelé sazbě DPH nebo nekladné částce), uloží se poslední chyba a zobrazí se jako červený banner na detailu šablony a odznak v seznamu. Po úspěšném (ručním i cronovém) vygenerování banner zmizí.

15.4 Cron

Skript api/bin/cron-generate-recurring-invoices.php — spouštěj ho jednou denně:

0 6 * * * cd /var/www/myinvoice.cz && php api/bin/cron-generate-recurring-invoices.php

Pro testy se hodí --dry-run (vypíše, co by se vygenerovalo, ale nic nevytvoří).

Cron v jednom běhu zvládá tři fáze:

  1. Otevření konceptu — u šablon v režimu *Na začátku období*, kde už začalo fakturované období, vytvoří koncept (idempotentně — jednou za období).
  2. Vystavení — u šablon, kterým nastal next_run_date, vystaví (u režimu *Na začátku období* uzavře otevřený koncept, jinak vygeneruje a vystaví jako dřív).
  3. Připomínka — pošle e-mailové připomínky k otevřeným konceptům, kterým se blíží vystavení (viz „Připomenout dní před vystavením").

Catch-up: pokud cron několik dní nešel, generuje jen jednu fakturu za cyklus a posune o jeden krok — zbytek backlog se doplní postupně další dny. Tím se zabrání tomu, aby po výpadku cron vygeneroval naráz 30 faktur za poslední měsíc.

15.5 Kill-switch (Nastavení → Dodavatel)

V Nastavení → Můj dodavatel je přepínač „Generovat pravidelné fakturace cronem". Pokud je vypnutý, cron tohoto dodavatele úplně přeskočí — všechny šablony se zastaví, dokud ho zase nezapneš. Manuální tlačítko Vygenerovat teď funguje nezávisle.

15.6 Vazba na vygenerované faktury

Každá faktura vytvořená šablonou má vazbu recurring_template_id (sloupec v invoices). V detailu faktury se zobrazí badge ↻ Pravidelná s odkazem na šablonu, ze které pochází.

Když šablonu smažeš, vygenerované faktury zůstanou (databáze má ON DELETE SET NULL — vazba se vyčistí, faktura zůstane platná).

15.7 Activity log

Vše se zaznamenává:

15.8 REST API

Pravidelné fakturace mají vlastní REST endpointy pod /api/recurring/*:

EndpointAkce
GET /api/recurringseznam (filtry: client_id, status)
POST /api/recurringvytvořit šablonu
GET /api/recurring/{id}detail
PUT /api/recurring/{id}update
DELETE /api/recurring/{id}smazat
POST /api/recurring/{id}/pausepozastavit
POST /api/recurring/{id}/resumeobnovit
POST /api/recurring/{id}/run-nowmanuální spuštění (volitelně issue_date)

Detailní schémata viz /api/reference (Redoc) nebo /api/docs (Swagger UI, Try it out).