Kimai + MyInvoice – nápověda
Jak jsou propojené výkazy času v Kimai a fakturace v MyInvoice přes n8n: co který workflow dělá, jak se používá a co dělat, když něco nefunguje.
Jak to celé funguje
1 · Import firem
MyInvoice → Kimai. Klienti založení v MyInvoice se objeví v Kimai jako zákazníci.
automaticky 6:002 · Projekty → zakázky
Kimai → MyInvoice. Projekt založený v Kimai dostane v MyInvoice zakázku se sazbou a obě se propojí.
automaticky 6:153 · Fakturace hodin
Kimai → MyInvoice. Ve formuláři vybereš projekty, vzniknou koncepty faktur a časy se v Kimai zamknou.
ručně přes formulářKlienty zakládej v MyInvoice. Projekty zakládej v Kimai pod zákazníkem, který přišel z MyInvoice. Faktury vznikají jen jako koncepty – vystavuješ je sám v MyInvoice.
Vazby mezi aplikacemi
Aplikace se párují přes čísla uložená v Kimai. Na tato pole v Kimai ručně nesahej.
| Co | Pole v Kimai | Hodnota | Kdo ho vyplňuje |
|---|---|---|---|
| Klient ↔ zákazník | Číslo zákazníka (number) | ID klienta v MyInvoice, např. 92 | Import firem |
| Zakázka ↔ projekt | Číslo objednávky projektu (orderNumber) | MI-<ID zakázky>, např. MI-31 | Projekty → zakázky |
Kimai si u nových projektů Číslo vyplňuje sám (např. 0002). Proto je vazba projektu v poli Číslo objednávky. Pokud v Čísle objednávky najde workflow jinou hodnotu než MI-…, nepřepíše ji a jen upozorní.
Tokeny a přihlášení
| Credential v n8n | Token | Kde se vytváří | Používá |
|---|---|---|---|
| MyInvoice | rozsah read, vázaný na dodavatele, bez expirace | MyInvoice → Systém → API tokeny → Nový token | Import firem |
| MyInvoice zápis | rozsah read & write, vázaný na dodavatele | MyInvoice → Systém → API tokeny → Nový token | Projekty → zakázky, Fakturace hodin |
| Kimai | API token admin uživatele | Kimai → avatar vpravo nahoře → API access → Create | všechny tři workflow |
Jak je credential v n8n nastavený
- Typ Header Auth.
- Name: přesně
Authorization– je to název HTTP hlavičky, ne název credentialu. - Value:
Bearer <token>(slovo Bearer, mezera, token). - Název credentialu (MyInvoice / Kimai…) se mění kliknutím na nadpis v levém horním rohu okna credentialu.
MyInvoice i Kimai ukážou token jen při vytvoření. Ztracený token zruš a vytvoř nový, pak ho vlož do credentialu v n8n. Do workflow ani do této nápovědy tokeny nepatří.
Workflow: Import firem MyInvoice → Kimai
Načte klienty z MyInvoice a zákazníky z Kimai. Chybějící klienty v Kimai založí a do Čísla zákazníka uloží ID klienta z MyInvoice.
Koho přeskočí
- čisté dodavatele (firmy, které jsou v MyInvoice jen dodavatel),
- archivované klienty,
- klienty, kteří už v Kimai jsou – podle Čísla, případně podle stejného názvu.
Co se přenáší
Název, adresa (addressLine1, postCode, city), DIČ (vatId), IČO do komentáře, e-mail, telefon, web, země a měna. Časové pásmo je vždy Europe/Prague. Země zahraničních klientů se dohledá z číselníku zemí MyInvoice.
Uzly: Spustit ručně / plánovač → Nastavení → MyInvoice klienti → Kimai zákazníci → MyInvoice země → Najít nové firmy → MyInvoice detail klienta → Namapovat na Kimai → Limit (test) → Kimai založit zákazníka
Workflow: Projekty → zakázky Kimai → MyInvoice
U každého viditelného projektu v Kimai bez vazby:
- Zkusí u klienta v MyInvoice najít zakázku se stejným názvem.
- Když ji nenajde, zakázku založí – se sazbou
VYCHOZI_SAZBAa splatností 14 dní. - Do Čísla objednávky projektu v Kimai zapíše
MI-<ID zakázky>.
Nastavení
MI_URL,KIMAI_URL– adresy aplikací bez lomítka na konci.VYCHOZI_SAZBA– hodinová sazba pro nové zakázky. Konkrétní zakázce ji pak můžeš upravit v MyInvoice.- Splatnost
payment_due_days: 14je v kódu uzlu Najít projekty bez zakázky. MyInvoice ji u zakázky vyžaduje (1–365 dní).
Upozornění ve výstupu
upozorneni_zakaznik_neni_z_myinvoice– zákazník projektu nemá Číslo z MyInvoice (byl založen jen v Kimai).upozorneni_zakazka_nenalezena_v_myinvoice– projekt máMI-…, ale taková zakázka v MyInvoice není.upozorneni_jine_cislo_objednavky– v Čísle objednávky je jiná hodnota, workflow ji nechá být.
Uzly: Spustit ručně / plánovač → Nastavení → Kimai projekty → Kimai zákazníci → MyInvoice zakázky → Najít projekty bez zakázky → Jen k akci → Limit (test) → Založit nebo propojit? → (MyInvoice založit zakázku → Propojení po založení) → Má ID zakázky → Kimai zapsat vazbu
Workflow: Fakturace hodin Kimai → MyInvoice
- Otevři záložku s formulářem (Production URL z uzlu Fakturace hodin). Volitelně zadej „Do data“ – prázdné = do dneška.
- Formulář ukáže projekty s nevyfakturovanými hodinami, např. Klient – Projekt: 2,02 h (1 záznam). Zaškrtni, co chceš fakturovat.
- Klikni na Vytvořit koncepty. Pro každý projekt vznikne v MyInvoice koncept faktury s jedním řádkem.
- Formulář vypíše výsledek a vyfakturované časy se v Kimai zamknou (exportováno).
Které časy se nabízejí
- jen ukončené záznamy (běžící stopky ne),
- jen fakturovatelné (záznam s vypnutým Fakturovatelné se nenabídne),
- jen neexportované (už vyfakturované jsou zamčené),
- jen na projektech s vazbou
MI-…– ostatní formulář vypíše jako „bez vazby na zakázku“.
Jak vypadá koncept
| Klient, zakázka | z vazby projektu (MI-…) |
|---|---|
| Řádek | název projektu z Kimai |
| Množství | součet hodin, bez zaokrouhlení (2:01 → 2,02 h) – případně upravíš ručně v MyInvoice |
| Cena | hodinová sazba ze zakázky v MyInvoice |
| DPH | VAT_RATE_ID = 3 = sazba CZ-0 Osvobozeno (neplátce) |
| Datum, splatnost | dnešní datum, splatnost podle zakázky |
4 (CZ-RC) je reverse charge – jiný daňový režim a jiná doložka na faktuře. 1 (21 %) by u neplátce přidala DPH do součtů. MyInvoice sazbu u položky vyžaduje i u neplátce, proto se posílá CZ-0.
Kdy se koncept nevytvoří
- zakázka nemá hodinovou sazbu → doplň ji v MyInvoice a spusť formulář znovu,
- MyInvoice koncept odmítne → chyba je vidět na stránce s výsledkem.
V obou případech se časy nezamknou, takže se při dalším spuštění nabídnou znovu.
Uzly: Fakturace hodin (formulář) → Nastavení → Kimai časy → Kimai projekty → Kimai zákazníci → Připravit výběr → Je co fakturovat? → Výběr projektů → Vybrané projekty → MyInvoice zakázka → Sestavit koncepty → Lze vytvořit? → Rozdělit platné → MyInvoice vytvořit koncept → Souhrn → (Záznamy k zamčení → Kimai zamknout záznam) + Hotovo
Běžný provoz
Nový klient
Založ ho v MyInvoice. Do Kimai se dostane ráno v 6:00, nebo hned po ručním spuštění Importu firem.
Nový projekt
Založ ho v Kimai pod zákazníkem z MyInvoice. Zakázka v MyInvoice vznikne ráno v 6:15, nebo po ručním spuštění workflow Projekty → zakázky.
Fakturace
Otevři formulář, vyber projekty, zkontroluj koncepty v MyInvoice a vystav je.
Hotový projekt
V Kimai ho skryj. Synchronizace pracuje jen s viditelnými projekty.
Fakturuješ projekt založený ještě dnes?
Formulář ho ukáže jako „bez vazby na zakázku“. Ručně spusť workflow Projekty → zakázky a otevři formulář znovu.
Potřebuješ vyfakturovaný čas opravit a vyfakturovat znovu?
V Kimai záznam odemkni (hromadná úprava → zrušit Exportováno), uprav ho a ve formuláři se nabídne znovu. Starý koncept nebo fakturu v MyInvoice vyřeš ručně.
Řešení problémů
Chyby, na které jsme narazili při stavbě, a jejich řešení.
| Co vidíš | Příčina | Řešení |
|---|---|---|
Header name must be a valid HTTP token | V credentialu je v poli Name název credentialu | Name = Authorization, název credentialu měň v nadpisu okna |
Credentials not found | Uzel nemá vybraný credential, nebo jde o starý výstup | Vyber credential v uzlu, ulož a spusť znovu |
| Do Kimai se nic nezapsalo, vše zelené | Zapisovací uzel je vypnutý (Deactivated), nebo chyby zůstaly ve výstupu | Zapni uzel (D), zkontroluj výstup – chyby jsou v poli error |
Kimai 400 … extra fields | Kimai nezná některé pole | Hláška vypíše povolená pole – např. místo address jsou addressLine1, postCode, city |
MyInvoice 400 payment_due_days | Zakázka musí mít splatnost | V kódu se posílá payment_due_days: 14 |
MyInvoice 400 items.0.vat_rate_id | Položka faktury musí mít sazbu DPH | VAT_RATE_ID = 3 v Nastavení fakturace |
| Formulář: „bez vazby na zakázku“ | Projekt nemá MI-… v Čísle objednávky | Spusť Projekty → zakázky (oba zapisovací uzly zapnuté) |
Node was not executed | Předchozí uzel nic nepropustil | Spusť celý workflow a podívej se na počty položek na spojnicích |
Problem loading form | Workflow není publikované | Ve workflow vpravo nahoře Publish. Po každé úpravě publikovat znovu |
| Koncept vznikl dvakrát | Při předchozím běhu bylo vypnuté zamykání | Duplicitní koncept smaž, uzel Kimai zamknout záznam nech zapnutý |
| Automatický běh selhal | Chyba při plánovaném spuštění | Záložka Executions v n8n – červené běhy, klikni na uzel s chybou |
Spusť celý workflow tlačítkem Execute workflow a podívej se na počty položek na spojnicích. Kde počet klesne na nulu, tam je problém – otevři ten uzel a podívej se na jeho výstup (záložka JSON).
Práce v n8n
| Úkon | Jak |
|---|---|
| Import workflow ze souboru | Nový prázdný workflow → menu ⋯ → Import from File (nikdy ne do existujícího workflow) |
| Vypnout / zapnout uzel | Označ uzel a stiskni D, nebo ikona ⏻ v liště nad uzlem |
| Chování při chybě | Uzel → záložka Settings → On Error (v synchronizacích Stop Workflow) |
| Plánované spouštění | Uzel Schedule Trigger napojený na uzel Nastavení, workflow publikovat |
| Aktivace / nová verze | Vpravo nahoře Publish. Upravený workflow publikuj znovu |
| Test formuláře | Test URL funguje jen při otevřeném editoru, Production URL jen u publikovaného workflow |
| Historie běhů | Záložka Executions u workflow |
| Uložení | Ctrl + S |
Soubory JSON všech tří workflow jsou zároveň zálohou – credentials v nich nejsou. Po importu stačí vybrat credentials v HTTP uzlech a vyplnit Nastavení.
Použitá API
MyInvoice (/api/v1, hlavička Authorization: Bearer mi_pat_…)
| Volání | K čemu |
|---|---|
GET /api/v1/auth/api-me | test tokenu |
GET /api/v1/clients, /clients/{id} | klienti (stránkování per_page=100, page) |
GET /api/v1/codebooks/countries | číselník zemí |
GET /api/v1/projects, /projects/{id} | zakázky, sazba hourly_rate |
POST /api/v1/projects | nová zakázka: client_id, name, payment_due_days, hourly_rate |
POST /api/v1/invoices | koncept: client_id, project_id, issue_date, items[] (description, quantity, unit, unit_price_without_vat, vat_rate_id) |
Sazby DPH: 1 CZ-21 · 2 CZ-12 · 3 CZ-0 Osvobozeno · 4 CZ-RC reverse charge. Dokumentace API je na vlastní instanci MyInvoice pod /api/docs (Swagger).
Kimai (/api, hlavička Authorization: Bearer …)
| Volání | K čemu |
|---|---|
GET /api/customers?visible=3 | všichni zákazníci včetně skrytých |
POST /api/customers | nový zákazník |
GET /api/projects?visible=1&ignoreDates=1 | viditelné projekty (visible=3 = všechny) |
PATCH /api/projects/{id} | zápis vazby {"orderNumber": "MI-31"} |
GET /api/timesheets?exported=0&active=0&size=250&end=… | nevyfakturované ukončené časy (stránkování page) |
PATCH /api/timesheets/{id}/export | zamknutí záznamu |
/export stav přepíná
Volání zamčený záznam odemkne a odemčený zamkne. Workflow ho proto volá jen u záznamů, které načetl jako neexportované, a jen jednou.
Rozpracováno a nápady
Automatické párování plateb z Fio rozpracováno
n8n jednou denně stáhne z API Fio nové pohyby ve formátu GPC a nahraje je do MyInvoice jako bankovní výpis. Platby pak spáruje samo MyInvoice stejně jako při ručním nahrání: podle VS a částky, včetně částečných a sloučených úhrad, s datem platby z banky.
| Krok | Volání |
|---|---|
| Nové pohyby od posledního stažení | GET https://fioapi.fio.cz/v1/rest/last/{token}/transactions.gpc |
| Nahrání výpisu do MyInvoice | POST /api/v1/bank-statements/upload (GPC/ABO) ověřeno ve Swaggeru |
| Nespárované platby | ručně ve výpisu (Spárovat / Ignorovat), případně POST /api/v1/bank-statements/{id}/rematch |
- Token Fio: internetbanking → Nastavení → API → přidat token s oprávněním Sledování účtu. Platnost max. 180 dní, s automatickým prodlužováním při přihlášení. Fio doporučuje mezi dotazy aspoň 30 s.
- Po zapnutí už nenahrávat ručně výpisy ze stejného období.
Ruční označení platby (do té doby)
- Výpis z Fio: stáhnout ve formátu GPC → MyInvoice → Finance → Bankovní účty → Bankovní výpisy → Nahrát. Párování podle VS a částky, datum platby = datum zaúčtování.
- Jedna faktura s datem: detail faktury → Částečná úhrada → datum platby.
- Hromadně: seznam faktur → Označit zaplacené – vždy s dnešním datem.
Další nápady
- Tlačítko v Kimai – plugin, který přidá do menu Export položku „Do MyInvoice“ (podle filtru). Vyžaduje přístup na server Kimai.
- Synchronizace projektů přímo ve formuláři – nové projekty by se propojily při otevření formuláře.