Menu

KROS Fakturácia

OpenAPI documentation

Slovenská verzia dokumentácie pre OpenAPI

Preface 

API interface allows user to communicate between KROS Fakturácia and his own custom application (for example eshop). 

How to create connection and authorize requests

You can access API on URL https://api-economy.kros.sk/api/{resource}. HTTPS is required and every request must authorize using Bearer Token stored in header Authorization, e.g. Authorization: Bearer MyToken.

Auth token can be created in company settings in KROS Fakturácia, in section API prepojenia:

  • Názov prepojenia – Name of connection: Required. Can be used for identification in case of multiple connections, for example ‘My eshop’, ‘Courier’, …
  • URL pre príjem notifikácií z API – Webhook URL for notifications from API: Optional. If you choose to use it, give URL address of endpoint in your API, where we can send notifications about finished document uploads and so on (more in Webhook section).
  • Autorizačný kľúč k zadanej URL – Secret for Webhook: Optional. It is used in combination with webhook URL, so you can check if notification really originated at KROS OpenAPI (more in section Notification origin check).
  • Vygenerovať token – Generate token: Use button to generate your token. Please make sure you copy and save the token. We don’t store it, so if you lose it, you will have to regenerate to get new valid token. Old token loses validity by reset.

Supported endpoints

List of available endpoints can be found at https://api-economy.kros.sk/swagger/index.html. Here you can try API, check examples and schemas of each request. Of course, you have to be authorized to send requests (button Authorize top right corner).

You should use valid JSON and UTF-8 for communication. Dates should be in ISO 8601 format: 2022-12-07T08:56:08.693Z

Maximum number of documents in one batch is 100.

API response

After you sent request API does some validation of data and returns response. Data are processed and uploaded to KROS Fakturácia asynchronously and you will be notified about it with Webhook notification, sent to address you provided in settings in input URL pre príjem notifikácií z API (more in section Webhook).

Types of responses:

  • 202 – Accepted: Data accepted for upload. You will be informed when upload finishes using notification send to webhook URL, if you provided it. Response also contains requestId. This ID can be used to pair notification from webhook with sent request.

Example of OK response

{
   “requestId”: “3fa85f64-5717-4562-b3fc-2c963f66afa6”
}

  • 400 – Bad Request: Some required properties missing, or unsupported value is used. Response JSON contains errors property with detailed info about wrong part of data.

BadRequest response example

{
   “isValid”: false,
   “errors”: [
      {
         “documentIndex”: 0,
         “propertyPath”: “items[0].amount”,
         “errorMessage”: “Unexpected character encountered while parsing value: a.”
      }
   ]
}

  • 401 – Unauthorized: Request doesn’t contain auth token, or token is not valid. 
  • 402 – Payment Required: Company with unsufficient or expired license.
  • 429 – Too Many Requests: If you send too many requests in short period of time. Limit is currently set to 5 requests per second. 
  • 409 – Conflict: As precaution against duplicated documents, it is not possible to send same request more times, after first request received 202 response. There is window of 120 seconds for this check, so if you really want to upload duplicates, you have to wait. 

Webhook (URL for receiving notifications from API)

Webhook URL should be simple endpoint in your API, publicly accessible, on which we can send POST requests. We recommend to use some form of rate limiting and you can also check if notification came from KROS OpenAPI (more in Check origin of webhook notification).

Body of notification message contains information if upload was successful or not. Successful answer also contains IDs of uploaded documents, your identification as externalId, if you provided it, CompanyId and URL of API GET endpoint for retrieving all of document info.

Example

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

Check origin of webhook notification

If you want to check if notification you received is in fact from KROS API, we add header X-Kros-Signature-256. This header contains hashed body of notification message, computed using HCMASSHA256 algorithm and converted to Base64String. Hash is computed using webhook secret key you saved in company settings. Recommended key length is 256 bits.

Examples on how to compute hash

Payload/$data is body of request (JSON with data). Computed value then compare with value from header 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));
}

KROS
O nás
Blog
Kontakty