Menu

KROS Fakturácia a Sklad

OpenAPI dokumentácia

 

English version of OpenAPI documentation

1. Úvod
2. Vytvorenie prepojenia a autorizácia odosielaných requestov
3. Podporované endpointy
   3.1. Špecifiká endpointov
   3.2. Ďalšie podrobnosti
4. Odpoveď na request
5. Webhook (URL pre príjem notifikácií z API)
   5.1. Prehľad možných chýb, ktoré môžu nastať pri spracovaní requestu
6. Kontrola správnosti notifikácie odoslanej do webhooku (voliteľné)
   6.1. Príklad vytvorenia hashu pre kontrolu
7. Vygenerovanie Open Api klienta pomocou Swagger Editora

 

1. Úvod

API rozhranie umožňuje používateľovi prenášať dáta medzi jeho programom (napr. eshop) a webovou aplikáciou KROS Fakturácia.

 

2. Vytvorenie prepojenia a autorizácia odosielaných requestov

API je dostupné na adrese https://api-economy.kros.sk/api/{resource}. Pre prístup ku 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’, ‘Kuriersky systém’ a pod.
  • URL pre príjem notifikácií z API : Nepovinný parameter. Ak sa rozhodnete využívať, zadajte URL Vášho API endpointu, na ktorý Vám budeme 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ť.

 

3. Podporované endpointy

Zoznam podporovaných endpointov nájdete tu:

https://api-economy.kros.sk/swagger/index.html

Tu si môžete API 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 získavaných aj odosielaných dokladov v jednej dávke je 100.

3.1. Špecifiká endpointov

  • POST endpointy dokladov (faktúry, zálohové faktúry a prijaté objednávky) slúžia súčasne na vytvorenie nových a aktualizáciu existujúcich dokladov. Aktualizáciu dokladov vykonávame v prípade jediného zhodujúceho sa čísla dokladu (vrátane číselnej rady).
    • Aktualizácia dokladu sa uskutoční pokiaľ request obsahuje doklad, ktorého číslo a kód číselnej rady už v databáze existujú. Ak sa takýto doklad nachádza v databáze viackrát, alebo je zamknutý inak ako nahratím cez OpenAPI, odošle sa vo webhooku chybová hláška s informáciou o nemožnosti vykonať aktualizáciu dokladu.
  • Vytvorenie dokladu (napr. faktúra, prijatá objednávka) vykoná zároveň aj založenie nového partnera, ak taký ešte neexistuje. Duplicita partnera je kontrolovaná na viacerých úrovniach a je realizovaná rozdielne pre fyzické a právnické osoby. Pri fyzických osobách sú základnými porovnávacími parametrami meno a e-mailová adresa. Pri právnických osobách sú to IČO, DIČ a IČ DPH, až následne meno a adresa.
  • Pokiaľ položky posielané na doklade majú vyplnený atribút itemCode, kontroluje sa ich existencia v sklade. V prípade zhody sa položky napárujú na príslušnú skladovú kartu. Ak itemCode nie je zadaný, porovnanie sa vykonáva podľa názvu. Skladovým položkám je možné posielať aj atribút warehouseCode, ktorý zabezpečí priradenie položky k existujúcemu skladu. ItemCode je možné posielať len pre skladové karty.
  • Endpointy, ktoré vrátia pole požadovaných entít, implementujú stránkovací mechanizmus za pomoci parametrov top a skip.
  • Endpoint /api/catalog-items má možnosť využitia parametra CatalogItemChangedTimestamp, ktorý zabezpečí optimálnejšie sťahovanie skladových kariet. Znamená to, že pri každom volaní nebude potrebné sťahovať všetky položky, ale iba položky zmenené od zadanej časovej pečiatky.
  • Endpoint /api/payments/batch slúži na pridávanie úhrad na doklady uložené v KROS Fakturácii. Na konkrétne doklady sa úhrady priraďujú podľa variabilného symbolu. V prípade zhodujúcich sa variabilných symbolov na viacerých dokladoch sa priraďovanie vykoná na základe sumy a dátumu vystavenia dokladov (od najstaršieho). Pokiaľ variabilný symbol existuje v zálohových faktúrach aj v riadnych faktúrach, úhrady sú priraďované len na zálohové faktúry.
  • Aktualizácia dokladu sa uskutoční v prípade, že request obsahuje doklad, ktorého číslo a kód číselnej rady už v databáze existujú. Ak sa takýto doklad nachádza v databáze viackrát, alebo je zamknutý inak ako nahratím cez Open API, odošle sa vo webhooku chybová hláška s informáciou o nemožnosti vykonať aktualizáciu dokladu.
  • V jednom requeste nie je povolený viacnásobný výskyt dokladu s rovnakým číslom v rámci jednej číselnej rady.

3.2. Ďalšie podrobnosti

  • Variabilný symbol – variabilný symbol je možné prostredníctvom API nastaviť nasledovne:
    • Konkrétny variabilný symbol – vami požadovanú hodnotu pošlite do atribútu variableSymbol.
    • Variabilný symbol podľa čísla dokladu – variabilný symbol sa automaticky preberie z čísla dokladu (funguje aj pri automatickom generovaní čísla dokladu) očistený o nepovolené znaky. Tento variant funguje automaticky, variableSymbol nie je potrebné posielať vôbec.
    • Prázdny variabilný symbol – ak variabilný symbol vôbec nepoužívate, nastavte variableSymbol ako prázdny string.
  • Číslo dokladu – v prípade, ak pošlete documentNumber ako prázdny string, prípadne ho nepošlete vôbec, generovanému dokladu bude číslo dokladu nastavené automaticky podľa číselnej rady. Pokiaľ daný atribút pošlete s konkrétnou hodnotou, táto sa generovanému dokladu nastaví ako číslo dokladu.
  • Notifikácie o úhradách do API – Aktivovaním tejto voľby v nastaveniach KROS Fakturácie v časti „API prepojenia“ sa z fakturácie začnú odosielať informácie o zaevidovaných úhradách prostredníctvom webhook správy na adresu zadanú v časti URL pre príjem notifikácií z API. Po zadaní úhrady na faktúru/zálohovú faktúru bude automaticky odoslaná notifikácia o stave uhradenosti príslušného dokladu. Informácie sa odosielajú aj pri automaticky priradených úhradách.

 

4. 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.
  • 405 - Method not allowed: Endpoint nie je podporovaný alebo je vo vývoji.
  • 429 - Too Many Requests: Na ochranu pred zahltením API sme zaviedli limit v počte 10 requestov za sekundu a 300 za minútu.
  • 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.

 

5. 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 (viac v Kontrola správnosti notifikácie odoslanej do webhooku).

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, External Id (ak ste ho pri nahrávaní poskytli) a prípadné dalšie údaje na identifikáciu dokladov, ID firmy a URL na endpoint, odkiaľ môžete dané doklady stiahnuť.

Odpoveď obsahuje aj indexy založených, prípadne upravených dokladov a súvisiacich entít, ktoré odpovedajú indexom dokladov poslaných vami v json dátach.

V prípade neúspechu zápisu niektorého z odoslaných dokladov, budete informovaný o tom, ktorý doklad sa nepodarilo založiť a prečo.

Pre sledovanie celkovej úspešnosti spracovania slúži atribút status. Ak je všetko v poriadku, vráti sa 200. Ak sa vyskytne nejaká chyba, vráti sa 207 a v problems sa nachádza zoznam chýb, ktoré môžu nastať pri spracovaní requestu.

Príklad

{
  "companyId": 119919,
  "entityType": 2,
  "results": {
    "entities": [
      {
        "index": 0,
        "source": 1,
        "oparation" : 2,
        "status": 201,
        "data": {
          "documentType": 2,
          "documentId": 926523,
          "variableSymbol": "4444555",
          "sumOfPayment": 1,
          "dateOfPayment": "2023-09-26T00:00:00",
          "hasRelatedEntity": true
        },
        "problems": null
      },
      {
        "index": 1,
        "status": 201,
        "data": null,
        "problems":  [
            {
            "type": "http://api-economy.kros.sk/problems/resource-locked",
            "title": "Resource is locked",
            "detail": "Resource is locked by non-editable lock, therefore the resource cannot be edited."
            }
        ]
      }
    ],
    "relatedEntityType": 1,
    "relatedEntities": [
      {
        "companyId": 119919,
        "documentType": 2,
        "documentId": 926523,
        "numberingSequence": "OF",
        "documentNumber": "20230008a",
        "variableSymbol": "4444555",
        "sumOfPayments": 2,
        "countOfPayments": 2,
        "paymentStatus": 3,
        "orderNumber": "123456789",
        "totalPriceInclVat": 96
      }
    ]
  },
  "status": 200,
  "apiUrl": "",
  "requestId": "50304274-197c-40e9-8804-84e23e28efa2"
}

5.1. Prehľad chýb, ktoré môžu nastať pri spracovaní requestu

Type Title Detail
http://api-economy.kros.sk/problems/resource-locked Resource is locked Resource is locked by non-editable lock, therefore the resource cannot be edited.
http://api-economy.kros.sk/problems/id-conflict Identification conflict in database Resource cannot be uniquely identified, therefore the resource cannot be edited.
http://api-economy.kros.sk/duplicate-document-number Duplicate document number in request Resource with this documentNumber and numberingSequence has been sent more than once, causing conflict. Please send the resource again making sure that the documentNumber and numberingSequence are unique in a batch.

 

6. Kontrola správnosti notifikácie odoslanej do webhooku (voliteľné)

Na overenie, že správa, ktorú ste dostali do poskytnutej webhook URL pochádza skutočne z 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. Hash je vytváraný pomocou kódovania UTF-16 Little Endian (UTF-16LE). Pri rekonštrukcii hashu je teda potrebné skonvertovať aj dáta (payload) aj kľúč na vyššie spomínané kódovanie reťazcov.

6.1. 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) {
    $keyEncoded = mb_convert_encoding($key, "UTF-16LE");
    $dataEncoded = mb_convert_encoding($data, "UTF-16LE");
    return base64_encode(hash_hmac("sha256", $dataEncoded, $keyEncoded, true));
}

7. Vygenerovanie Open API klienta pomocou Swagger Editora

  • Otvorte v prehliadači Swagger Editor.
  • V novej záložke prehliadača otvorte Swagger dokumentáciu KROS OpenAPI.
  • Na stránke dokumentácie klikinte na link /swagger/v1/swagger.json.
  • Skopírujte obsah zobrazeného JSON dokumentu a vložte ho do ľavej časti Swagger Editora.
  • V pravom hornom rohu Swagger editora kliknite na tlačidlo Generate Client a vyberte si jazyk, v ktorom chcete mať vygenerovaného klienta.
  • Vygenerovaného klienta si môžete stiahnuť kliknutím na tlačidlo Download v pravom hornom rohu.
KROS
Zmeniť heslo Odhlásiť sa
O nás
Blog
Kontakty