Endpointy

Přehled koncových bodů REST API s příklady použití. Mapu všech oblastí najdete v API přehledu.

Všechny příklady posílají klíč v hlavičce Authorization: Bearer. ID jsou UUID — v příkladech je zkracujeme na <uuid> a {id}.

Pravidla platná všude

• Zápis (POST, PUT, PATCH, DELETE) vyžaduje klíč s plným přístupem. Klíč Pouze čtení zápis odmítne chybou 403. Výjimkou jsou dotazy, které nic nemění: AI dotaz a náhled importu nákladů.
• Role a rozsah: API klíč dědí roli svého majitele. Co člověk v aplikaci nevidí, nedostane ani přes API. U každé oblasti níž je řádek Kdo smí.
• Pole, která endpoint nezná, server bez chyby zahodí. Překlep v názvu pole proto nevrátí chybu — hodnota se jen neuloží.
• Částky jsou v nejmenší jednotce měny (CZK celé koruny, EUR a USD centy). Jedinou výjimkou je import nákladů, který bere hlavní jednotky.
• Úpravy (PUT) posílají jen pole, která měníte — není-li u koncového bodu uvedeno jinak.

Time Entries (záznamy práce)

Kdo smí: všechny role. Člen a HR vidí a zapisují jen své výkazy, manažer výkazy svého rozsahu, vlastník, administrátor a účetní všechny. Účetní výkazy nezakládá.

Získání seznamu

curl -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/time-entries?from=2026-03-01&to=2026-03-31"

Query parametry (všechny nepovinné):

Parametr	Význam
from, to	Období ve tvaru RRRR-MM-DD; to zahrne celý den
project_id	UUID projektu, nebo none pro výkazy bez projektu
user_id	UUID člena
status	draft, submitted, approved, nebo invoiced
activity_id	UUID typu práce
q	Hledání v popisu a v názvech projektu, klienta, typu práce i autora
limit, offset	Stránkování — viz Stránkování

Výsledek je seřazený od nejnovějšího záznamu. Co kdo vidí, určuje role: člen a HR jen své výkazy, manažer výkazy svých klientů a svých lidí. Manažer vidí u práce svých lidí hodiny a popis všude, ale částky jen u klientů, které spravuje.

Hranice dne

Samotné datum ve from a to se počítá od půlnoci UTC, ne pražského času. Práce začatá mezi půlnocí a jednou až dvěma ráno se proto může přiřadit k sousednímu dni a součet za měsíc se od aplikace nepatrně liší. Přesné pražské hranice dostanete, když pošlete čas s posunem: from=2026-03-01T00:00:00%2B01:00 (znak + se v adrese píše jako %2B).

Detail záznamu

GET /time-entries/{id} vrátí jeden výkaz včetně projektu, autora a typu práce. Platí stejná pravidla viditelnosti jako u seznamu.

Vytvoření záznamu

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"userId": "<uuid>", "projectId": "<uuid>", "description": "API integrace", "startedAt": "2026-03-27T09:00:00+01:00", "durationMinutes": 150}' \
  https://app.mujvykaz.cz/api/v1/time-entries

Povinná pole:

• userId — komu výkaz patří (své ID vrátí GET /users/me)
• description — popis práce (1–1000 znaků)
• startedAt — začátek práce. Přijímá čas s posunem (2026-03-27T09:00:00+01:00, i …Z), pražský čas bez posunu (2026-03-27T09:00) i samotné datum (2026-03-27 — dosadí 9:00). Nejvýš o den do budoucna.
• durationMinutes — délka v minutách (1–1440)

Nepovinná pole: projectId, isBillable, hourlyRate, activityId (typ práce z GET /activities) a taskId (úkol). Když sazbu nepošlete, aplikace ji dopočítá stejně jako při zápisu v aplikaci — včetně ceníku typu práce. U výkazu k úkolu se projekt odvodí z úkolu, projectId můžete vynechat (jiný projekt než má úkol server odmítne). hourlyRate je v měně klienta projektu (bez projektu v měně organizace), v nejmenší jednotce měny. Úspěch vrátí stav 201 a nový záznam.

Člen a HR zapisují vždy sami sobě — cizí userId server nahradí vaším vlastním a chybu nevrátí. Za jiného člověka zapisuje vlastník a administrátor (komukoli) a manažer, ale jen tam, kde by výkaz sám mohl schválit: svým lidem na střediska klientů, které spravuje. Jinak vrátí 403. Výkaz do uzamčeného měsíce nebo před mez Výkazy od server odmítne.

Úprava a smazání záznamu

# Úprava — posílejte jen pole, která měníte
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"description": "API integrace — oprava", "durationMinutes": 120}' \
  https://app.mujvykaz.cz/api/v1/time-entries/{id}

# Smazání
curl -X DELETE -H "Authorization: Bearer vas_klic" \
  https://app.mujvykaz.cz/api/v1/time-entries/{id}

Upravit jde description, durationMinutes, hourlyRate, isBillable, projectId, activityId, taskId a date (nový den ve tvaru RRRR-MM-DD; čas dne zůstane). Hodnota null u activityId typ práce odebere, u taskId výkaz od úkolu odepne; pole, které nepošlete, se nemění. Platí stejná pravidla jako v aplikaci: obsah výkazu mění jen jeho autor a člen jen dokud je výkaz koncept.

Stav výkazu se úpravou nemění. Pole status smí jen zopakovat současný stav, jiný stav server odmítne — odeslání, schválení i vrácení dělá bulk-status.

Smazání: člen a HR smažou jen vlastní koncepty, manažer jen vlastní výkazy, cizí výkazy smí smazat jen vlastník a administrátor. Účetní nemaže nic. Vyfakturovaný výkaz smazat nejde, schválený v uzamčeném měsíci také ne.

Hromadná změna stavu (bulk-status)

# Odeslání ke schválení
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<uuid>", "<uuid>"], "status": "submitted"}' \
  https://app.mujvykaz.cz/api/v1/time-entries/bulk-status

# Schválení (vlastník, administrátor, manažer)
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<uuid>", "<uuid>"], "status": "approved"}' \
  https://app.mujvykaz.cz/api/v1/time-entries/bulk-status

# Vrácení k přepracování s poznámkou (vlastník, administrátor, manažer)
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<uuid>"], "status": "draft", "note": "Doplňte prosím popis."}' \
  https://app.mujvykaz.cz/api/v1/time-entries/bulk-status

ids je seznam 1–500 UUID. Podporované hodnoty status: submitted, approved, draft (vrácení). Nepovinná note (nejvýš 500 znaků) je poznámka k vrácení. Výkaz, který je v odeslaném klientském reportu nebo na nestornované faktuře, vrátit nejde.

Projects (projekty)

V aplikaci se projektům podle nastavení firmy říká také Střediska nebo Zakázky — API používá vždy slovo projekt (projectId).

Kdo smí: seznam všechny role — člen a HR dostanou projekty bez peněz (člen jen ty, na kterých má výkaz), manažer projekty svých klientů. Detail ne člen a ne HR. Zakládat a upravovat smí vlastník, administrátor a manažer (manažer jen u svých klientů), mazat jen vlastník a administrátor.

Získání seznamu a detailu

curl -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/projects?client_id=<uuid>"

Nepovinné parametry: status (active, paused, done, archived) a client_id. Detail jednoho projektu vrátí GET /projects/{id}.

Vytvoření projektu

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "<uuid>", "name": "Nový web", "hourlyRate": 1500}' \
  https://app.mujvykaz.cz/api/v1/projects

Povinná pole: clientId, name. Nepovinná: description, budgetHours (celé hodiny), budgetAmount, hourlyRate, deadline. Vyžaduje klíč s plným přístupem; platí limit projektů vašeho tarifu. Projekt vznikne aktivní a s typem rozpočtu hodinová sazba — pevnou cenu ani interní typ přes API nenastavíte.

budgetAmount a hourlyRate jsou v měně klienta (bez vlastní měny v měně organizace), v nejmenší jednotce: u eurového klienta znamená "hourlyRate": 1500 částku 15,00 €.

Úprava a smazání projektu

curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"status": "done"}' \
  https://app.mujvykaz.cz/api/v1/projects/{id}

Volitelná pole: name, description, status, budgetHours, budgetAmount, hourlyRate, deadline. Posílejte jen ta, která chcete změnit. Vyžaduje klíč s plným přístupem a roli vlastník, administrátor nebo manažer (manažer jen u projektů svých klientů) — stejně jako vytvoření projektu.

DELETE /projects/{id} smí jen vlastník a administrátor. Projekt s prací v zamčeném měsíci smazat nejde.

deadline chce plný ISO 8601 časový údaj

Pole deadline posílejte jako 2026-06-30T00:00:00Z. Samotné 2026-06-30 endpoint odmítne s chybou validace. (Import v aplikaci naopak očekává tvar RRRR-MM-DD — jsou to dvě různé cesty.)

Datum dodání (completedAt)

Odpověď GET /projects obsahuje i pole completedAt — datum, kdy byla zakázka dodaná. U zakázky s pevnou cenou určuje měsíc, do kterého spadne její tržba v Ziskovosti.

Přes API ho nelze nastavit přímo. Mění se jen nepřímo změnou pole status:

Změna status	Co se stane s completedAt
na done	orazítkuje se dnešním dnem (pokud datum ještě nemá)
na active	zruší se
na paused / archived	zůstane beze změny

Ruční opravu data dodání (například na skutečný den odevzdání) provedete v aplikaci — viz Datum dodání. Totéž platí pro MCP nástroj update_project, který jde přes tenhle endpoint.

Clients (klienti)

Kdo smí: seznam a detail vlastník, administrátor, účetní a manažer (jen své klienty); HR dostane klienty bez peněžních polí; člen klienty nevidí. Zakládat a upravovat smí vlastník, administrátor a manažer.

Získání seznamu a detailu

curl -H "Authorization: Bearer vas_klic" \
  https://app.mujvykaz.cz/api/v1/clients

GET /clients/{id} vrátí klienta s jeho projekty a základním přehledem faktur (ID, číslo, stav, částka).

Vytvoření klienta

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"name": "Firma s.r.o.", "contactEmail": "fakturace@firma.cz", "defaultHourlyRate": 1500, "metadata": {"ico": "12345678", "dic": "CZ12345678"}}' \
  https://app.mujvykaz.cz/api/v1/clients

Povinné pole: name. Nepovinná: contactEmail, contactPerson, defaultHourlyRate, metadata. Vyžaduje klíč s plným přístupem. Manažer, který klienta založí, se k němu rovnou přiřadí.

IČO, DIČ a adresa patří do objektu metadata (klíče ico, dic, address, city, zip). Samostatné pole ico endpoint nezná. Měnu klienta API nastavit neumí — klient vznikne v měně organizace. Eurového klienta přepnete v aplikaci v úpravě klienta (jen dokud nemá výkazy), nebo ho založíte importem CSV se sloupcem Měna. ARES se přes API nedoplňuje: uloží se jen to, co pošlete.

Úprava klienta

PUT /clients/{id} s poli, která měníte: name, contactEmail, contactPerson, defaultHourlyRate, isActive, metadata.

Kontakty a historie klienta (karta klienta)

Kdo smí: vlastník, administrátor, manažer (jen své klienty) a účetní. Vyžaduje tarif Starter nebo vyšší.

Požadavek	K čemu
GET /clients/{id}/contacts	Kontaktní osoby klienta
POST /clients/{id}/contacts	Přidat kontakt (nejvýš 10 na klienta)
GET /clients/{id}/activities	Historie klienta — ruční záznamy
POST /clients/{id}/activities	Přidat záznam do historie

Kontakt: povinné name, nepovinné role, email, phone, note, is_primary (hlavní kontakt). Záznam v historii: povinné body (1–5000 znaků), nepovinné type (note, call, meeting, followup; výchozí note) a occurred_at. Pole due_at (termín) je povinné u připomenutí followup a u ostatních typů ho server odmítne; totéž platí pro assignee_id (komu je připomenutí přiřazené, výchozí jste to vy).

Tělo požadavku je tady v snake_case

U těchto dvou koncových bodů se pole is_primary, occurred_at, due_at a assignee_id píšou s podtržítkem — na rozdíl od ostatních těl požadavků.

Typy práce a kategorie nákladů

Číselníky organizace. Typ práce nese případnou sazbu za činnost, kategorie nákladu sazbu DPH pro fakturaci.

Kdo smí: číst všechny role (člen u typu práce nedostane sazbu defaultRate). Založit smí vlastník a administrátor rovnou; manažer podá návrh, který musí schválit administrátor v aplikaci — do schválení se položka nikde nenabízí a nejde použít.

Požadavek	K čemu
GET /activities	Aktivní typy práce (id, name, defaultRate, color, sortOrder)
POST /activities	Založit nebo navrhnout typ práce — name, nepovinné defaultRate a color (#RRGGBB)
GET /expense-categories	Aktivní kategorie nákladů (id, name, vatRate, sortOrder)
POST /expense-categories	Založit nebo navrhnout kategorii — name, nepovinná vatRate (0–100)

Založení vlastníkem nebo administrátorem vrátí 201 s novou položkou. Návrh manažera vrátí 202 a {"proposal": true, "status": "pending"}. Typy práce se zakládají jen tehdy, když je v organizaci zapnuté Používat typy práce.

Invoices (faktury)

Kdo smí: čtení vlastník, administrátor, účetní a manažer (jen faktury svých klientů). HR a člen faktury přes API nedostanou. Organizace, která má modul Fakturace vypnutý, dostane na seznam i detail chybu 404.

Získání seznamu

curl -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/invoices?status=sent"

Nepovinné parametry: status (draft, sent, paid, cancelled) a client_id. Filtr podle data seznam faktur nemá. Detail jedné faktury vrátí GET /invoices/{id}.

Faktura z klientského reportu

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"reportId": "<uuid>"}' \
  https://app.mujvykaz.cz/api/v1/invoices/from-report

Povinné pole: reportId — odeslaný klientský report (z neodeslaného reportu server fakturu odmítne chybou 412). Nepovinná: vatRate, notes. Faktura vznikne jako koncept a odpověď má stav 201 a nese invoiceId, invoiceNumber, lineCount, totalAmount a currency.

Když se částka reportu liší od hodnoty výkazů podle ceníku, pošlete i acknowledgeSourceDiff: true. Když report obsahuje výkazy, které už jsou na jiné faktuře, server fakturu odmítne a s skipInvoicedLines: true jejich řádky vynechá. Viz Faktura z klientského reportu.

Fakturu přímo z vybraných výkazů REST API nevystaví — tu vystavíte v aplikaci.

Změna stavu a storno

# Označit jako odeslané nebo zaplacené (nejvýš 50 faktur najednou)
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["<uuid>"], "status": "paid"}' \
  https://app.mujvykaz.cz/api/v1/invoices/status

# Storno s povinným důvodem
curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Chybná částka"}' \
  https://app.mujvykaz.cz/api/v1/invoices/{id}/cancel

status je sent, nebo paid; kroky nejdou přeskočit (čerstvá faktura je koncept a nejdřív se označí jako odeslaná). Přes API se faktura nemaže — stornuje se s důvodem (storno jde jen u odeslané nebo zaplacené faktury). Obojí smí vlastník, administrátor, účetní a manažer u svých klientů.

Klientské reporty

Soupis odvedené práce za období, který se posílá klientovi a bývá podkladem faktury. Viz Klientské reporty.

Kdo smí: vlastník, administrátor, účetní a manažer (jen reporty svých klientů).

Požadavek	K čemu
GET /client-reports	Seznam reportů; nepovinný filtr status (draft, sent)
GET /client-reports/{id}	Detail reportu včetně řádků — to, co uvidí klient
POST /client-reports	Sestavit report za období
POST /client-reports/{id}/send	Odeslat report klientovi e-mailem

Sestavení: povinná pole clientId, periodFrom, periodTo (RRRR-MM-DD) a title; nepovinná projectIds, tagIds, includeStatuses (approved, invoiced) a includeExpenses. Report vznikne jako rozpracovaný a klientovi se neodešle.

Odeslání je akce ven z firmy

POST /client-reports/{id}/send opravdu pošle e-mail klientovi (povinné recipientEmail, nepovinné emailSubject) a report tím přejde do stavu odesláno, odkud se stává podkladem faktury. U klienta s paušálem server odmítne odeslání s chybou 412, dokud nepotvrdíte upozornění polem acknowledgeRetainerWarnings: true.

Users (uživatelé)

Můj profil

curl -H "Authorization: Bearer vas_klic" \
  https://app.mujvykaz.cz/api/v1/users/me

Odpověď nese id, name, email, role, position, hourlyRate, currency, isActive, tracksTime, employmentType, avatarUrl a createdAt. currency je měna organizace, ve které je hourlyRate. Člen, který nemá zapnuté zobrazování vlastní sazby, dostane hourlyRate nula.

Moje statistiky

curl -H "Authorization: Bearer vas_klic" \
  https://app.mujvykaz.cz/api/v1/users/me/stats

Odpověď nese hodiny a částky za tento týden (thisWeek) a měsíc (thisMonth). Částky čtěte z amountByCurrency — součet po měnách výkazů, například {"CZK": 120000, "EUR": 45000} (koruny celé, eura v centech); měna s nulou v něm chybí. totalAmount je prostý součet přes všechny měny a zůstává jen kvůli kompatibilitě. currency je měna organizace.

Statistiky týmu

curl -H "Authorization: Bearer vas_klic" \
  https://app.mujvykaz.cz/api/v1/users/stats

Jen pro vlastníka, administrátora a manažera; manažer dostane lidi ze svého rozsahu. Každý člověk má v thisMonth stejně jako u Mých statistik amountByCurrency (součet po měnách) a totalAmount (prostý součet přes měny, jen kvůli kompatibilitě); currency je měna organizace. Manažer dostane částky jen z projektů svých klientů.

Členové týmu

Požadavek	K čemu	Kdo smí
GET /users	Seznam členů (role, sazby, typ vztahu, currency)	Všichni kromě člena; manažer vidí svůj tým
POST /users	Založit člena, pozvánka odejde e-mailem	Vlastník, administrátor, HR a manažer — role, kterou smí přidělit, je omezená stejně jako v aplikaci
PUT /users/{id}	Upravit člena	Cizí profil vlastník, administrátor a HR; vlastní jméno a pozici každý

Založení vyžaduje email a name; nepovinná jsou role, position, hourlyRate, hourlyCost, costPeriod, monthlyCost, costExempt, overheadCost, workSchedule, hoursPerDay, tracksTime, canPlanCapacity, employmentType, hireDate a departureDate. Roli Administrátor přidělí jen vlastník, HR přidělí HR, manažera a člena (ne účetní ani administrátora), manažer zakládá jen členy. Platí limit míst vašeho tarifu.

Úprava přijímá stejná pole a navíc isActive, costValidFrom a schedule (pracovní týden člověka). E-mail členu změnit nejde. HR nemění profil administrátora a vlastníka. Vlastní datum nástupu a konec spolupráce si nezmění nikdo, ani vlastník. costValidFrom říká, od kdy změna odměny platí: RRRR-MM je od zvoleného měsíce (ne budoucího), start je oprava od začátku; bez něj platí první vyplnění nákladu od začátku a každá další změna od tohoto měsíce. Zamčený měsíc se přes API nemění — nejdřív ho odemkněte přes zámek měsíce.

Tyto koncové body nepřijímají starý API klíč organizace — použijte osobní klíč. Viz Autentizace.

Časovač

GET, PUT a DELETE /timer ukládají a čtou stav časovače přihlášeného člověka. Používá je rozšíření pro Chrome, aby se časovač synchronizoval s webovou aplikací. PUT hlídá souběžnou změnu (chyba 409) a člen, který nesleduje čas, dostane 403.

Úkoly (tasks)

Modul Úkoly.

Kdo smí: všechny role. Vyžaduje tarif Starter nebo vyšší. Úkol upravuje jeho autor, řešitel nebo manažer.

Požadavek	K čemu
GET /tasks	Seznam úkolů
POST /tasks	Vytvořit úkol
GET /tasks/{id}	Detail úkolu včetně podúkolů a odpracovaných minut
PATCH /tasks/{id}	Upravit úkol
DELETE /tasks/{id}	Smazat úkol — navázané výkazy zůstanou, jen se od úkolu odpojí
GET /tasks/{id}/comments	Komentáře úkolu
POST /tasks/{id}/comments	Přidat komentář — {"body": "…"}, prostý text 1–5000 znaků

Seznam má parametry project_id, assignee_id (UUID, nebo me pro moje úkoly), status, include_done=false (skryje hotové, zrušené a pozastavené úkoly), limit a offset.

Vytvoření: povinné projectId a title; nepovinná taskListId, parentTaskId (podúkol), description, assigneeId, dueDate (RRRR-MM-DD), estimateMinutes, status a priority. Hodnoty status: todo, in_progress, on_hold, done, cancelled. Hodnoty priority: none, low, medium, high. Úprava přijímá stejná pole a navíc blockedReason (příznak Čeká na). Zmínky kolegů (@) v komentáři API nepodporuje.

Nepřítomnosti (absences)

Modul Nepřítomnosti. Vyžaduje tarif Business a v Nastavení → Nepřítomnosti → Správa absencí zapnutý Modul Absence.

Požadavek	K čemu	Kdo smí
GET /absences/types	Typy nepřítomnosti s ID	Všichni
GET /absences	Seznam žádostí	Cizí žádosti vidí jen vlastník, administrátor a HR; ostatní dostanou jen své
POST /absences	Podat žádost — vždy za sebe	Všichni
PATCH /absences/{id}	Schválit, zamítnout, zrušit nebo upravit žádost	Schvalovat a zamítat smí vlastník, administrátor a HR
GET /absences/balance	Zůstatek dovolené	Svůj každý, cizí jen ten, kdo má oprávnění
GET /absences/entitlements	Přehled ročních nároků	Vlastník, administrátor, HR
PUT /absences/entitlements	Nastavit roční nárok člena	Vlastník, administrátor, HR

Seznam žádostí má filtry user_id, type_id, status (pending, approved, rejected, cancelled), date_from, date_to, limit (1–200) a offset. Typ nepřítomnosti se nižším rolím maskuje (ochrana údajů o zdraví).

Žádost: povinné typeId, startDate, endDate (RRRR-MM-DD); nepovinné startHalf a endHalf (full, morning, afternoon), note a notifyUserIds (komu poslat vzkaz „nebudu tu“, nejvýš 20).

# Schválení
curl -X PATCH -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}' \
  https://app.mujvykaz.cz/api/v1/absences/{id}

PATCH rozlišuje pole action: approve, reject (povinný reviewNote s důvodem), cancel (smí žadatel i schvalovatel) a update (změna typu, dnů nebo poznámky u čekající žádosti). Vlastní žádost si neschválí ani vlastník.

Zůstatek má volitelné parametry user_id a year (2020–2030). Odpověď nese i pole mode — v ručním režimu evidence absencí vrací zůstatek nuly a podle mode to poznáte. Nárok se zadává po půldnech (entitlement 0–50); poměrnou část podle nástupu a převody z loňska dopočítá aplikace. Vlastní nárok si nenastaví ani HR.

Náklady (expenses)

Modul Náklady. Částky jsou v nejmenší jednotce měny klienta střediska (u nákladu bez střediska v měně organizace).

Kdo smí: všechny role — člen a HR vidí jen své náklady, manažer náklady svého rozsahu, vlastník, administrátor a účetní všechny. Ručně určený schvalovatel vidí navíc náklady střediska, které schvaluje. Zapisovat (založit, upravit, smazat náklad, nahrát a potvrdit doklad) smí jen ten, koho pustí volba firmy Kdo zapisuje náklady. Ostatní dostanou 403 s větou, komu náklad poslat.

Seznam, zápis, úprava a smazání

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "<uuid>", "categoryId": null, "description": "Licence Figma", "amount": 120000, "expenseDate": "2026-10-09", "supplierName": "Figma Inc."}' \
  https://app.mujvykaz.cz/api/v1/expenses

Požadavek	K čemu
GET /expenses	Seznam nákladů
POST /expenses	Zapsat náklad
PUT /expenses/{id}	Upravit náklad
DELETE /expenses/{id}	Smazat náklad
PUT /expenses/bulk-status	Hromadně schválit nebo vrátit náklady

Seznam má parametry project_id, category_id (UUID, nebo none), status (draft, approved, invoiced), date_from, date_to (RRRR-MM-DD), search (1–100 znaků, hledá v popisu i dodavateli) a limit (1–200).

Zápis: povinné projectId, categoryId, description, amount (nejméně 1) a expenseDate (RRRR-MM-DD). projectId a categoryId posílejte vždy — hodnota null znamená „bez střediska“ (obecný provoz firmy), resp. „bez kategorie“. Firma, která má zapnuté Vyžadovat kategorii u každého nákladu, náklad bez kategorie odmítne. Nepovinná pole: billableAmount (částka k přeúčtování klientovi — bez ní ji aplikace dopočítá z marže), isBillable, receiptUrl, notes a údaje z dokladu supplierName, supplierIco (IČO s kontrolním součtem) a vatAmount.

Nový náklad vznikne rovnou schválený, když ho smíte schválit (nebo má firma schvalování vypnuté), jinak jako koncept.

Úprava přijímá stejná pole, posílejte jen ta, která měníte. Vyfakturovaný náklad měnit ani mazat nejde, člen upravuje a maže jen vlastní koncepty. Schválený náklad upraví a smaže ten, kdo ho smí schválit (při vypnutém schvalování i autor). Náklad v zamčeném měsíci nebo před mezí Výkazy od server odmítne.

Hromadné schválení: {"ids": ["<uuid>"], "action": "approve"} nebo "action": "unapprove" (vrácení do konceptu), 1–100 ID. Smí kdokoli, kdo náklady schvaluje — vlastník, administrátor a účetní celou firmu, manažer náklady na střediscích svých klientů a ručně určený schvalovatel své středisko (bez nákladů vedení), viz Schvalování nákladů. Řádky, které schválit nesmíte, nebo v jiném stavu se tiše přeskočí — odpověď říká, kolik jich prošlo.

Schvalování nákladů

Nastavení schvalování — v aplikaci Nastavení → Sazby a náklady → Schvalování nákladů, viz Schvalování nákladů.

Požadavek	K čemu
GET /expenses/approval	Je schvalování zapnuté (enabled), smíte něco schválit (canApproveAny), co schvalujete z ručního přiřazení (mine). Vlastník a administrátor dostanou i seznam schvalovatelů (rules)
PUT /expenses/approval	Zapnout nebo vypnout schvalování a nastavit schvalovatele jednoho střediska

Kdo smí: číst každá role, měnit vlastník a administrátor klíčem s plným přístupem.

Tělo PUT: enabled (true / false) a nebo projectId s approverIds. projectId je středisko, null znamená obecný provoz firmy (náklady bez střediska). approverIds nahradí celý seznam schvalovatelů toho střediska (nejvýš 20 lidí, [] = zrušit). Schvalovatel musí být aktivní člen vaší organizace. Odpověď vrátí stav jako GET.

curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"projectId": null, "approverIds": ["<uuid>"]}' \
  https://app.mujvykaz.cz/api/v1/expenses/approval

Kdo zapisuje náklady

Volba firmy, kdo smí zakládat, upravovat a mazat náklady a nahrávat doklady — v aplikaci Nastavení → Sazby a náklady → Kdo zapisuje náklady, viz Kdo zapisuje náklady.

Požadavek	K čemu
GET /expenses/writers	Volba firmy (mode), smíte zapisovat vy (canWrite), a komu poslat doklad (writers — jména vedení a účetních)
PUT /expenses/writers	Změnit volbu — tělo {"mode": "all"}, "managers" nebo "finance"

all = všichni (výchozí), managers = vedení, účetní a manažeři, finance = jen vedení a účetní. Kdo smí: číst každá role, měnit vlastník a administrátor klíčem s plným přístupem.

Doklady k nákladům

Nahraný doklad (faktura, účtenka) aplikace přečte a připraví ke kontrole. Náklad z něj vznikne až potvrzením. Postup v aplikaci popisuje stránka Doklady k nákladům.

Kdo smí: každá role své doklady; cizí doklady vlastník, administrátor a účetní. Nahrát, přečíst, potvrdit a zahodit doklad smí jen ten, kdo podle volby firmy Kdo zapisuje náklady náklady zapisuje.

Požadavek	K čemu
GET /expenses/documents	Doklady čekající na kontrolu. Parametr all=true vrátí doklady celé firmy (jen vlastník, administrátor, účetní)
POST /expenses/documents	Nahrát a přečíst doklad
GET /expenses/documents/{id}	Detail dokladu — přečtená pole, upozornění a navržené středisko
POST /expenses/documents/{id}/confirm	Potvrdit doklad — vznikne náklad
DELETE /expenses/documents/{id}	Zahodit doklad, ze kterého ještě nevznikl náklad

Nahrání jde jako multipart/form-data s polem file:

curl -X POST -H "Authorization: Bearer vas_klic" \
  -F "file=@faktura.pdf" \
  https://app.mujvykaz.cz/api/v1/expenses/documents

Přijímá PDF, fotky JPG, PNG a WebP a e-faktury ISDOC (.isdoc, .isdocx), nejvýš 10 MB. Fotky HEIC server odmítne. E-fakturu ISDOC přečte přesně a bez AI, ostatní doklady přečte AI v rámci měsíčního limitu vašeho tarifu — na Free se doklad nahraje a vyplní ručně. Stejný soubor podruhé nahrát nejde: odpověď pak místo dokladu nese údaj o dřívějším nahrání. Nahrávání je omezené na 60 dokladů za 10 minut na člověka.

Potvrzení vytvoří náklad. Částky dokladu posílejte v nejmenší jednotce měny dokladu; náklad pro Ziskovost a převod do měny střediska spočítá aplikace.

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"projectId": "<uuid>", "categoryId": null, "description": "Nájem kanceláře", "expenseDate": "2026-10-01", "currency": "CZK", "base": 2000000, "vat": 420000, "total": 2420000}' \
  https://app.mujvykaz.cz/api/v1/expenses/documents/{id}/confirm

Povinná pole: projectId, categoryId, description, expenseDate (datum zdanitelného plnění — určuje měsíc nákladu), currency a base, vat, total (každé číslo, nebo null). Nepovinná: supplierName, supplierIco, documentNumber, variableSymbol, issueDate, dueDate, isBillable, billableAmount, notes, recurringExpenseId, customerIco a:

• splitMonths (1–24) — rozloží náklad do více měsíců, například roční předplatné do 12;
• splitCenters — rozdělí náklad na 2–10 středisek. Každý řádek nese projectId a buď percent, nebo amount; poslední řádek bez podílu dostane zbytek. Střediska musí účtovat ve stejné měně. S rozložením do měsíců ani s recurringExpenseId se rozdělení nekombinuje;
• amountOverride — náklad v měně střediska. Použijte ho, když automatický převod kurzem ČNB nejde (jiná měna než CZK, EUR a USD), nebo když znáte skutečnou částku například z výpisu z účtu.

Fakturu vystavenou na jinou firmu (IČO odběratele se liší od IČO vaší organizace) server nepotvrdí a vrátí 400. Když bylo IČO odběratele přečtené špatně, pošlete správné v poli customerIco — viz Faktura na jinou firmu.

Více v Rozložení do měsíců a rozdělení na střediska. Úspěch vrátí 201. recurringExpenseId přiřadí doklad k pravidelné položce — smí jen vlastník, administrátor a účetní.

Pravidelné položky

Nájem, leasing, mobily, předplatné — položku zadáte jednou a aplikace za ni každý měsíc založí řádek nákladu. Viz Pravidelné položky.

Kdo smí: vlastník, administrátor a účetní.

Požadavek	K čemu
GET /expenses/recurring	Mřížka položek s historií částky a řádky po měsících. Parametry from a to ve tvaru RRRR-MM (výchozí poslední čtyři měsíce)
POST /expenses/recurring	Založit položku
PUT /expenses/recurring/{id}	Změnit položku — podle pole action
DELETE /expenses/recurring/{id}	Smazat položku, která nemá skutečné náklady

Založení: povinné name, projectId (nebo null = obecný provoz), categoryId (nebo null), mode, amount a startMonth (RRRR-MM). mode je estimate (odhad — čeká na doklad), contract (pevná částka podle smlouvy) nebo annual (platba jednou ročně, rozloží se do 12 měsíců). Nepovinná: supplierName, supplierIco, backfill (doplnit i minulé nezamčené měsíce), skipMonths (měsíce, za které řádek nezakládat) a amountCurrency (měna, ve které částku posíláte — server ji ověří proti měně položky, aby eura v centech neskončila jako koruny).

PUT rozlišuje pole action:

action	Další pole	Co udělá
update	name, supplierName, supplierIco, projectId, categoryId, mode, applyToPast	Změní položku; středisko, kategorie a způsob se propíšou do nepřepsaných řádků od tohoto měsíce
amount_from	validFrom, amount, amountCurrency	Nová částka od měsíce dál
month_amount	month, amount, amountCurrency	Skutečná částka jednoho měsíce
end	endMonth	Položka platí do měsíce včetně
reopen	—	Ukončená položka platí zase bez konce
skip_month	month	Měsíc bez nákladu
unskip_month	month	Vrátí náklad měsíce

Zamčený měsíc přes API nezmění nikdo — nejdřív ho odemkněte.

Balíček pro účetní

Měsíční ZIP s doklady, přehledem v Excelu a souborem pro Money S3. Viz Balíček pro účetní.

Kdo smí: vlastník, administrátor a účetní. Ke čtení stačí klíč jen pro čtení.

Požadavek	K čemu
GET /expenses/accounting-package/summary?month=RRRR-MM	Co by balíček za měsíc obsahoval: počty dokladů, náklady bez dokladu, doklady ke kontrole a střediska bez kódu
GET /expenses/accounting-package?month=RRRR-MM	Stažení balíčku jako ZIP. Nepovinný parametr locale (cs, sk, en) určuje jazyk přehledu
PUT /expenses/accounting-package/settings	Účetní program a kódy středisek — vyžaduje plný přístup

Měsíc nesmí být budoucí. Stažení je omezené na 20 balíčků za hodinu na člověka a balíček větší než 3,8 GB server odmítne (413) — v tom případě napište podpoře.

Nastavení: pole system (money_s3, nebo null pro žádný program) a codes — seznam {"projectId": "<uuid>", "code": "KANC"}, kde projectId: null je obecný provoz firmy a code: null kód smaže. Kód střediska má nejvýš 10 znaků a posílejte aspoň jedno z polí system, codes.

Import nákladů z účetnictví

Import nákladů z knihy přijatých faktur nebo z tabulky. Postup v aplikaci popisuje Import z účetnictví.

Kdo smí: vlastník, administrátor a účetní. Náhled stačí volat klíčem jen pro čtení, zápis vyžaduje plný přístup.

Požadavek	K čemu
POST /expenses/import/preview	Náhled: co se s každým řádkem stane. Nic nezapisuje
POST /expenses/import	Zápis — vrátí batchId pro vrácení importu
GET /expenses/imports	Posledních 20 importů a zda jdou vrátit (canUndo)
POST /expenses/imports/{id}/undo	Vrátit import (do 30 dní)

Tělo náhledu i zápisu je totéž: pole rows (1–2 000 řádků) a volby převodů. Řádek nese:

Pole	Význam
line	Číslo řádku — povinné a jedinečné, slouží k hláškám
date	Datum zdanitelného plnění RRRR-MM-DD — povinné
supplierName, supplierIco, documentNumber, description, notes	Údaje o dokladu
costCenter	Kód střediska v účetnictví, nebo název střediska
category	Název kategorie
base, vat, total	Základ, DPH a celkem v hlavních jednotkách měny (koruny, eura — ne haléře ani centy); nejméně jedna částka, nikdy záporná
currency	Třípísmenný kód měny

Volby: costCenterMap (hodnota střediska ze souboru → ID střediska, general = obecný provoz, skip = přeskočit), categoryMap (hodnota kategorie → ID, nebo none), include (čísla řádků, které se mají založit i jako duplicita) a recurring (číslo řádku → ID pravidelné položky, nebo none). Zápis přijímá navíc fileName (název zdroje do historie importů) a saveMappings.

Náhled vrací pro každý řádek akci — create (založí se), recurring (doplní pravidelnou položku), duplicate (nezaloží se) nebo skip (přeskočí se) — s důvodem, a seznam středisek a kategorií, které nepoznal. Zápis vrátí 201 a vytvoří schválené, nefakturovatelné náklady bez souboru dokladu. Řádky v zamčeném měsíci, před mezí Výkazy od a v jiné měně, než účtuje středisko, přeskočí. Duplicity (stejný doklad podle IČO a čísla dokladu, nebo stejný dodavatel, den a částka) se nezaloží, ledaže je číslo jejich řádku v include. Vrácení smaže náklady z importu; co od importu někdo změnil, je na faktuře nebo v zamčeném měsíci, zůstane a vypíše se v poli kept.

Odměny a náklady lidí

Mzdové údaje kolegů — manažer k nim přístup nemá.

Požadavek	K čemu	Kdo smí
GET /bonuses	Odměny nad rámec měsíční mzdy	Vlastník, administrátor, HR, účetní
POST /bonuses	Zapsat odměnu	Totéž
PUT /bonuses/{id}	Upravit odměnu	Totéž
DELETE /bonuses/{id}	Smazat odměnu	Totéž
GET /users/{id}/cost-history	Historie odměny člena po měsících	Totéž
GET /users/{id}/cost-recalc	Náhled přepočtu nákladovky výkazů	Vlastník, administrátor, HR
POST /users/{id}/cost-recalc	Provést přepočet	Totéž
GET /cost-rules	Pravidla rozpisu nákladů do středisek	Vlastník, administrátor, HR, účetní
PUT /cost-rules	Uložit pravidla	Vlastník, administrátor

Odměny

GET /bonuses má nepovinné parametry user_id, from a to (RRRR-MM-DD); výchozí je letošní rok. Odpověď nese currency (měna organizace) a seznam items. Zápis: povinné userId, amount, paidOn (RRRR-MM-DD) a label (1–100 znaků), nepovinná note. Částka je v měně organizace. Odměna je nákladem měsíce výplaty. PUT posílá celou odměnu (amount, paidOn, label, note). HR a účetní si vlastní odměnu nezapíšou, neupraví ani nesmažou.

Historie odměny a přepočet výkazů

Viz Historie odměn.

GET /users/{id}/cost-history vrátí řádky s platností od měsíce (nejnovější první): měsíční odměnu nebo hodinovou nákladovku, úvazek a podmínky rozpisu. Změnu odměny s platností od měsíce uložíte přes PUT /users/{id} s polem costValidFrom.

Přepočet použijete, když výkazy vznikly s nákladovkou, která se později ukázala jako chybná (například úvazek 8 hodin místo 4): GET /users/{id}/cost-recalc?from_month=start ukáže, kolik výkazů se změní a o kolik, POST s tělem {"fromMonth": "2026-08"} přepočet provede. Hodnota from_month a fromMonth je RRRR-MM, nebo start (od začátku). Vlastní náklad mění jen vlastník a administrátor. Výkazy v zamčeném měsíci přes API přepočítat nejde.

Rozpis nákladů do středisek

Pravidla říkají, kam firma posílá části odměn, které nejsou přímá práce. V aplikaci je najdete v Nastavení → Sazby a náklady → Kam patří náklady, viz Kam patří náklady.

GET /cost-rules vrátí pravidla platná dnes, jejich historii a jména středisek, na která odkazují. PUT /cost-rules uloží celou sadu pravidel s platností od měsíce — nejdřív si pravidla načtěte, upravte a pošlete zpět celá:

{
  "validFrom": "2026-10",
  "rules": {
    "unlogged": {"kind": "dissolve"},
    "holiday": {"kind": "dissolve"},
    "absence": {"kind": "dissolve"},
    "absenceTypes": {},
    "bonus": {"kind": "dissolve"},
    "noWork": {"kind": "project", "projectId": "<uuid>"},
    "expenseNoProject": {"kind": "unassigned"},
    "overhead": {"key": "none", "projectIds": []}
  }
}

Pravidlo	Co určuje
unlogged	Nevykázané hodiny
holiday	Svátky ve všední den
absence	Volno; absenceTypes přidává výjimky podle typu nepřítomnosti
bonus	Odměny nad rámec mzdy
noWork	Člověk, který v měsíci nevykázal nic
expenseNoProject	Náklady bez střediska
overhead	Režie na klienty — key je none (nerozdělovat), hours (podle vykázaných hodin), directCost (podle mzdových nákladů) nebo revenue (podle tržeb z výkazů) a projectIds jsou interní střediska, ze kterých se režie rozděluje

Cíl pravidla je {"kind": "dissolve"} (rozpustit na střediska, kde člověk pracoval, podle jeho hodin), {"kind": "project", "projectId": "<uuid>"} (poslat do střediska) nebo {"kind": "unassigned"} (Nezařazeno). U noWork a expenseNoProject jde jen středisko nebo Nezařazeno. Volitelné pole absenceCost nastavuje náklad volna pro firmu. validFrom je start (od začátku), nebo měsíc RRRR-MM (ne budoucí); bez něj platí aktuální měsíc. Zamčený měsíc se přes API nemění.

Ziskovost a kontrola financí

Požadavek	K čemu	Kdo smí
GET /profitability	Souhrn Ziskovosti za období	Vlastník, administrátor, účetní a manažer — manažerovi se nákladová strana nevrací
GET /finance-check	Kontrola financí — kde chybí nebo nesedí nastavení peněz	Vlastník, administrátor, účetní
GET /controlling?month=RRRR-MM	Závazky klientů za měsíc	Vlastník, administrátor, účetní a manažer; tarif Business

Souhrn Ziskovosti má parametry date_from, date_to (RRRR-MM-DD), client_ids (ID klientů oddělená čárkou) a cost_view. Odpověď nese currency (měna organizace) a souhrn ve dvou pohledech: dle výkazů (hodiny × sazba) a dle reality (ceny paušálů, faktury, reporty, pevné ceny). cost_view=direct (výchozí) počítá přímé náklady, cost_view=full přidává podíl režie interních středisek rozdělený na klienty podle pravidel v Kam patří náklady. S filtrem klienta full přičte jeho podíl režie; bez filtru zůstanou Náklady celkem stejné a odpověď řekne, kolik režie šlo na klienty a v kterých měsících nebylo na koho ji rozdělit. Více v Ziskovosti.

GET /controlling bere měsíc ve tvaru RRRR-MM (výchozí aktuální, budoucí nejde) a vrací paušály, zakázky za pevnou cenu a projekty s hodinovým rozpočtem a seznam řádků ke kontrole. Manažer dostane jen své klienty a bez nákladů a marže. Viz Controlling.

Uzávěrky a zámek měsíce

Viz Uzávěrky a Zámek měsíce.

Kdo smí: uzávěrky a externí faktury vlastník, administrátor, účetní a manažer (jen své klienty). Stav zámku měsíce vidí všechny role, zamyká a odemyká ho vlastník, administrátor a účetní.

Požadavek	K čemu
GET /closures	Otevřená období klientů k uzavření (klient × měsíc). Parametry months (2026-08,2026-07), state (ready, blocked), limit (≤ 200)
GET /closures/lock	Stav zámku měsíce; s previewMonth=RRRR-MM i náhled, co by zamčení zasáhlo
POST /closures/lock	Zamknout nebo dočasně odemknout měsíc
GET /closures/lock/requests	Žádosti o odemčení měsíce pro jednoho člověka a přehled „kdo zapisuje po termínu“
POST /closures/lock/requests	Požádat o odemčení, žádost stáhnout, schválit, zamítnout nebo odemčení ukončit
GET /closures/external/preview	Náhled externí uzávěrky — parametry client_id a month
GET /closures/external	Seznam externích faktur — status (active, cancelled), client_id, limit (≤ 500)
POST /closures/external	Uzavřít měsíc klienta externí fakturou
GET /closures/external/{id}	Detail externí faktury
PATCH /closures/external/{id}	Upravit externí fakturu
GET /closures/external/{id}/history	Historie externí faktury
POST /closures/external/{id}/cancel	Stornovat externí fakturu — povinný reason (3–500 znaků)
POST /closures/external/{id}/attach-retainer	Připsat paušál do existující externí faktury

Zámek měsíce: {"action": "lock", "month": "2026-09"} zamkne měsíc a všechny dřívější, {"action": "unlock", "month": "2026-09", "untilDay": "2026-10-05"} ho dočasně odemkne (po uplynutí se zamkne sám). Natrvalo odemknout jde jen v aplikaci. Do zamčeného měsíce se přes API nezapisuje ani s potvrzením — cesta je odemčení.

Odemčení měsíce pro jednoho člověka

Člověk může požádat o odemčení zamčeného měsíce jen pro své výkazy. Schvaluje vlastník, administrátor nebo účetní. Odemčení platí do konce dne schválení. Postup a pravidla jsou v Odemčení měsíce pro jednoho člověka.

GET /closures/lock/requests vrací žádosti a souhrn po lidech (kolik žádostí, kolik schváleno, kolik výkazů se během odemčení zapsalo). Vlastník, administrátor a účetní vidí celou organizaci, ostatní jen své žádosti. Parametry: status (pending, approved, rejected, cancelled), userId (UUID člověka) a months (za kolik měsíců zpět, 1–36, výchozí 12).

POST /closures/lock/requests přijímá pole action. Zápis vyžaduje klíč s plným přístupem:

action	Co dělá	Další pole	Kdo smí
request	Požádá o odemčení, vždy jen pro sebe. Vrací 201 a jména schvalovatelů	months (pole RRRR-MM, 1–12 měsíců) nebo month, reason (3–500 znaků, povinný)	Člen, manažer a HR, kteří vykazují čas
cancel	Stáhne vlastní čekající žádost	id	Autor žádosti
approve, reject	Schválí nebo zamítne celou žádost, i když obsahuje víc měsíců	id, note (nepovinná poznámka pro žadatele)	Vlastník, administrátor, účetní. Vlastní žádost ne
end	Ukončí platné odemčení dřív	id	Vlastník, administrátor, účetní

Na jeden měsíc čeká nejvýš jedna žádost a za 24 hodin jde podat nejvýš 5 žádostí (žádost na víc měsíců se počítá jednou). Schválené odemčení platí i pro zápis vlastních výkazů přes API.

Externí faktura je „skutečně vyfakturováno mimo aplikaci“ — doklad za klienta a kalendářní měsíc, který uzavře schválené fakturovatelné výkazy. Sazby ani hodiny výkazů se nemění. Zápis přijímá clientId, month (RRRR-MM), invoicedAmount (jen za práci), currency, nepovinné passThroughAmount (náklady mimo aplikaci na téže faktuře), invoiceNumber, issuedAt, note, parts (co doklad uzavírá — práci mimo paušál a vybrané paušály), lines (rozpad po střediscích), includeExpenses a withoutWork (faktura ke středisku bez výkazů). Částky jsou v měně klienta. Doporučený postup je napřed zavolat náhled.

Paušály (retainers)

Modul Paušály klientů. Vyžaduje tarif Business.

Kdo smí: vlastník, administrátor, účetní a manažer (jen své klienty). Ceny paušálů vidí podle role jen finanční role a manažer u svých klientů. Zápisy (uzavření období) smí vlastník, administrátor a účetní.

Požadavek	K čemu
GET /retainers	Aktivní paušály s aktuálním obdobím
GET /retainers/{clientId}	Paušály jednoho klienta — období, historie, čerpání a přebytek
GET /retainers/open-periods	Otevřená období paušálů, která ještě nejsou uzavřená
GET /retainers/close-period?retainer_id=…&month=RRRR-MM	Náhled uzavření období
POST /retainers/close-period	Uzavřít období — {"retainerId": "<uuid>", "month": "2026-09"}
POST /retainers/refill-period	Doplnit do už uzavřeného období hodiny, které přibyly pozdě — retainerId, month

Uzavřením se období zmrazí: uloží se vyčerpané hodiny, cena i dohoda o přesahu, takže pozdější změny sazeb ho nepřepíšou. Období, ve kterém vznikly placené vícepráce, přes API uzavřít nejde — o faktuře za ně rozhoduje člověk na kartě klienta, server takové volání odmítne chybou 409. Viz Čerpání a uzavření.

Allocations (plánování kapacit)

Naplánovaná práce z modulu Plánování kapacit. Vyžaduje plán Business a v Nastavení → Nepřítomnosti → Správa absencí zapnutý Modul Absence.

Tvar polí

Tělo požadavku je v camelCase (minutesPerDay), ale odpověď tohoto zdroje je v snake_case (minutes_per_day, start_date, planned_minutes).

Získání plánu a kapacity

curl -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/allocations?date_from=2026-08-01&date_to=2026-08-31"

Povinné parametry: date_from, date_to (YYYY-MM-DD, rozsah max ~6 měsíců). Volitelně user_id, project_id. Vrací naplánovanou práci, kapacitu lidí (kolik mají volno) a souhrn na projekt. Ke čtení stačí klíč jen pro čtení — plán vidí všechny role.

Můj plán

curl -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/allocations/my-plan?date_from=2026-08-01&date_to=2026-08-31"

Vlastní potvrzený plán se zbývajícími minutami (naplánováno − už vykázáno).

Naplánování práce

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"userId": "...", "projectId": "...", "minutesPerDay": 240, "startDate": "2026-08-03", "endDate": "2026-08-07", "status": "confirmed"}' \
  https://app.mujvykaz.cz/api/v1/allocations

Povinná pole: userId, projectId, minutesPerDay, startDate, endDate. Nepovinná: taskId, activityId, startTime (HH:MM, pevný čas bloku), status (tentative — návrh, nebo confirmed), billable a note. Zápis vyžaduje klíč s plným přístupem. Sám sobě plánuje každý, kdo vykazuje čas. Ostatním plánuje vlastník, administrátor, manažer (jen na projekty svých klientů) nebo člen s oprávněním Plánovač kapacit. Kolize s absencí zápis neblokuje — vrátí se jako varování v poli conflicts.

Opakující se plán založíte přidáním pole recurrence:

  -d '{"userId": "...", "projectId": "...", "minutesPerDay": 240, "startDate": "2026-08-03", "endDate": "2026-08-07", "recurrence": {"intervalWeeks": 1, "until": "2026-12-31"}}'

intervalWeeks je 1 (každý týden) nebo 2 (každé 2 týdny), until je nepovinné (bez něj se opakuje napořád).

Úprava a smazání

# Úprava (body: seriesScope = this | following | all u výskytu série)
curl -X PUT -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"status": "confirmed"}' \
  https://app.mujvykaz.cz/api/v1/allocations/{id}

# Smazání (query: series_scope = this | following | all u výskytu série)
curl -X DELETE -H "Authorization: Bearer vas_klic" \
  "https://app.mujvykaz.cz/api/v1/allocations/{id}?series_scope=following"

U výskytu opakující se série volí seriesScope / series_scope rozsah: this (jen tento výskyt), following (tento a další), all (celá série). Výkazy zapsané podle plánu zůstávají.

Narozeniny

Hromadné nahrání narozenin členů týmu (den a měsíc, bez roku).

Kdo smí: vlastník, administrátor a HR.

Požadavek	K čemu
GET /birthdays	Kdo má narozeniny vyplněné — email, name, day, month
POST /birthdays	Nahrát narozeniny — {"birthdays": [{"email": "jana@firma.cz", "day": 14, "month": 3}]}

Členové se párují podle e-mailu, ne podle jména. Jedno nahrání zvládne nejvýš 500 položek. Opakované nahrání téže tabulky nic nezkazí — existující datum se přepíše. Člen, který v organizaci není, import nezastaví: odpověď vrátí počty saved a failed, seznam uložených e-mailů a v errors důvod u každého, který neprošel.

AI dotaz

curl -X POST -H "Authorization: Bearer vas_klic" \
  -H "Content-Type: application/json" \
  -d '{"query": "Kolik hodin jsme odpracovali tento měsíc?"}' \
  https://app.mujvykaz.cz/api/v1/ai

POST /ai položí dotaz nad daty organizace jako AI Reporty. Pole query má 1–1000 znaků. Odpověď nese text, data a použitý SQL dotaz; na otázku, kterou z dat nejde spočítat, odpoví poctivým odmítnutím (refusal: true).

Kdo smí: vlastník, administrátor, účetní a manažer. Dotaz data jen čte, proto ho smí položit i klíč Pouze čtení. Čerpá limit AI dotazů organizace jako dotaz v aplikaci; když má organizace AI funkce vypnuté, nebo je limit vyčerpaný, odpověď vrátí důvod.

Hromadný upsert klientů a projektů

Hromadné zakládání a aktualizace klientů a projektů je dnes dostupné jen z aplikace přes tlačítko Import CSV (párování podle názvu, prázdné buňky se ignorují, max 500 záznamů, manager scope se vynucuje). REST endpoint pro něj zatím není.

Stránkování

Seznam výkazů (/time-entries) a úkolů (/tasks) stránkuje dvěma parametry:

Parametr	Výchozí	Popis
limit	100	Kolik záznamů vrátit (nejvýš 500)
offset	0	Kolik záznamů přeskočit

Odpověď neobsahuje celkový počet. Když vrátí méně záznamů, než je limit, máte všechno.

Ostatní seznamy mají vlastní strop, uvedený u příslušné oblasti výše: náklady limit do 200, nepřítomnosti limit do 200 a offset, otevřená období limit do 200, externí faktury limit do 500.