API pre vlastné integrácie

Verzia v1 · súčasť balíka Business Pro

Cez API pripojíte k PLEVIXu vlastný e-shop, sklad alebo interný systém. Typické použitie: na vašom e-shope padne objednávka a faktúra sa objaví v PLEVIXe bez toho, aby ju niekto prepisoval ručne.

Ako to funguje

Do PLEVIXu vedú dvoje dvere. Cez hlavné chodí človek — prihlási sa a klikne. Cez API chodí program a namiesto hesla ukáže API kľúč. Podľa kľúča PLEVIX vie, komu patrí, ktorej firmy sa týka a čo smie robiť.

1. Vytvorenie kľúča

Kľúč si vytvoríte v Nastaveniach profilu v sekcii API kľúče. Pri vytvorení si vyberiete rozsah — či má kľúč len čítať, alebo aj zapisovať.

Kľúč sa zobrazí jediný raz. Uložený je len jeho odtlačok, takže ho neskôr nevie zobraziť ani podpora. Keď ho stratíte, zrušíte starý a vytvoríte nový.

2. Overenie

Kľúč posielate v hlavičke každej požiadavky:

Authorization: Bearer pxk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Na jeden kľúč platí limit 120 požiadaviek za minútu. Po prekročení príde 429; počkajte do ďalšej minúty.

Kľúč nikdy nedávajte do stránky ani do mobilnej aplikácie. Patrí výhradne na váš server. Preto API zámerne nepovoľuje volania z prehliadača (nemá hlavičky CORS) — keby ich povoľovalo, prvý kľúč vložený do JavaScriptu si prečíta ktokoľvek zo zdrojového kódu stránky.

3. Čo API vie

GET /api/v1/ucet

Overí kľúč a vráti firmu, balík a rozsahy. Použite ho na skúšku, či je všetko nastavené.

curl -H "Authorization: Bearer VÁŠ_KĽÚČ" \ https://plevixbusiness.com/api/v1/ucet

GET /api/v1/faktury

Zoznam faktúr aktívnej firmy. Podporuje ?limit= (najviac 200) a ?od= na stránkovanie, ?firma= na výber firmy. Vyžaduje rozsah faktury.citanie.

curl -H "Authorization: Bearer VÁŠ_KĽÚČ" \ "https://plevixbusiness.com/api/v1/faktury?limit=20"

GET /api/v1/faktury/{id}

Jedna faktúra podľa vnútorného id alebo podľa čísla dokladu.

POST /api/v1/faktury

Vloží faktúru do PLEVIXu. Vyžaduje rozsah faktury.zapis.

Faktúra sa nevytvorí okamžite — príde ako návrh na potvrdenie. Je to zámer: cudzí systém sa môže pomýliť a doklad je účtovný záznam, nie poznámka. V PLEVIXe ho uvidíte medzi čakajúcimi záznamami, skontrolujete a potvrdíte. Číslo dokladu prideľuje server až vtedy, takže sa nemôže minúť do prázdna.

curl -X POST \ -H "Authorization: Bearer VÁŠ_KĽÚČ" \ -H "Content-Type: application/json" \ -d '{ "odberatel": {"nazov":"Anna Kováčová","email":"anna@example.com"}, "polozky": [ {"nazov":"Montérky veľkosť L","mnozstvo":2,"cena":24.90,"dph":23}, {"nazov":"Doprava","mnozstvo":1,"cena":3.50,"dph":23} ], "externeCislo": "ESHOP-2026-00417" }' \ https://plevixbusiness.com/api/v1/faktury

Odpoveď 202 znamená, že návrh čaká v PLEVIXe:

{"ok":true,"id":"h_…","stav":"caka_na_potvrdenie"}

GET /api/v1/kontakty

Kontakty z CRM aktívnej firmy. Jeden kontakt cez /api/v1/kontakty/{id} alebo podľa e-mailu. Vyžaduje rozsah kontakty.citanie.

GET /api/v1/objednavky

Objednávky z Eshopu. Jedna objednávka cez /api/v1/objednavky/{id} alebo podľa čísla. Vyžaduje rozsah objednavky.citanie.

curl -H "Authorization: Bearer VÁŠ_KĽÚČ" "https://plevixbusiness.com/api/v1/objednavky?limit=20"

GET /api/v1/sklad

Skladové položky a množstvá. Jedna položka cez /api/v1/sklad/{sku}. Vyžaduje rozsah sklad.citanie.

{"firma":"cmp_…","spolu":2,"od":0,"limit":50,"polozky":[ {"id":"i1","sku":"MONT-L","name":"Montérky veľkosť L","qty":12,"unit":"ks"} ]}

POST /api/v1/kontakty · /objednavky · /sklad

Vytvorí nový záznam, alebo upraví existujúci, keď pošlete id. Vyžaduje rozsah kontakty.zapis, objednavky.zapis alebo sklad.zapis.

curl -X POST -H "Authorization: Bearer VÁŠ_KĽÚČ" -H "Content-Type: application/json" -d '{"name":"Zuzana Nová","email":"zuzana@example.com","status":"Lead"}' https://plevixbusiness.com/api/v1/kontakty

Odpoveď 201 pri novom zázname, 200 pri úprave — v oboch prípadoch s id, ktoré si uložte, ak chcete záznam neskôr meniť.

Tu sa na potvrdenie nečaká — zápis je okamžitý. Na rozdiel od faktúry, ktorá je účtovný doklad, kontakt či skladová položka sa dá kedykoľvek opraviť. Čas zmeny určuje server, nie váš systém: keby si ho mohol určiť volajúci, stačilo by poslať rok 2099 a taký záznam by už nikto neprepísal.

Ako to, že si zápisy navzájom neprepíšu prácu

Aplikácia v mobile aj v prehliadači si posiela celý svoj zoznam. Keby server jednoducho zapísal to, čo prišlo, váš zápis cez API by zmizol pri najbližšej synchronizácii z telefónu — a naopak.

Preto sa zlučuje po jednotlivých záznamoch: každý záznam má vlastný čas zmeny a vyhráva novší. Záznam, ktorý pozná len jedna strana, sa nikdy nezahodí. Zmazanie zanecháva stopu, takže sa zmazaný záznam nevráti z druhého zariadenia — ale keď ho niekto po zmazaní znova upraví, úprava je novšia a záznam ožije.

Všetky zoznamy podporujú ?limit= (najviac 200), ?od= a ?firma=. Kľúč vidí iba nástroje, ktoré má váš balík — inak vráti 402.

Export pre účtovný program

Parameter ?format=pohoda vráti faktúry ako POHODA XML (dataPack) namiesto JSON — súbor, ktorý účtovník naimportuje priamo do programu. Filtre ?zmenene_od= a ?firma= platia rovnako, takže sa dá stiahnuť napríklad presne jeden mesiac.

curl -H "Authorization: Bearer VÁŠ_KĽÚČ" \n "https://plevixbusiness.com/api/v1/faktury?format=pohoda&zmenene_od=2026-08-01T00:00:00%2B00:00" \n -o pohoda.xml

Cena položky sa posiela bez dane a sadzba ako none, low alebo high — konkrétne percento si POHODA dopĺňa sama podľa obdobia. Zaúčtovanie (predkontácie) neposielame; to si účtovník nastavuje vo svojom programe.

Sťahujte len to, čo sa zmenilo

Parameter ?zmenene_od= vráti iba záznamy zmenené po danom čase. Uložte si aktualizovane z poslednej odpovede a nabudúce ho pošlite späť — namiesto celého zoznamu dostanete len rozdiel.

curl -H "Authorization: Bearer VÁŠ_KĽÚČ" \n "https://plevixbusiness.com/api/v1/kontakty?zmenene_od=2026-08-25T09:00:00%2B00:00"

Čas zapíšte v tvare ISO 8601. V adrese nezabudnite zakódovať + ako %2B, inak sa z neho stane medzera a časové pásmo sa stratí. Filtruje sa vždy pred stránkovaním, takže spolu hovorí, koľko záznamov sa naozaj zmenilo.

Príklad v PHP

$kluc = getenv('PLEVIX_API_KLUC'); // kľúč patrí do premennej prostredia, nie do kódu $ch = curl_init('https://plevixbusiness.com/api/v1/faktury'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Authorization: Bearer '.$kluc, 'Content-Type: application/json'], CURLOPT_POSTFIELDS => json_encode([ 'odberatel' => ['nazov' => $objednavka['meno']], 'polozky' => $polozky, 'externeCislo' => $objednavka['cislo'], ], JSON_UNESCAPED_UNICODE), ]); $odpoved = json_decode(curl_exec($ch), true);

Webhooky — keď sa má PLEVIX ozvať vám

API rieši smer „váš systém sa pýta PLEVIXu". Webhook je opačný: keď zákazník uhradí faktúru, váš e-shop sa to dozvie sám, bez toho, aby sa každú minútu pýtal.

Cieľ pridáte v Nastaveniach profilu v sekcii Webhooky. Zadáte adresu a vyberiete udalosti. Tlačidlom Skúška si overíte spracovanie skôr, než príde ostrá udalosť.

Aké udalosti chodia

Udalosť	Kedy nastane
`faktura.vytvorena`	V PLEVIXe pribudla nová faktúra.
`faktura.uhradena`	Faktúra bola označená ako uhradená.
`objednavka.nova`	V Eshope pribudla nová objednávka.
`objednavka.odoslana`	Objednávka prešla do stavu „Odoslaná".

Pri objednávkach nesie data polia id, cislo, zakaznik, suma, stav, dopravca a zasielka.

Ako správa vyzerá

Na vašu adresu príde POST s JSON telom:

{ "udalost": "faktura.uhradena", "firma": "cmp_…", "cas": "2026-08-24T21:15:03+00:00", "data": { "id": "…", "cislo": "FA-2026-0042", "suma": 53.30, "mena": "EUR", "odberatel": "Anna Kováčová", "splatnost": "2026-09-07" } }

Overenie podpisu — toto nepreskočte

Vašu adresu môže poznať ktokoľvek, kto ju odpozerá. Preto každú správu podpisujeme tajomstvom, ktoré poznáte len vy a PLEVIX. Podpis je v hlavičke:

X-PLEVIX-Signature: t=1756070103,v1=9f2c…

Podpisuje sa reťazec čas + "." + telo algoritmom HMAC-SHA256. Overenie v PHP:

$telo = file_get_contents('php://input'); $hlavicka = $_SERVER['HTTP_X_PLEVIX_SIGNATURE'] ?? ''; $tajomstvo = getenv('PLEVIX_WEBHOOK_TAJOMSTVO'); if (!preg_match('/t=(\d+),v1=([a-f0-9]+)/', $hlavicka, $m)) { http_response_code(400); exit; } // Staršia než päť minút? Niekto zachytenú správu posiela znova. if (abs(time() - (int)$m[1]) > 300) { http_response_code(400); exit; } $ocakavany = hash_hmac('sha256', $m[1] . '.' . $telo, $tajomstvo); // hash_equals, nie == — porovnanie musí trvať rovnako dlho vždy if (!hash_equals($ocakavany, $m[2])) { http_response_code(401); exit; } $udalost = json_decode($telo, true); // … tu spracujte úhradu … http_response_code(200);

Čo od vášho servera čakáme

Adresa musí byť https:// a verejne dostupná. Adresy do vnútornej siete odmietame — inak by sa dal náš server prinútiť sťahovať cudzie vnútro.
Cieľ musí mať IPv4 adresu. Server dostupný len cez IPv6 zatiaľ nepodporujeme.
Odpovedzte kódom 2xx do 5 sekúnd. Dlhé spracovanie si odložte na neskôr a odpovedzte hneď.
Keď neodpoviete, skúšame päťkrát s narastajúcim odstupom (1, 2, 4, 8 minút). Potom správu zahodíme a v profile uvidíte dôvod.
Po troch takto zahodených správach cieľ vypneme, aby sme doň netĺkli donekonečna. Zapnete ho pridaním nanovo.
Tá istá správa môže prísť aj dvakrát (napríklad keď vaša odpoveď cestou zapadne). Spracovanie si preto zaistite podľa data.id, nech sa úhrada nezapíše dvakrát.

Odpovede a chyby

Každá chyba nesie okrem vety pre človeka aj kód pre stroj v poli code. Vyhodnocujte kód, nie text — texty sa môžu spresniť, kódy zostanú.

{"error":"Kľúč nemá rozsah sklad.citanie.","code":"missing_scope","rozsah":"sklad.citanie"}

HTTP	`code`	Čo znamená
`200`	—	V poriadku.
`201`	—	Záznam vznikol.
`202`	—	Prijaté, čaká na potvrdenie v PLEVIXe.
`401`	`missing_key`	Hlavička `Authorization` chýba.
`401`	`invalid_key`	Kľúč neexistuje alebo bol zrušený.
`402`	`plan_required`	Balík neobsahuje API. Vyžaduje sa Business Pro.
`403`	`missing_scope`	Kľúč nemá potrebný rozsah — ktorý, je v poli `rozsah`.
`403`	`team_product_denied`	Vo firme vám tento nástroj nepovolil správca.
`404`	`company_not_found`	Firma nepatrí tomuto účtu.
`404`	`not_found`	Záznam s takým `id` neexistuje.
`404`	`unknown_path`	Neznáma cesta.
`405`	`method_not_allowed`	Tá cesta túto metódu nepodporuje.
`413`	`payload_too_large`	Jeden záznam smie mať najviac 64 kB, faktúra najviac 200 položiek.
`422`	`missing_field`	Chýba povinné pole — ktoré, je v poli `pole`.
`422`	`too_many_items`	Priveľa položiek na jeden doklad.
`422`	`no_fields`	Telo neobsahovalo žiadne použiteľné pole.
`429`	`rate_limited`	Prekročený limit 120 požiadaviek za minútu na kľúč. Presné číslo je aj v odpovedi v poli `limit`.

Bezpečnosť

Kľúč je uložený len ako odtlačok — z databázy sa spätne prečítať nedá.
Zrušenie kľúča platí okamžite pri najbližšej požiadavke.
Kľúč vidí výhradne údaje firiem, ktoré patria jeho účtu.
Pri každom použití sa zaznamená čas a IP adresa — v profile vidíte, kedy bol kľúč naposledy použitý.
Kľúč držte v premennej prostredia alebo v nastaveniach servera, nie v zdrojovom kóde a nie v repozitári.

Čo API zatiaľ nevie

Cez API sa dnes dajú čítať aj zapisovať kontakty z CRM, objednávky z Eshopu a skladové položky, čítať faktúry a vytvárať faktúru ako návrh na potvrdenie. Zatiaľ nie sú dostupné Banka a pokladňa ani účtovníctvo — tam je doklad viazaný na uzávierky a zápis zvonku by musel riešiť aj ich. Ak vám niečo konkrétne chýba, napíšte na support@plevixbusiness.com; podľa toho určíme poradie.