{"openapi":"3.0.3","info":{"title":"Scalix Connector API","version":"1.0.0","description":"Napojení libovolného systému (CRM, ERP, účetnictví, e-shop) na Scalix.\n\n## Jak to funguje\n1. **Vygenerujte API token** v aplikaci: *Nastavení → API přístup* → token ve tvaru `sclx_…`\n2. **Posílejte data dávkově** — každý endpoint přijímá `{ source, items[] }` (max 500 položek na požadavek)\n3. **Idempotence**: záznamy se párují přes dvojici `source + externalId` — opakovaný push nikdy nevytvoří duplicitu, jen aktualizuje\n4. **Čtěte AI výsledky** — buď GET endpointy (pull), nebo si zaregistrujte webhook (push do vašeho systému)\n\n## Doporučený postup napojení\nZačněte kontakty → nabídky → zakázky → faktury. Scalix z nich okamžitě staví Health Score, cashflow a obchodní přehledy. E-maily a dokumenty přidejte ve druhé vlně — odemknou AI klasifikaci, prioritizaci a vytěžování smluv.\n\n## Limity a chování\n- **Rate limit AI analýz**: 30 požadavků/min; AI útrata se počítá do měsíčního token limitu firmy\n- **Datumy**: ISO 8601 (`2026-07-17` nebo `2026-07-17T10:00:00Z`), částky jako čísla v Kč\n- **Dedupe dokumentů**: stejný soubor (fileName + fileSize) z více zdrojů se automaticky archivuje jako duplicita\n- **Chyby**: dávka nikdy nespadne celá — vadné položky se vrací v poli `errors` s důvodem česky\n\nInteraktivní příklady s curl najdete na [/developers](https://app.scalix.cz/developers)."},"tags":[{"name":"Systém","description":"Ověření spojení"},{"name":"Obchodní data","description":"Kontakty, nabídky, zakázky, provize"},{"name":"Peníze","description":"Faktury, banka, cashflow"},{"name":"Obsah","description":"Dokumenty a e-maily (vstup pro AI)"},{"name":"AI a webhooky","description":"Analýzy na vyžádání a write-back výsledků"}],"servers":[{"url":"https://app.scalix.cz"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/ping":{"get":{"summary":"Ověření klíče a spojení","tags":["Systém"],"responses":{"200":{"description":"OK — vrací název firmy"}}}},"/api/v1/contacts":{"post":{"summary":"Kontakty — klienti a leady (upsert)","tags":["Obchodní data"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Contact"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}},"get":{"summary":"Čtení kontaktů (stránkované)","tags":["Obchodní data"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Seznam"}}}},"/api/v1/quotes":{"post":{"summary":"Cenové nabídky (upsert)","tags":["Obchodní data"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Quote"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/orders":{"post":{"summary":"Zakázky / podepsané smlouvy (upsert)","tags":["Obchodní data"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Order"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/invoices":{"post":{"summary":"Vydané faktury → cashflow příjmy (upsert)","tags":["Peníze"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Invoice"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/cashflow":{"post":{"summary":"Bankovní transakce a výdaje (upsert)","tags":["Peníze"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/CashflowItem"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/bank-accounts":{"post":{"summary":"Stavy bankovních účtů (přepis)","tags":["Peníze"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/BankAccount"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/documents":{"post":{"summary":"Dokumenty — metadata + odkaz na soubor (upsert, automatický dedupe podle fileName+fileSize)","tags":["Obsah"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Document"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}},"get":{"summary":"Čtení dokumentů vč. AI vytěžení","tags":["Obsah"],"responses":{"200":{"description":"Seznam"}}}},"/api/v1/emails":{"post":{"summary":"E-maily (upsert; AI doplní kategorii, prioritu, shrnutí)","tags":["Obsah"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Email"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}},"get":{"summary":"Čtení e-mailů vč. AI polí (aiCategory, aiPriority, aiSummary, aiDraft)","tags":["Obsah"],"responses":{"200":{"description":"Seznam"}}}},"/api/v1/commissions":{"post":{"summary":"Provize obchodníků (upsert)","tags":["Obchodní data"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["source","items"],"properties":{"source":{"type":"string","description":"Identifikátor zdrojového systému (idempotence: source + externalId)","example":"moje-crm"},"items":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/Commission"}}}}}}},"responses":{"200":{"description":"Výsledek dávky","content":{"application/json":{"schema":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"externalId":{"type":"string"},"error":{"type":"string"}}}}}}}}},"401":{"description":"Chybný nebo chybějící API klíč"}}}},"/api/v1/ai/analyze":{"post":{"summary":"AI analýza na vyžádání (poznámka, e-mail, typologie klienta, návrh odpovědi na tiket)","tags":["AI a webhooky"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["kind","payload"],"properties":{"kind":{"type":"string","enum":["note","email","typology","ticket_reply"]},"payload":{"type":"object","description":"Vstup dle kind — viz /developers"}}}}}},"responses":{"200":{"description":"Strukturovaný výsledek analýzy"},"429":{"description":"Rate limit (30/min) nebo token limit"}}}},"/api/v1/webhook":{"post":{"summary":"Registrace webhooku pro write-back AI výsledků do vašeho systému","tags":["AI a webhooky"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","secret"],"properties":{"url":{"type":"string"},"secret":{"type":"string"}}}}}},"responses":{"200":{"description":"Registrováno"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"sclx_…"}},"schemas":{"Contact":{"type":"object","required":["externalId"],"properties":{"externalId":{"type":"string"},"stage":{"type":"string","enum":["client","lead"]},"companyName":{"type":"string"},"firstName":{"type":"string"},"lastName":{"type":"string"},"ico":{"type":"string"},"dic":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"},"street":{"type":"string"},"city":{"type":"string"},"zip":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"ownerExternalRef":{"type":"string","nullable":true,"maxLength":128,"description":"Stabilní ID vlastníka v zdrojovém systému (jediný autorizační kanál)"},"ownerName":{"type":"string","nullable":true,"maxLength":256,"description":"Zobrazovací jméno vlastníka — NIKDY zdroj autorizace"},"ownershipSource":{"type":"string","nullable":true,"maxLength":64,"description":"Audit trail zdroje resoluce vlastnictví, např. \"client.owner\""},"ownershipState":{"type":"string","nullable":true,"enum":["owned_active","inactive_owner","unassigned","quarantined"],"description":"owned_active vyžaduje vyplněné ownerExternalRef"}}},"Quote":{"type":"object","required":["externalId","number"],"properties":{"externalId":{"type":"string"},"number":{"type":"string"},"title":{"type":"string"},"contactExternalId":{"type":"string"},"status":{"type":"string","enum":["DRAFT","SENT","ACCEPTED","REJECTED","EXPIRED","CANCELLED"]},"totalAmount":{"type":"number"},"validUntil":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"ownerExternalRef":{"type":"string","nullable":true,"maxLength":128},"ownerName":{"type":"string","nullable":true,"maxLength":256},"ownershipSource":{"type":"string","nullable":true,"maxLength":64},"ownershipState":{"type":"string","nullable":true,"enum":["owned_active","inactive_owner","unassigned","quarantined"]}}},"Order":{"type":"object","required":["externalId","number"],"properties":{"externalId":{"type":"string"},"number":{"type":"string"},"title":{"type":"string"},"contactExternalId":{"type":"string"},"quoteExternalId":{"type":"string"},"status":{"type":"string","enum":["NEW","CONFIRMED","IN_PRODUCTION","READY","SHIPPED","DELIVERED","INVOICED","COMPLETED","CANCELLED"]},"totalAmount":{"type":"number"},"dueDate":{"type":"string","format":"date-time"},"signedAt":{"type":"string","format":"date-time"},"ownerExternalRef":{"type":"string","nullable":true,"maxLength":128},"ownerName":{"type":"string","nullable":true,"maxLength":256},"ownershipSource":{"type":"string","nullable":true,"maxLength":64},"ownershipState":{"type":"string","nullable":true,"enum":["owned_active","inactive_owner","unassigned","quarantined"]}}},"Invoice":{"type":"object","required":["externalId","number","amount"],"properties":{"externalId":{"type":"string"},"number":{"type":"string"},"description":{"type":"string"},"amount":{"type":"number"},"dueDate":{"type":"string","format":"date"},"paidDate":{"type":"string","format":"date"},"isPaid":{"type":"boolean"},"contactExternalId":{"type":"string"},"orderExternalId":{"type":"string"}}},"CashflowItem":{"type":"object","required":["externalId","type","amount"],"properties":{"externalId":{"type":"string"},"type":{"type":"string","enum":["INCOME","EXPENSE"]},"description":{"type":"string"},"amount":{"type":"number"},"dueDate":{"type":"string","format":"date"},"paidDate":{"type":"string","format":"date"},"isPaid":{"type":"boolean"}}},"BankAccount":{"type":"object","required":["name","balance"],"properties":{"name":{"type":"string"},"number":{"type":"string"},"balance":{"type":"number"},"currency":{"type":"string","default":"CZK"}}},"Document":{"type":"object","required":["externalId","name"],"properties":{"externalId":{"type":"string"},"name":{"type":"string"},"fileName":{"type":"string"},"fileSize":{"type":"integer"},"mimeType":{"type":"string"},"docType":{"type":"string","enum":["CONTRACT","INVOICE","PHOTO","OTHER"]},"fileUrl":{"type":"string","description":"URL, ze které si Scalix soubor stáhne (chráněné sdíleným secretem)"},"contactExternalId":{"type":"string"}}},"Email":{"type":"object","required":["externalId","direction","fromEmail","toEmail","sentAt"],"properties":{"externalId":{"type":"string"},"direction":{"type":"string","enum":["INBOUND","OUTBOUND"]},"fromEmail":{"type":"string"},"fromName":{"type":"string"},"toEmail":{"type":"string"},"subject":{"type":"string"},"bodyText":{"type":"string"},"sentAt":{"type":"string","format":"date-time"},"messageId":{"type":"string"},"inReplyTo":{"type":"string"},"contactExternalId":{"type":"string"}}},"Commission":{"type":"object","required":["externalId","userName","period","amount"],"properties":{"externalId":{"type":"string"},"userName":{"type":"string"},"userRef":{"type":"string"},"period":{"type":"string","example":"2026-07"},"amount":{"type":"number"},"status":{"type":"string"},"role":{"type":"string"},"contractRef":{"type":"string"},"payableAt":{"type":"string","format":"date-time"}}}}}}