MyInvoice MyInvoice.cz Manuál
Stáhnout PDF Zpět na hlavní stránku

41. REST API (automatizace a integrace)

MyInvoice.cz nabízí veřejné REST API pro integraci s e-shopy, CRM, Make/Zapier a vlastními skripty. API používá Personal Access Tokens (PAT) v hlavičce Authorization.

Dokumentační rozhraní

K dispozici jsou tři varianty stejné dokumentace nad jedním OpenAPI specem (navzájem se prolinkují v horní liště):

URLNástrojPoužití
/api/docsSwagger UI„Try it out" — vlož API token (Authorize) a volej endpointy přímo z prohlížeče
/api/referenceRedocPretty static reference, 3-sloupcový layout, lepší typografie pro čtení
/api/scalarScalarModerní reference s vestavěným API klientem a fulltext vyhledáváním
/api/openapi.yamlRaw OpenAPI 3.1Import do Postmana, Insomnie, Zapier Custom App, Make HTTP modulu

41.1 Vytvoření tokenu

  1. Systém → API tokeny (admin) nebo profil uživatele.
  2. Klikni Nový token, vyplň:
  1. Po vytvoření zobrazíme plain-text token (mi_pat_…) — jen jednou. Ulož ho do password manageru, zpětně už ho nezobrazíme.

Samotné přihlášení pomocí MFA nestačí: vytvoření PAT vždy vyžaduje nový účelový step-up, pokud má účet passkey nebo TOTP. Proof pro jinou operaci ani odemčení zamčené PWA token nevytvoří. PAT je bearer credential a serverový zámek browserové session se na něj nevztahuje; chraň jej vlastní expirací, minimálním scopem a včasnou revokací.

41.2 Použití tokenu

curl -H "Authorization: Bearer mi_pat_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
     https://myinvoice.cz/api/v1/auth/api-me

Response:

{
  "user":     { "id": 1, "email": "you@example.com", "name": "Petr", "role": "admin" },
  "supplier": { "id": 1, "company_name": "Acme s.r.o.", "display_name": "Acme" },
  "auth_method": "bearer",
  "token":    { "id": 42, "name": "Make integrace", "prefix": "mi_pat_abcd", "scope": "read_write", "expires_at": null }
}

Příklady

Seznam faktur za leden 2026:

curl -H "Authorization: Bearer mi_pat_…" \
     "https://myinvoice.cz/api/v1/invoices?from=2026-01-01&to=2026-01-31"

Vytvoření klienta:

curl -X POST https://myinvoice.cz/api/v1/clients \
     -H "Authorization: Bearer mi_pat_…" \
     -H "Content-Type: application/json" \
     -d '{
       "company_name": "Nový klient s.r.o.",
       "ic": "12345678",
       "street": "Hlavní 1",
       "city": "Praha",
       "zip": "11000",
       "country_id": 1
     }'

Označení faktury jako zaplacené:

curl -X POST https://myinvoice.cz/api/v1/invoices/123/mark-paid \
     -H "Authorization: Bearer mi_pat_…" \
     -H "Content-Type: application/json" \
     -d '{"paid_at": "2026-05-10"}'

41.3 Verzování

41.4 Rate limity

Každá bearer-authed response vrací tyto headers, ať si můžeš self-throttle před tím, než narazíš na 429:

X-RateLimit-Limit:     600         (limit v aktuálním okně)
X-RateLimit-Remaining: 587         (kolik volání ti ještě zbývá)
X-RateLimit-Reset:     42          (sekundy do reset countru)

Doporučujeme klienta s retry-with-backoff (axios-retry, Retry-After-aware) + sledovat X-RateLimit-Remaining a brzdit, když klesá pod ~10 %.

41.5 Multi-supplier

Pokud má účet víc firem (dodavatelů), máš dvě možnosti:

Token bound na supplier_id (doporučeno)Token globální
Token operuje vždy v kontextu této firmy.Klient pošle hlavičku X-Supplier-Id: <id> u každého requestu.
Hlavička X-Supplier-Id se ignoruje.Bez hlavičky = výchozí firma.
Token nemůže „skočit“ do jiné firmy = bezpečnější.Flexibilnější pro power-user skripty.

41.6 Scopes

ScopePovolené metody
readGET, HEAD
read_writevšechny (POST, PUT, PATCH, DELETE)

Volání s nedostatečným scopem vrátí 403 insufficient_scope.

41.7 Chybové odpovědi

Všechny chyby v unifikovaném formátu:

{ "error": { "code": "validation_failed", "message": "Pole 'name' je povinné." } }
KódVýznam
unauthenticated / invalid_tokenChybí nebo neplatný token
insufficient_scopeToken nemá read_write
validation_failedTělo neprošlo validací
not_foundZdroj neexistuje (nebo nepatří aktuálnímu supplier-ovi)
rate_limitedPřekročen limit (viz Retry-After)

41.8 Nastavení dodavatele a číslování dokladů přes API

Veřejný subset nastavení dodavatele jde měnit tokenem se scope read_write (uživatel tokenu musí být admin):

curl -X PUT https://mojefirma.example/api/v1/settings/supplier/invoice-counter \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "type": "invoice", "next_number": 42 }'
# → { "type": "invoice", "next_number": 42, "counter": 41,
#     "period": "202607", "preview": "2607042" }

Counter jde i snížit; pokud by nové číslo kolidovalo s už vystaveným dokladem, vystavení se samoopravně posune na první volné číslo — duplicitní číslo nikdy nevznikne. Volitelné date (YYYY-MM-DD) určuje období řady (při invoice_number_period = year/month), default je dnešek.

curl -X POST https://mojefirma.example/api/v1/settings/supplier/logo \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@logo.png"
# → { "logo_path": "storage/supplier-logos/sup-1.png", "width": 480, "height": 160 }

41.9 Brandingový profil faktury

Po zapnutí modulu brandingových profilů vrací aktivní profily aktuálního dodavatele read-only endpoint:

curl -H "Authorization: Bearer $TOKEN" \
  https://mojefirma.example/api/v1/branding-profiles

Hodnotu id lze poslat při vytvoření konceptu faktury:

curl -X POST https://mojefirma.example/api/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 123,
    "branding_profile_id": 5,
    "issue_date": "2026-07-20",
    "due_date": "2026-08-03",
    "items": [{
      "description": "Konzultační služby",
      "quantity": 1,
      "unit": "h",
      "unit_price_without_vat": 2500,
      "vat_rate_id": 1
    }]
  }'

Profil musí být aktivní a patřit stejnému dodavateli jako klient. Jinak API vrátí HTTP 400 s kódem integrity_violation. Když branding_profile_id v těle chybí nebo je null, nový koncept převezme výchozí profil klienta a následně výchozí profil dodavatele. Není-li žádný nastaven, použije základní identitu.

Při vystavení se výsledná identita včetně cesty k verzi loga uloží do snapshotu faktury. Pozdější úprava profilu tedy již vystavený doklad nezmění.

41.10 Export faktur přes API

— hromadný export vystavených dokladů za měsíc (nebo period=quarterly&year=YYYY&quarter=1..4). PDF ZIP, ISDOC, Pohoda či Stereo XML; date_by=tax zařazuje dle DUZP (shodně s výkazy DPH). Pro PDF lze merge_pdf=true vrátit jeden soubor místo ZIPu a současně sign_pdf=true podepsat výsledný celek.

curl -H "Authorization: Bearer $TOKEN" -OJ \
  "https://mojefirma.example/api/v1/invoices/export?format=isdoc&month=2026-06"

41.11 Bezpečnost tokenů — best practices

41.12 Co API nepokrývá