API pro vývojáře

Skyware API

Napojte na Skyware svůj web nebo vlastní aplikaci. Poptávky z formuláře založí lead rovnou v pipeline, leady, firmy, projekty a faktury si přečtete do svých nástrojů a webhooky vám dají vědět, když se něco stane.

K čemu API je

Skyware API je pro případy, kdy data nemají zůstat jen ve Skyware – nebo do něj mají přicházet samy:

  • Poptávkový formulář na webu založí lead v pipeline a obchodníci dostanou upozornění. Nikdo nic nepřepisuje z e-mailu.
  • Vlastní přehledy a nástroje – leady, firmy, projekty a vydané faktury si přečtete do tabulek, reportů nebo interních aplikací.
  • Typy zakázek a fáze načtete třeba pro výběr v poptávkovém formuláři.
  • Webhooky – Skyware sám dá vědět vaší aplikaci, Make, Zapieru nebo n8n, když přijde poptávka, klient schválí nabídku nebo zaplatí fakturu.

Každý zákazník má svůj Skyware na vlastní adrese, a tedy i vlastní API. V příkladech ji píšeme jako https://vase-firma.skyware.cz/api/v1 – místo vase-firma.skyware.cz použijte adresu svého Skyware.

Rychlý start

  1. Ve Skyware otevřete Nastavení › API a vytvořte nový klíč. Dejte mu jen oprávnění, která aplikace potřebuje.
  2. Klíč (začíná sw_) si uložte na bezpečné místo a posílejte ho v hlavičce Authorization.
  3. Spojení otestujte voláním GET /ping. Vrátí název klíče a jeho oprávnění.
curl https://vase-firma.skyware.cz/api/v1/ping \
  -H 'Authorization: Bearer sw_…'

Odpověď:

{
    "data": {
        "key": "Web skyware.cz",
        "scopes": [
            "leads:write"
        ],
        "version": "v1"
    }
}

Ověření a oprávnění

Každé volání musí mít v hlavičce API klíč:

Authorization: Bearer sw_…
  • Klíče vytváříte ve Skyware v Nastavení › API. Pro každou aplikaci zvlášť, každý jen s oprávněními, která potřebuje.
  • Klíči můžete nastavit platnost do určitého data a kdykoli ho zrušit.
  • Každé volání se zaznamená a záznam se uchovává 90 dní. Najdete ho v Nastavení › API.

Oprávnění

OprávněníNázevCo umožňuje
leads:writeZakládat leadyPoptávky z webu a formulářů – založí lead v pipeline a upozorní obchodníky.
leads:readČíst leadySeznam a detail leadů včetně fáze, hodnoty a obchodníka.
pipelines:readČíst typy zakázekTypy zakázek (pipeline) a jejich fáze – např. pro výběr v poptávkovém formuláři.
companies:readČíst firmyKlienti: název, IČO, DIČ, adresa, e-mail pro faktury.
projects:readČíst projektyProjekty: název, klient, stav, termín.
invoices:readČíst fakturyVydané faktury: číslo, klient, částka, splatnost, úhrada.

Formát a pravidla

JSON tam i zpět

Data posíláte jako JSON s hlavičkou Content-Type: application/json a odpovědi jsou také v JSON. Výsledek je vždy v poli data.

Seznamy a stránkování

Seznamy berou parametry ?limit= (max. 100, výchozí 50) a ?offset=. Kromě záznamů vrátí i celkový počet, abyste věděli, kolik stránek zbývá:

{
    "data": [
        "…"
    ],
    "meta": {
        "total": 0,
        "limit": 50,
        "offset": 0
    }
}

Data a časy

Datum má tvar YYYY-MM-DD (např. 2026-10-31), datum a čas YYYY-MM-DD HH:MM:SS. Ve stejném tvaru zadáváte i filtry jako updated_since.

Limit volání

Jeden klíč může zavolat API nejvýš 120× za minutu. Další volání v téže minutě skončí chybou HTTP 429 (rate_limited).

Endpointy

Všechny adresy jsou na doméně vašeho Skyware, např. https://vase-firma.skyware.cz/api/v1/leads.

GET /api/v1/ping

Ověření klíče · stačí platný klíč, bez zvláštního oprávnění

Vrátí název klíče a jeho oprávnění. Hodí se k otestování spojení.

Odpověď

{
    "data": {
        "key": "Web skyware.cz",
        "scopes": [
            "leads:write"
        ],
        "version": "v1"
    }
}

POST /api/v1/leads

Založit lead (poptávku) · oprávnění leads:write

Založí lead v pipeline (zdroj „web“, bez obchodníka), zapíše zprávu do historie leadu a upozorní obchodníky. Stejná poptávka (e-mail + text) odeslaná znovu do 10 minut se nezaloží podruhé – vrátí se původní lead s "duplicate": true. Když e-mail patří kontaktu klienta, lead se k jeho firmě propojí sám. Založení spustí sekvence „Nový lead“.

PolePopis
namejméno a příjmení (povinné, pokud chybí company)
emaile-mail (povinný e-mail nebo telefon)
phonetelefon
companynázev firmy
messagetext poptávky (max. 5 000 znaků)
titlenázev leadu (výchozí „Poptávka z webu – firma/jméno“)
pipelineID typu zakázky (výchozí první; viz GET /pipelines)
valueodhad hodnoty bez DPH
currencyISO kód měny, např. CZK (výchozí základní měna)
sourcezdroj: web, doporučení, telefon, e-mail, akce, jiné… (výchozí web)
pageURL stránky, ze které poptávka přišla
utmobjekt {source, medium, campaign, term, content}

Příklad volání

curl -X POST https://vase-firma.skyware.cz/api/v1/leads \
  -H 'Authorization: Bearer sw_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jana Nováková",
    "email": "[email protected]",
    "phone": "+420 777 123 456",
    "company": "Firma s.r.o.",
    "message": "Chtěli bychom ukázku Skyware pro 8 lidí.",
    "page": "https://skyware.cz/poptavka",
    "utm": {
        "source": "google",
        "medium": "cpc"
    }
}'

Odpověď

{
    "data": {
        "id": 42,
        "title": "Poptávka z webu – Firma s.r.o.",
        "status": "open",
        "pipeline": {
            "id": 1,
            "name": "Weby"
        },
        "stage": {
            "id": 1,
            "name": "Nový lead",
            "role": ""
        },
        "duplicate": false
    }
}

GET /api/v1/leads

Seznam leadů · oprávnění leads:read

Od nejnověji změněných.

ParametrPopis
statusopen / won / lost
pipelineID typu zakázky
updated_sincejen změněné od (YYYY-MM-DD nebo datum a čas)
limitmax. 100 (výchozí 50)
offsetposun

Příklad volání

curl 'https://vase-firma.skyware.cz/api/v1/leads?limit=20&offset=0' \
  -H 'Authorization: Bearer sw_…'

Odpověď

{
    "data": [
        {
            "id": 42,
            "title": "Poptávka z webu – Firma s.r.o.",
            "status": "open",
            "value": 120000,
            "currency": "CZK",
            "…": "…"
        }
    ],
    "meta": {
        "total": 1,
        "limit": 50,
        "offset": 0
    }
}

GET /api/v1/leads/{id}

Detail leadu · oprávnění leads:read

Lead včetně kontaktu, dalšího kroku a posledních 20 záznamů historie.

Odpověď

{
    "data": {
        "id": 42,
        "title": "…",
        "contact": {
            "name": "Jana Nováková",
            "email": "[email protected]",
            "phone": ""
        },
        "activity": [
            {
                "type": "note",
                "text": "…",
                "date": "2026-09-28 10:15:00"
            }
        ]
    }
}

GET /api/v1/pipelines

Typy zakázek a fáze · oprávnění pipelines:read

Typy zakázek (pipeline) s fázemi v pořadí. role: "" běžná, quote_sent, won, lost.

Odpověď

{
    "data": [
        {
            "id": 1,
            "name": "Weby",
            "stages": [
                {
                    "id": 1,
                    "name": "Nový lead",
                    "position": 1,
                    "probability": 10,
                    "role": ""
                }
            ]
        }
    ]
}

GET /api/v1/companies

Seznam firem (klientů) · oprávnění companies:read

Podle názvu.

ParametrPopis
qhledat v názvu
reg_nopřesné IČO
limitmax. 100
offsetposun

Odpověď

{
    "data": [
        {
            "id": 5,
            "name": "Firma s.r.o.",
            "reg_no": "12345678",
            "vat_no": "CZ12345678",
            "city": "Praha",
            "…": "…"
        }
    ],
    "meta": {
        "total": 1,
        "limit": 50,
        "offset": 0
    }
}

GET /api/v1/companies/{id}

Detail firmy · oprávnění companies:read

Odpověď

{
    "data": {
        "id": 5,
        "name": "Firma s.r.o.",
        "…": "…"
    }
}

GET /api/v1/projects

Seznam projektů · oprávnění projects:read

Od nejnověji změněných, bez smazaných.

ParametrPopis
companyID firmy
done0 = rozpracované, 1 = hotové
updated_sincejen změněné od
limitmax. 100
offsetposun

Odpověď

{
    "data": [
        {
            "id": 37,
            "title": "Nový web",
            "company": {
                "id": 5,
                "name": "Firma s.r.o."
            },
            "status": "Rozpracováno",
            "done": false,
            "deadline": "2026-10-31"
        }
    ],
    "meta": {
        "total": 1,
        "limit": 50,
        "offset": 0
    }
}

GET /api/v1/projects/{id}

Detail projektu · oprávnění projects:read

Odpověď

{
    "data": {
        "id": 37,
        "title": "Nový web",
        "…": "…"
    }
}

GET /api/v1/invoices

Seznam vydaných faktur · oprávnění invoices:read

Od nejnovějších.

ParametrPopis
paid0 / 1
overdue1 = jen po splatnosti
companyID firmy
sincevystavené od (YYYY-MM-DD)
limitmax. 100
offsetposun

Odpověď

{
    "data": [
        {
            "id": 120,
            "number": "FV2026100042",
            "type": "faktura",
            "company": {
                "id": 5,
                "name": "Firma s.r.o."
            },
            "total": 36300,
            "total_without_vat": 30000,
            "currency": "CZK",
            "due_date": "2026-10-12",
            "paid": false
        }
    ],
    "meta": {
        "total": 1,
        "limit": 50,
        "offset": 0
    }
}

GET /api/v1/invoices/{id}

Detail faktury · oprávnění invoices:read

Odpověď

{
    "data": {
        "id": 120,
        "number": "FV2026100042",
        "…": "…"
    }
}

Webhooky

API čte data, když se zeptáte. Webhook je opačný směr: když se ve Skyware něco stane, Skyware sám pošle zprávu na vaši adresu. Nemusíte se pořád ptát, jestli je něco nového.

  1. Ve Skyware otevřete Nastavení › API › Webhooky a zadejte adresu, kam má zpráva chodit. Musí být na https.
  2. Vyberte události, které vás zajímají. Webhook dostane vlastní tajný klíč pro ověření podpisu.
  3. Tlačítkem Test pošlete zkušební zprávu (událost test) a hned uvidíte, jak vaše adresa odpověděla.

Události

UdálostKdy přijde
lead.createdNový lead (poptávka)
lead.wonLead vyhrán
lead.lostLead prohrán
quote.sentNabídka odeslána klientovi
quote.approvedNabídka schválena klientem
quote.rejectedNabídka odmítnuta klientem
invoice.createdFaktura vystavena
invoice.paidFaktura zaplacena
project.createdProjekt založen
project.doneProjekt dokončen

Leady, nabídky a projekty odcházejí hned po změně. Nové a zaplacené faktury (vznikají i párováním plateb z banky) Skyware zjišťuje každou minutu, takže přijdou s malým zpožděním.

Zpráva

Skyware pošle POST s JSON tělem: název události, ID objektu, čas a hlavní údaje objektu. Odkaz url vede na záznam ve Skyware. Příklad pro lead.created:

{
    "event": "lead.created",
    "id": 128,
    "occurred_at": "2026-10-05T14:32:10+02:00",
    "data": {
        "id": 128,
        "title": "Nový web pro e-shop",
        "status": "open",
        "stage": "Nová poptávka",
        "pipeline": "Obchod",
        "value": 120000,
        "currency": "CZK",
        "source": "web",
        "referral": "Doporučení od klienta",
        "company": {
            "id": 42,
            "name": "Příklad s.r.o."
        },
        "contact": {
            "name": "Jana Nováková",
            "email": "[email protected]",
            "phone": "+420 777 123 456"
        },
        "lost_category": null,
        "lost_reason": null,
        "url": "https://vase-firma.skyware.cz/pipeline/lead/128"
    }
}
HlavičkaVýznam
X-Skyware-EventNázev události, např. lead.created (u zkušební zprávy test).
X-Skyware-DeliveryČíslo doručení – při opakování zůstává stejné, podle něj poznáte duplicitu.
X-Skyware-Signaturesha256= a HMAC-SHA256 celého těla zprávy, klíčem je tajný klíč webhooku.

Ověření podpisu

Než zprávě uvěříte, ověřte podpis: spočítejte HMAC-SHA256 z těla tak, jak přišlo (bez úprav), tajným klíčem webhooku a porovnejte ho s hlavičkou X-Skyware-Signature. Porovnávejte funkcí s konstantním časem. PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SKYWARE_SIGNATURE'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($body, true);
// … zpracování, pak odpověď 2xx

Node.js:

const crypto = require('crypto');

// rawBody = tělo požadavku tak, jak přišlo (Buffer), ne znovu serializovaný JSON
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
const given = req.get('X-Skyware-Signature') || '';
if (given.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))) {
  return res.sendStatus(401);
}

Odpověď a opakování

  • Odpovězte kódem 2xx do 10 sekund. Delší zpracování si dejte do fronty a odpovězte hned.
  • Jiná odpověď, timeout nebo nedostupná adresa = Skyware zprávu zopakuje po 1 min, 5 min, 30 min a 2 h. Pak doručení vzdá a označí ho jako nedoručené.
  • Stejná zpráva tak může přijít víckrát – duplicitu poznáte podle X-Skyware-Delivery.
  • Přesměrování (3xx) Skyware nenásleduje. Výsledky doručení za posledních 30 dní vidíte ve Skyware na kartě Webhooky.

Chyby

Při chybě API vrátí odpovídající HTTP status a v těle kód a popis chyby. Chyba validace (422) navíc obsahuje pole fields s podrobnostmi k jednotlivým polím.

{
    "error": {
        "code": "unauthorized",
        "message": "…"
    }
}
HTTPKódKdy nastane
400invalid_jsonTělo požadavku není platný JSON objekt.
401unauthorizedChybí API klíč, nebo je neplatný, zrušený či prošlý.
403forbiddenKlíč nemá oprávnění, které endpoint vyžaduje.
404not_foundNeznámá adresa nebo záznam neexistuje.
405method_not_allowedMetoda není u této adresy povolená.
422validation_failedData nejsou kompletní – podrobnosti po polích ve "fields".
429rate_limitedPříliš mnoho volání – max. 120 za minutu na klíč.
500server_errorChyba na straně Skyware – zkuste to znovu.

Pomoc a ukázka

Chystáte napojení a nevíte si rady, nebo vám v API něco chybí? Napište nám – poradíme s napojením a rádi vám Skyware ukážeme na vaší práci.

Ukážeme vám Skyware na vaší práci

Napište, jak dnes pracujete s projekty, klienty a fakturací. Projdeme to spolu a navrhneme, jak by to vypadalo ve Skyware.

Chci nezávaznou ukázku