KROS Fakturácia

Ú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.

{
      “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”
}

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));
}