21. 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 dvě varianty stejné dokumentace nad jedním OpenAPI specem:

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/openapi.yamlRaw OpenAPI 3.1Import do Postmana, Insomnie, Zapier Custom App, Make HTTP modulu

21.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.

21.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"}'

21.3 Verzování

21.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 %.

21.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.

21.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.

21.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)

21.8 Bezpečnost tokenů — best practices

21.9 Co API nepokrývá