API přehled

MujVykaz poskytuje REST API v1 pro programový přístup k hlavním funkcím aplikace. API je součástí tarifu Starter a vyšších.

Tarif a zkušební doba

Zkušební doba má funkce tarifu Business, takže API v ní funguje. Organizace na tarifu Free — typicky po skončení zkušební doby — dostane na každý požadavek chybu 403 s vysvětlením a nový klíč si nevytvoří. Klíče ani připojení se nemažou: po přechodu na vyšší tarif (vlastník nebo administrátor v Nastavení → Tarif a platby) fungují zase.

Základní informace

Parametr	Hodnota
Base URL	https://app.mujvykaz.cz/api/v1
Verze	v1
Formát	JSON
Autentizace	Osobní API klíč v hlavičce Authorization: Bearer …
Rate limit	120 požadavků za minutu na jeden klíč (MCP server má vlastní limit 60 za minutu)
OpenAPI spec	https://app.mujvykaz.cz/api/v1/openapi

Autentizace

Každý požadavek musí obsahovat API klíč v hlavičce Authorization, před klíčem slovo Bearer:

curl -H "Authorization: Bearer vas_api_klic" \
  https://app.mujvykaz.cz/api/v1/time-entries

API klíče si vytvoříte ve svém nastavení: avatar vpravo nahoře → Nastavení → Kalendář a AI asistenti → Osobní API klíče. Více v Autentizace.

Co API pokrývá

Pro každou oblast najdete cesty, oprávnění a příklady v Endpointy. Všechny cesty jsou pod /api/v1.

Oblast	Hlavní cesty	Kdo smí	Tarif
Výkazy práce	/time-entries, /time-entries/{id}, /time-entries/bulk-status	Všechny role; člen a HR své, manažer svůj rozsah; účetní výkazy nezakládá
Projekty	/projects, /projects/{id}	Čtení všechny role (člen a HR bez peněz); zápis vlastník, administrátor, manažer u svých klientů; mazání vlastník a administrátor
Klienti	/clients, /clients/{id}	Čtení všechny role kromě člena; zápis vlastník, administrátor, manažer
Karta klienta	/clients/{id}/contacts, /clients/{id}/activities	Vlastník, administrátor, manažer, účetní	Starter+
Typy práce, kategorie nákladů	/activities, /expense-categories	Čtení všichni; zápis vlastník a administrátor, manažer podává návrh
Úkoly	/tasks, /tasks/{id}, /tasks/{id}/comments	Všechny role	Starter+
Členové týmu	/users, /users/me, /users/me/stats, /users/stats, /users/{id}	Podle role, viz Users
Narozeniny	/birthdays	Vlastník, administrátor, HR
Nepřítomnosti	/absences, /absences/{id}, /absences/types, /absences/balance, /absences/entitlements	Všechny role; schvalování a nároky vlastník, administrátor, HR	Business+
Plán kapacit	/allocations, /allocations/{id}, /allocations/my-plan	Čtení všechny role; plánování sám sobě každý, ostatním manažer a Plánovač kapacit	Business+
Náklady	/expenses, /expenses/{id}, /expenses/bulk-status	Všechny role podle rozsahu; zápis podle volby firmy Kdo zapisuje náklady; schvalování vlastník, administrátor, účetní, manažer u svých klientů a ručně určený schvalovatel
Kdo zapisuje a schvaluje náklady	/expenses/writers, /expenses/approval	Čtení všechny role; změna vlastník a administrátor
Doklady k nákladům	/expenses/documents, /expenses/documents/{id}, /expenses/documents/{id}/confirm	Každá role své doklady, cizí vlastník, administrátor, účetní
Pravidelné položky	/expenses/recurring, /expenses/recurring/{id}	Vlastník, administrátor, účetní
Balíček pro účetní	/expenses/accounting-package, …/summary, …/settings	Vlastník, administrátor, účetní
Import nákladů	/expenses/import, /expenses/import/preview, /expenses/imports, /expenses/imports/{id}/undo	Vlastník, administrátor, účetní
Odměny a náklady lidí	/bonuses, /bonuses/{id}, /users/{id}/cost-history, /users/{id}/cost-recalc, /cost-rules	Vlastník, administrátor, HR, účetní (pravidla a přepočet užší)
Ziskovost a kontrola	/profitability, /finance-check, /controlling	Vlastník, administrátor, účetní; Ziskovost a Controlling i manažer (bez nákladů)	Controlling Business+
Klientské reporty	/client-reports, /client-reports/{id}, /client-reports/{id}/send	Vlastník, administrátor, účetní, manažer u svých klientů
Faktury	/invoices, /invoices/{id}, /invoices/from-report, /invoices/status, /invoices/{id}/cancel	Vlastník, administrátor, účetní, manažer u svých klientů
Uzávěrky a zámek měsíce	/closures, /closures/lock, /closures/external…	Vlastník, administrátor, účetní, manažer u svých klientů
Paušály	/retainers, /retainers/{clientId}, /retainers/open-periods, /retainers/close-period, /retainers/refill-period	Vlastník, administrátor, účetní, manažer u svých klientů	Business+
AI dotaz	/ai	Vlastník, administrátor, účetní, manažer
Časovač	/timer	Každý, kdo sleduje čas (pro rozšíření Chrome)

U každého zápisu platí navíc rozsah klíče: klíč Pouze čtení zápis odmítne.

Formát dat

• Pole v tělech požadavků i v odpovědích jsou většinou v camelCase (projectId, durationMinutes). Výjimkou jsou těla požadavků na kontakty a historii klienta (is_primary, due_at) a odpovědi plánování kapacit (minutes_per_day, planned_minutes).
• Parametry v URL jsou v snake_case (project_id, client_id), u několika novějších koncových bodů v camelCase (previewMonth).
• ID jsou UUID.
• Data jsou ve tvaru RRRR-MM-DD, měsíce RRRR-MM.
• Čas je v minutách.
• Částky jsou celá čísla v nejmenší jednotce měny: CZK v celých korunách, EUR a USD v centech. Výjimkou je import nákladů, který bere částky v hlavních jednotkách (koruny, eura).
• Výkaz, faktura, náklad a projekt mají částky v měně klienta a nesou ji v poli currency. U klienta znamená prázdné currency měnu organizace.
• Sazby a náklady lidí, odměny a ceník typů práce jsou v měně organizace. Tu vrací pole currency u GET /users/me a GET /users.
• Součty přes víc měn API nesčítá do jednoho čísla — statistiky vrací rozpad amountByCurrency, viz Endpointy.
• Pole, která endpoint nezná, server bez chyby zahodí.

Formát odpovědí

Úspěšná odpověď nese výsledek v poli data:

{
  "data": [...]
}

Seznamy, které stránkování nabízejí, se stránkují parametry limit a offset a odpověď u nich neobsahuje celkový počet záznamů — viz Stránkování.

Chybové odpovědi

Chyba vrací popis v poli error:

{
  "error": "Popis chyby"
}

HTTP status kódy:

Kód	Význam
200	OK
201	Vytvořeno
202	Přijato — návrh položky číselníku čeká na schválení administrátorem
400	Chyba validace
401	Neautorizováno (chybí, je neplatný, odvolaný nebo vypršelý API klíč)
403	Nedostatečná oprávnění (role, klíč jen pro čtení, deaktivovaný účet), nebo organizace nemá tarif s API
404	Nenalezeno (u faktur také vypnutý modul Fakturace)
409	Konflikt se současným stavem dat
412	Chybí předpoklad — například faktura z reportu, který ještě nebyl odeslán klientovi
413	Nahraný soubor je příliš velký
429	Rate limit překročen (hlavička Retry-After řekne, za kolik sekund to zkusit znovu)

OpenAPI specifikace

Specifikace API je veřejně dostupná ve formátu OpenAPI 3.0:

https://app.mujvykaz.cz/api/v1/openapi

Můžete ji importovat do nástrojů jako Postman, Insomnia nebo Swagger UI.

Co ve specifikaci zatím chybí

Specifikace zatím neobsahuje některé novější koncové body: doklady k nákladům, pravidelné položky, balíček pro účetní, import nákladů, narozeniny, hromadnou změnu stavu výkazů, profil a statistiky členů a časovač. Ty popisuje stránka Endpointy.