Connector API v1

Rychlý start

1. Zaregistrujte firmu na app.scalix.cz/register
2. V Nastavení → API přístup vygenerujte API token (sclx_…)
3. Ověřte spojení a začněte posílat data:

curl https://app.scalix.cz/api/v1/ping \
  -H "Authorization: Bearer sclx_VAS_TOKEN"

# → {"ok":true,"system":"Scalix","version":"v1","tenant":"Vaše firma"}

Kompletní referenci najdete v interaktivní API dokumentaci (všechny endpointy, schémata, příklady). Pro Postman/Insomnia je k dispozici OpenAPI specifikace (JSON).

Autentizace

Každý požadavek nese hlavičku Authorization: Bearer sclx_…. Token je vázaný na vaši firmu (tenant) — vidíte a zapisujete výhradně svá data. Token lze kdykoli zrušit v Nastavení; ukládáme jen jeho otisk (hash).

Principy

• Batch upsert: POST endpointy přijímají { source, items: [...] } — max 500 položek na požadavek
• Idempotence: každá položka má externalId (vaše ID záznamu). Opakované poslání stejných dat aktualizuje, nevytváří duplicity
• source: identifikátor vašeho systému (např. moje-crm) — umožňuje napojit víc systémů vedle sebe
• Čtení zpět: GET varianty se stránkováním ?page=&limit= (max 200) a inkrementálním filtrem ?since=<ISO-8601>
• Částky v CZK, časy ISO-8601, chyby jako { "error": "…" } s HTTP kódem

Endpointy

POST /api/v1/contacts — kontakty (klienti, leady, dodavatelé)

curl -X POST https://app.scalix.cz/api/v1/contacts \
  -H "Authorization: Bearer sclx_VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "moje-crm",
    "items": [{
      "externalId": "c-123",
      "stage": "client",
      "companyName": "Firma s.r.o.",
      "firstName": "Jan", "lastName": "Novák",
      "ico": "12345678", "dic": "CZ12345678",
      "email": "jan@firma.cz", "phone": "+420601234567",
      "street": "Ulice 1", "city": "Praha", "zip": "11000"
    }]
  }'

# → {"created":1,"updated":0,"errors":[],"ids":{"c-123":"<scalix-id>"}}

POST /api/v1/quotes — cenové nabídky

{ "source": "moje-crm", "items": [{
  "externalId": "q-42", "number": "N-2026-042",
  "title": "Střecha RD Průhonice",
  "contactExternalId": "c-123",
  "status": "SENT",
  "totalAmount": 458000, "taxAmount": 79500,
  "validUntil": "2026-07-15"
}]}

Stavy: DRAFT | SENT | ACCEPTED | REJECTED | EXPIRED | CANCELLED. Idempotence přes number.

POST /api/v1/orders — zakázky / smlouvy

{ "source": "moje-crm", "items": [{
  "externalId": "s-18", "number": "S-2026-018",
  "title": "Střecha RD Průhonice",
  "contactExternalId": "c-123",
  "status": "IN_PRODUCTION",
  "totalAmount": 458000,
  "dueDate": "2026-08-30",
  "signedAt": "2026-06-01"
}]}

Stavy: NEW | CONFIRMED | IN_PRODUCTION | READY | SHIPPED | DELIVERED | INVOICED | COMPLETED | CANCELLED.

POST /api/v1/invoices — faktury (cashflow)

{ "source": "moje-crm", "items": [{
  "externalId": "f-89", "number": "FV-2026-0089",
  "type": "FV",
  "contactExternalId": "c-123",
  "totalAmount": 145200,
  "issuedAt": "2026-06-01", "dueDate": "2026-06-15",
  "isPaid": false
}]}

Typy dle českého flow: FV (běžná), ZF (zálohová),VF (vyúčtovací), DOBROPIS (záporná částka automaticky). Typ DD (daňový doklad k záloze) API přijme, ale do cashflow ho nezapočítá — peníze už přišly zálohou, započtení by je zdvojilo. Pro nákupní faktury pošlete "direction": "EXPENSE".

POST /api/v1/documents — dokumenty (metadata + volitelné vytěžování)

{ "source": "moje-crm", "items": [{
  "externalId": "d-7",
  "name": "Smlouva o dílo S-2026-018",
  "fileName": "smlouva.pdf", "mimeType": "application/pdf",
  "fileSize": 245000, "docType": "CONTRACT",
  "url": "https://vase-crm.cz/documents/d-7",
  "fileUrl": "https://vase-crm.cz/api/soubory/d-7",
  "contactExternalId": "c-123"
}]}

Typy: CONTRACT | INVOICE | CERTIFICATE | PHOTO | REPORT | OTHER. Soubory zůstávají u vás — Scalix eviduje metadata a odkaz. AI vytěžování: pokud pošlete fileUrl (adresa, ze které si Scalix může PDF stáhnout — chraňte ji hlavičkou x-webhook-secret se secretem z registrace webhoooku níže), Scalix smlouvy a faktury automaticky vytěží: strany, částky, splatnosti, klíčové podmínky, rizika a doporučenou akci.

POST /api/v1/emails — e-maily (AI klasifikace a návrhy odpovědí)

{ "source": "moje-crm", "items": [{
  "externalId": "e-555",
  "direction": "INBOUND",
  "fromEmail": "zakaznik@email.cz", "fromName": "Jan Zákazník",
  "toEmail": "info@vase-firma.cz",
  "subject": "Poptávka renovace střechy",
  "bodyText": "Dobrý den, chtěl bych…",
  "sentAt": "2026-07-10T09:15:00Z",
  "hasAttachments": true,
  "contactExternalId": "c-123"
}]}

Scalix příchozí e-maily automaticky klasifikuje (poptávka / objednávka / reklamace / faktura / spam…), shrne a u obchodních zpráv připraví návrh odpovědi v tónu vaší firmy (učí se ze znalostní báze). Výsledky si přečtete přes GET /api/v1/emails (pole aiCategory, aiPriority, aiSummary, aiDraft) nebo je dostanete push přes webhook níže.

POST /api/v1/cashflow — příjmy a výdaje mimo fakturaci (banka)

{ "source": "moje-crm", "items": [{
  "externalId": "tx-2026-889",
  "type": "EXPENSE",
  "description": "ČEPRO a.s. — nafta",
  "amount": 45210,
  "date": "2026-07-08",
  "category": "Banka — odchozí platby",
  "isPaid": true
}]}

Typicky bankovní transakce. Neposílejte interní převody mezi vlastními účty — zkreslily by výdaje. Z opakovaných plateb Scalix automaticky detekuje pravidelné náklady a promítá je do výhledu cashflow.

POST /api/v1/bank-accounts — stavy účtů

{ "source": "moje-crm", "items": [{
  "externalId": "2901620628/2010",
  "name": "Provozní účet", "bankName": "Fio banka",
  "balance": 2136952, "balanceAt": "2026-07-12T06:00:00Z"
}]}

POST /api/v1/commissions — provize obchodníků

{ "source": "moje-crm", "items": [{
  "externalId": "com-123", "userName": "Jan Novák",
  "period": "2026-07", "amount": 12500,
  "status": "k_vyplaceni", "contractRef": "SML-2026-0851"
}]}

Jméno posílejte při každém syncu — noví obchodníci se ve Scalixu objeví automaticky.

POST /api/v1/ai/analyze — AI analýza na vyžádání

curl -X POST https://app.scalix.cz/api/v1/ai/analyze   -H "Authorization: Bearer sclx_VAS_TOKEN"   -H "Content-Type: application/json"   -d '{ "kind": "email",
        "payload": { "subject": "Poptávka střechy",
                     "body": "Dobrý den, chtěl bych…" } }'

# kind: note | email | typology | ticket_reply
# → strukturovaný JSON (kategorie, priorita, shrnutí / návrh odpovědi)
# limit 30 požadavků/min, útrata se počítá do token limitu firmy

POST /api/v1/webhook — odběr AI výsledků (write-back)

curl -X POST https://app.scalix.cz/api/v1/webhook \
  -H "Authorization: Bearer sclx_VAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://vase-crm.cz/api/webhooks/scalix",
        "secret": "min-16-znaku-nahodny-retezec" }'

# Scalix pak po každém AI zpracování volá:
# POST <url>  (hlavička x-webhook-secret: <secret>)
# { "type": "email_ai",
#   "items": [{ "externalId": "e-555",
#               "aiCategory": "poptavka",
#               "aiSummary": "Zákazník poptává renovaci…",
#               "aiDraft": "Dobrý den, děkujeme za poptávku…" }] }

externalId je ID e-mailu ve vašem systému — návrh odpovědi tak uložíte rovnou ke správné zprávě (např. jako koncept ve schránce). Stejný secret použijte pro ochranu fileUrl dokumentů. Konfiguraci ověříte GET /api/v1/webhook, zrušíte DELETE.

Čtení dat

GET /api/v1/contacts?source=moje-crm&since=2026-06-01T00:00:00Z&page=1&limit=100
GET /api/v1/quotes?since=...
GET /api/v1/orders?since=...
GET /api/v1/invoices?since=...
GET /api/v1/documents?since=...
GET /api/v1/emails?since=...   # vč. aiCategory, aiSummary, aiDraft

# → { "items": [...], "page": 1, "limit": 100, "total": 250, "hasMore": true }

Doporučený sync

1. Pořadí: contacts → quotes → orders → invoices → cashflow → documents → emails (vazby přes contactExternalId)
2. První sync: pošlete vše; další syncy: jen záznamy změněné od minulého běhu
3. Frekvence: inkrementální sync každých 15 minut bohatě stačí
4. Idempotence je zaručena — při nejistotě klidně pošlete znovu

Chybové kódy

Scalix Connector API v1 · Změny API oznamujeme předem · Podpora: podpora@scalix.cz