ERPIO One Client API

Klientské API rozhranie ERPIO One je zjednodušená brána k platforme ERPIO One (my.erpio.one). Namiesto toho, aby ste sa museli zaoberať viackrokovým protokolom pôvodného API, vykonáte tu jednu požiadavku a získate dáta alebo vykonáte akciu.

Rozhranie API interne spracováva všetku orchestráciu – vrátane reťazených akcií (IDNext), autentifikáciu a dekódovania dátovej časti odpovede.

Nastavenie v ERPIO One Middleware

Každej akcii je možné nastaviť API Alias. Pomocou tohto názvu, je následne akcia dostupné cez klientské API. API Alias musí byť jedinečný v rámci príslušného workspace. Princíp je ten, že akcie typu Navigate to sa používajú na získanie údajov (klientské API vracia tabuľku vo forme JSON stringu)

Klientské API sa správa rovnako ako webový alebo mobilný klient, vykonajú sa getters, uplatnia sa podmienky a pod.

Zreťazením akcií pomocou ID Next je možné dosiahnuť napr. to, že po založení záznamu akciu typu Edit, tak cez naviazanú akciu typu Navigate to si vrátim identifikátor novo založeného záznamu (musím mať pripravený príslušný datasource, ktorý vracia identifikátor najnovšieho záznamu založeného prihláseným používateľom).

Základná URL adresa

https://client.erpio.one

Dostupné koncové body

Metóda	Cesta	Popis
POST	`/api/v1/login`	Získanie tokenu
GET	`/api/v1/{idCustomer}/{actionAlias}`	Vykonanie akcie, získanie údajov, parametre v reťazci dotazu
POST	`/api/v1/{idCustomer}/{actionAlias}`	Vykonanie akcie, získanie údajov, parametre v tele JSON

Autentifikácia

Každý koncový bod akcie vyžaduje autentifikáciu. Existujú dve metódy:

Bearer token

Najprv zavolajte POST /api/v1/login, aby ste získali token, a potom ho odovzdajte v každej hlavičke požiadavky:

Hlavička požiadavky

Autorizácia: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

E1Key

E1Key je interný kľúč pre overenie počas prihlasovania, ktorý môže vytvoriť osoba s príslušnými oprávneniami priamo v Middleware. Odovzdajte ho v hlavičke autorizácie pomocou schémy e1key:

Hlavička požiadavky

Autorizácia: e1key vaša-hodnota-e1kľúča

Iba pre požiadavky GET je možné E1Key odovzdať aj ako parameter dotazu:

Reťazec dotazu (iba GET)

GET /api/v1/213/getorders?e1key=vaša-hodnota-e1kľúča

Priority

Bearer token v hlavičke Autorization – vždy má prednosť
E1Key v hlavičke Autorization ( e1key {hodnota} )
E1Key ako parameter dotazu — iba požiadavky GET

Prihlásenie

Autorizácia nie je potrebná

POST /api/v1/login

Overuje používateľa a vracia token nosiča. Akceptuje JSON, form-urlencoded alebo multipart.

Polia tela požiadavky

Pole	Typ	Povinné	Popis
`UserName`	string	✅	Vaše používateľské meno ERPIO One (e-mail)
`Password`	string	✅	Vaše heslo ERPIO One

Príklad — JSON

REQUEST

POST /api/v1/login
Content-Type: application/json

{
"UserName": "moj@email.domena",
"Password": "mojeheslo"
}

Príklad — Formulár

REQUEST


POST /api/v1/login
Content-Type: application/x-www-form-urlencoded

UserName=moj%40email.domena&Pasword=mojeheslo

RESPONSE (v obidvoch príkladoch)


{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
"type_tokenu": "nositeľ",
"expires_in": 43199
}

Token je platný počet sekúnd podľa expires_in (zvyčajne ~12 hodín). Uschovajte si ho a znova ho použite – neprihlasujte sa pred každou požiadavkou.

Vykonávanie akcií

Akcie sú jadrom rozhrania API. Alias akcie identifikuje konkrétnu operáciu v ERPIO One (napr. getmyserviceactivities, getorders). idCustomer je ID Vášho workspace v systéme. ID workspace nájdete po príhlásení v menu Dashboard:

Predvolená hodnota RowsCount je 50 a je obmedzená na 1000. Ak potrebujete viac záznamov, implementujte stránkovanie pomocou rowsoffset.

GET — Parametre v URL

_{Spôsoby autorizácie:}
Bearer token
E1Key header
E1Key query param

GET /api/v1/{idCustomer}/{actionAlias}?rowsoffset=0&rowscount=50&@Param=value

Parametre dopytu

Parameter	Predvolená hodnota	Popis
rowsoffset	0	Počet riadkov, ktoré sa majú preskočiť (pre stránkovanie)
rowscount	50	Počet riadkov, ktoré sa majú vrátiť (max. 1000)
e1key	–	Poverenie E1Key (alternatíva k hlavičke)
akýkoľvek iný kľúč	–	Akýkoľvek ďalší parameter z url bude preposlaný do akcie do ERPIO One

Príklad — Načítanie údajov

REQUEST


GET /api/v1/213/getmyserviceactivities?rowsoffset=0&rowscount=50
Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Príklad — S parametrami akcie

REQUEST


GET /api/v1/213/searchcompanies?rowsoffset=0&rowscount=20&@Name=ERPIO&@ICO=12345678
Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…

Príklad — Použitie E1Key v URL

REQUEST


GET /api/v1/213/getmyserviceactivities?e1key=my-e1key-value&rowscount=10

POST — Parametre v tele

_{Spôsoby autorizácie:}
Bearer token
E1Key header

POST /api/v1/{idCustomer}/{actionAlias}?rowsoffset=0&rowscount=50

Stránkovanie sa nachádza v reťazci dotazu. Telo je plochý objekt JSON, kde každý kľúč je názov parametra akcie. E1Key nie je v tele akceptovaný — použite hlavičku.

Príklad — Vytvorenie spoločnosti

REQUEST


POST /api/v1/213/newcompany?rowsoffset=0&rowscount=1
Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
Content-Type: application/json

{
"@Name": "TEST API s.r.o.",
"@ICO": "55443322",
"@JeSubberatel": "true"
}

RESPONSE


{
"id": 4821,
"name": "TEST API s.r.o.",
"ico": "55443322"
}

Príklad — S hlavičkou E1Key

REQUEST


POST /api/v1/213/getmyserviceactivities?rowscount=50
Autorization: e1key my-e1key-value
Content-Type: application/json

{}

Ak nemáte žiadne parametre akcie, odošlite ako telo prázdny objekt JSON {}.

Parametre akcie

Parametre akcie sú definované každou akciou v ERPIO One. Očakávané názvy parametrov nájdete v zozname parametrov v definícii akcie – alebo ich jednoducho odošlite tak, ako ich zdokumentoval váš administrátor ERPIO One.

Názvy parametrov zvyčajne začínajú znakom @ (napr. @Nazev, @ICO). Pri volaní cez klientské APAI sa nerozlišujú veľké a malé písmená a zhodujú sa s názvom parametra aj s názvom jeho hodnoty. Všetky parametre, ktoré neposkytnete, použijú svoje predvolené hodnoty z definície akcie.

Všetky hodnoty parametrov sa odosielajú ako reťazce. Dátový typ je určený definíciou akcie, nie typom hodnoty JSON.

Reťazené akcie (IDNext)

Niektoré akcie v ERPIO One sú reťazené – dokončenie jednej akcie automaticky spustí ďalšiu. API to rieši transparentne: sleduje reťazec až do 5 skokov a vracia konečný výsledok. Ak ktorákoľvek akcia v reťazci zlyhá, chyba sa okamžite vráti a reťazec sa zastaví.

Webhooky

Koncový bod POST /api/v1/{idCustomer}/{actionAlias} môže fungovať priamo ako cieľ webhooku. Keď externý systém doručí dáta webhooku na túto URL adresu, surové telo požiadavky sa automaticky prepošle do akcie ERPIO – nie je potrebná žiadna transformácia ani medzispracovanie.

Ako to funguje

Ak cieľová akcia v ERPIO One definuje parameter s názvom @__ydirectdatabody, brána ho zistí a nahradí jeho hodnotu celým surovým telom požiadavky ako reťazec pred odoslaním proti prúdu. Všetky ostatné parametre akcie si zachovajú svoje predvolené hodnoty z definície akcie.

Parameter @__ydirectdatabody musí byť deklarovaný v definícii akcie ERPIO One. Brána vloží telo iba v prípade, že parameter je už prítomný v zozname parametrov akcie.

Autentifikácia

Zdroje webhookov zvyčajne nemôžu nastaviť vlastné hlavičky. Na autentifikáciu bez hlavičky použite parameter dotazu e1key – je podporovaný pri akciách obsahujúcich parameter @__ydirectdatabody :

Cieľová URL adresa webhooku


POST /api/v1/213/processwebhookevent?e1key=hodnota-vašeho-e1kľúča

Príklad – užitočné zaťaženie webhooku JSON

Prichádzajúca požiadavka na webhook (z externého systému)


POST /api/v1/213/processwebhookevent?e1key=hodnota-vašeho-e1kľúča
Content-Type: application/json

{
"event": "order.created",
"orderId": 12345,
"amount": 4200.00
}

Celé telo – {"event":"order.created","orderId":12345,"amount":4200.00} – sa odovzdá ako reťazcová hodnota @__ydirectdatabody do nadradenej akcie. Odpoveď sa riadi štandardným formátom výsledku akcie.

Vkladanie surového tela sa vzťahuje iba na požiadavky POST. V požiadavkách GET bude hodnota @__ydirectdatabody prázdny reťazec.

Spracovanie chýb

Všetky chyby používajú konzistentný formát JSON s ID korelácie na sledovanie:

Formát odpovede na chybu

{
    "error": {
        "code": "ERROR_CODE",
        "message": "Popis čitateľný človekom.",
        "details": { … },
        "correlationId": "93e768dc-8d46-4f88-b009-9f5c853030ff"
    }
}

Kódy chýb

HTTP Status	Kód	Význam
401	`UNAUTHORIZED`	Nebolo poskytnuté žiadne overenie alebo sú prihlasovacie údaje neplatné
4xx	`ERPIOOneClientAPI_ERROR`	ERPIO One odmietlo požiadavku (napr. 404 akcia sa nenašla, 400 neplatné parametre)
502	`BAD_GATEWAY`	ERPIO One vrátilo chybu na strane servera
500	`INTERNAL_ERROR`	Neočakávaná chyba v tomto API
429	`---`	Prekročený limit počtu požiadaviek – pozri hlavičku `Retry-After`

ID korelácie

Každá odpoveď (vrátane chýb) obsahuje hlavičku X-Correlation-ID a rovnakú hodnotu v tele chyby. Použite toto ID pri hlásení problémov – prepojí vašu požiadavku s protokolmi servera.

Limit počtu požiadaviek

Obmedzenia rýchlosti chránia API pred zneužitím. Po prekročení limitu dostanete odpoveď 429 Too Many Requests s hlavičkou Retry-After, ktorá vám povie, koľko sekúnd máte čakať.

Endpoint	Limit	Časové okno	Stratégia
`POST /api/v1/login`	5 požiadaviek	za minútu, na IP adresu	Fixed window
`GET/POST /api/v1/…`	60 požiadaviek	za minútu, na IP adresu	Token bucket

Fixed window – Je to algoritmus, ktorý počíta počet požiadaviek v pevne danom časovom intervale (napr. každá minúta). Po prekročení limitu blokuje ďalšie požiadavky až do začiatku nového intervalu.

Token bucket – Systém pridáva „tokeny“ do vedra konštantnou rýchlosťou a každá požiadavka spotrebuje jeden token. Ak vedro nemá tokeny, požiadavky sa zamietajú, takže ide o flexibilnejšiu kontrolu rýchlosti ako fixed window.

Nepokúšajte sa o prihlásenie znova pri každej požiadavke. Získajte token raz a znova ho použite, kým nevyprší (expires_in seconds).