Úvod
API rozhranie umožňuje používateľovi prenášať dáta medzi jeho programom (napr. eshop) a webovou aplikáciou KROS Fakturácia.
Vytvorenie prepojenia a autorizácia odosielaných requestov
API je dostupné na adrese https://api-economy.kros.sk/api/{resource}. Pre prístup k službám sa požaduje HTTPS pripojenie a autorizácia tokenom vloženým do hlavičky dotazu s názvom Authorization. Token sa používa ako tzv. Bearer token: Authorization: Bearer MojToken.
Autorizačný token si viete vytvoriť v nastaveniach firmy v KROS Fakturácii, v sekcii API prepojenia:

- Názov prepojenia: Povinný parameter. Môžete použiť na identifikáciu prepojení, napr. ‘E-shop mojeshop.sk’, ‘Kuriérsky systém’ a pod.
- URL pre príjem notifikácíi z API: Nepovinný parameter. Ak sa rozhodnete využívať, zadajte URL vášho API endpointu, na ktorý vám budeme automaticky posielať notifikácie, napr. o ukončenom importe dokladov (viac v sekcii Webhook).
- Autorizačný kľúč k zadanej URL: Nepovinný parameter. Používa sa v kombinácii s nastavením URL pre príjem notifikácií z API, na kontrolu správnosti prijatej notifikácie (viac v sekcii Kontrola správnosti notifikácie).
- Vygenerovať token: Tlačidlom vygenerujete váš token. Tento token si uschovajte! Už sa k nemu nedostanete. Jediný spôsob, ako získať token pre prepojenie, je resetovať ho. Resetovaním stráca pôvodný token platnosť.
Podporované endpointy
Zoznam podporovaných endpointov nájdete tu:
https://api-economy.kros.sk/swagger/index.html
API si tam môžete aj vyskúšať, pozrieť vzorové príklady a schémy jednotlivých requestov. Samozrejme sa treba najskôr autorizovať (tlačidlo Authorize vpravo hore).
Požadovaný výmenný formát dát je JSON a UTF-8 kódovanie. Pri dátumoch treba dodržiavať ISO 8601 formát: 2022-12-07T08:56:08.693Z
Maximálny možný počet dokladov v jednej dávke je 100.
Odpoveď na request
Po odoslaní requestu prebehne základná validácia dát, na ktorú dostanete odpoveď. Spracovanie dotazu prebieha až následne a výsledok spracovania dostanete formou Webhook správy na adresu, ktorú ste zadali v nastaveniach URL pre príjem notifikácií z API (viac v sekcii Webhook).
Odpovede na request môžu byť:
- 202 – Accepted: Dáta boli akceptované na nahratie. O tom, že boli skutočne nahraté, Vás budeme notifikovať pomocou poskytnutého webhooku. V odpovedi dostanete requestId. Toto ID môžete použiť, ak využívate notifikácie cez webhook a chcete si priradiť notifikáciu k requestu. V notifikácii cez webhook toto requestId bude tiež.
Príklad OK odpovede
{
“requestId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}
- 400 – Bad Request: V dátach bude niečo chýbať alebo bude nejaká odpoveď neprípustná. V časti “errors” dostanete vysvetlenie čo a na akom mieste bolo zadané nesprávne.
Príklad BadRequest odpovede
{
“isValid”: false,
“errors”: [
{
“documentIndex”: 0,
“propertyPath”: “items[0].amount”,
“errorMessage”: “Unexpected character encountered while parsing value: a.”
}
]
}
- 401 – Unauthorized: Request s nesprávnym alebo chýbajúcim autorizačným tokenom.
- 402 – Payment Required: Firma s nedostatočnou alebo vypršanou licenciou.
- 429 – Too Many Requests: Na ochranu pred zahltením API sme zaviedli limit v počte requestov za sekundu – maximálne 5.
- 409 – Conflict: Ako prevenciu pred nahrávaním duplicitných dokladov nie je možné rovnaký request poslať viackrát za sebou, pokiaľ prvý request prešiel (202-Accepted). Ak je to potrebné, treba počkať 120 sekúnd.
Webhook (URL pre príjem notifikácií z API)
Webhook URL by mal byť jednoduchý endpoint vo vašej API, verejne prístupný, na ktorý vieme posielať POST správy. Odporúčame pri jeho zapracovaní zaviesť nejakú formu rate limit-ingu a taktiež využiť možnosť overenia či bola notifikácia odoslaná z KROS OpenAPI.
V tele takejto správy dostanete informácie o úspešnom alebo neúspešnom spracovaní dotazu. V úspešnej odpovedi budú ID vytvorených dokladov, ExternalId (ak ste ho pri nahrávaní poskytli) a prípadné ďalšie údaje na identifikáciu dokladov, ID firmy a URL na endpoint, odkiaľ môžete dané doklady stiahnuť.
Príklad
{
“companyId”: 5587,
“createdEntities”: {
“documents”: [
{
“id”: 22596,
“externalId”: “101”,
“numberingSequence”: “OF”,
“documentNumber”: “20210512001”,
“documentType”: 2
},
{
“id”: 22597,
“externalId”: “102”,
“numberingSequence”: “OF”,
“documentNumber”: “20210512002”,
“documentType”: 2
}
]
},
“entityType”: 1,
“isSuccessful”: true,
“apiUrl”: “http://example/endpoint/{id}”,
“requestId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}
Kontrola správnosti notifikácie odoslanej do webhooku (voliteľné)
Na overenie, že správa, ktorú ste dostali do poskytnutej webhook URL, je skutočne od KROS OpenAPI, pripájame k requestu hlavičku X-Kros-Signature-256. Táto hlavička obsahuje hash správy requestu, vytvorený pomocou algoritmu HCMASSHA256 a konvertovaný na Base64String. Hash sa vytvára z tela notifikácie pomocou kľúča, ktorý ste si nastavili vo firme. Odporúčaná dĺžka kľúča je 256 bitov.

Príklad vytvorenia hashu pre kontrolu
Payload je telo requestu (JSON s dátami). Vypočítanú hodnotu potom porovnáme s obsahom hlavičky X-Kros-Signature-256.
c#
private string? GenerateHash(string payload, string webHookSecret)
{
var hash = new HMACSHA256(Encoding.Unicode.GetBytes(webHookSecret));
return Convert.ToBase64String(hash.ComputeHash(Encoding.Unicode.GetBytes(payload)));
}
php
function($data, $key) {
return base64_encode(hash_hmac(“sha256”, $data, $key, true));
}