Menu

KROS Fakturácia a Sklad

OpenAPI documentation 

 

Slovenská verzia dokumentácie pre OpenAPI

1. Preface
2. How to create connection and authorize requests
3. Supported endpoints
   3.1. Endpoint specifics
   3.2. More details
4. API Response
5. Webhook (URL for receiving notifications from API)
   5.1. Overview of possible problems
6. Check origin of webhook notificiation
   6.1. Examples on how to compute hash
7. Generate an Open Api client using Swagger Editor

 

1. Preface

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

 

2. 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ácíi 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 loose it, you will have to regenerate to get new valid token. Old token looses validity by reset.

 

3. 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 either sent or received in one batch is 100.

3.1. Endpoint specifics

  • POST document endpoints (invoices, advance invoices and received orders) serve simultaneously to create new and update existing documents. We update documents in the case of a single matching document number (including the number line).
    • The document will be updated if the request contains a document whose number and number series code already exist in the database. If such a document is in the database more than once, or if it is locked otherwise than by uploading via OpenAPI, an error message is sent in the webhook with information about the impossibility of updating the document.
  • Creating a document (e.g. invoice, received order, proforma invoice) also creates a new partner, if one does not already exist. Partner duplication is checked at several levels and is implemented differently for natural and legal persons. For natural persons, the basic comparison parameters are name and e-mail address. For legal persons, these are the registration number, tax number and VAT number, followed by name and address.
  • If items sent on the document have the itemCode attribute filled in, their existence in the warehouse is checked. If there is a match, the items are matched to the corresponding stock card. If itemCode is not specified, the comparison is performed by name. Stock items are also possible to be sent with the warehouseCode attribute, which will ensure that the item is assigned to an existing warehouse. ItemCode can only be sent for stock cards.
  • Endpoints that return an array of requested entities implement the paging mechanism using the top and skip parameters.
  • Enpoint /api/catalog-items has a option to use a parameter CatalogItemChangedTimestamp which ensures more optimal download of catalog items. By using mentioned parameter, only catalog items, that were changed after the timestamp will be downloaded.
  • Endpoint /api/payments/batch is used for adding payments to documents stored in KROS Invoicing. Payments are assigned to specific documents according to a variable symbol. In the case of matching variable symbols on several documents, the assignment is made on the basis of the sum and date of issuance of the documents (from the oldest). If the variable symbol exists in advance invoices as well as in regular invoices, payments are assigned only to proforma invoices.
  • The document will be updated if the request contains a document whose number and number series code already exist in the database. If such a document is in the database more than once, or is locked otherwise than by uploading via the Open API, an error message is sent in the webhook with information about the impossibility of updating the document.
  • Multiple occurrences of a document with the same number within one number series are not allowed in the request.

3.2. More details

  • Variable symbol – the variable symbol can be set via the API as follows:
    • Specific variable symbol – send the desired value to the variableSymbol attribute.
    • Variable symbol according to the document number – the variable symbol is automatically taken from the document number (also works with automatic generation of the document number) cleared of disallowed characters. This variant works automatically, variableSymbol does not need to be sent at all.
    • Empty variable symbol – if you do not use the variable symbol at all, set variableSymbol as an empty string.
  • Document number – if you send documentNumber as an empty string, or if you don’t send it at all, the document number will be set automatically according to the number sequence for the generated document. If you send the given attribute with a specific value, this will be set as the document number for the generated document.
  • Payment notifications to the API – By activating this option in the KROS Invoicing settings, invoicing will start sending information about registered payments via a webhook message to the address entered in the URL section for receiving notifications from the API. After entering the payment on the invoice/proforma invoice, a notification will be automatically sent about the payment status of the relevant document. Information is also sent for automatically assigned payments.

4. 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 insufficient or expired license.
  • 405 - Method not allowed: Endpoint is not supported or being developed.
  • 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.

 

5. 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 also check if notification came from KROS OpenAPI (more in Check origin of webhook notification).

In the body of a notification message, you will receive information about the successful or unsuccessful processing of the query. The successful response will contain the ID of the created documents, External Id (if you provided it when uploading) and any other data to identify the documents, the company ID and the URL to the endpoint, from where you can download the documents.

The response also contains the indexes of established or modified documents and related entities, which correspond to the indexes of the documents sent by you in the json data.

In case of failure to register any of the sent documents, you will be informed about which document could not be created and why.

The attribute Status is used to monitor the overall success of the processing. If all is well, 200 will be returned. If an error occurs, 207 is returned and in Problems there is a list of errors that may occur during request processing.

Príklad

{
  "CompanyId": 119919,
  "EntityType": 2,
  "Results": {
    "Entities": [
      {
        "Index": 0,
        "Status": 201,
        "Data": {
          "DocumentType": 2,
          "DocumentId": 926523,
          "VariableSymbol": "4444555",
          "SumOfPayment": 1,
          "DateOfPayment": "2023-09-26T00:00:00",
          "HasRelatedEntity": true,
          "Index": 0
        },
        "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. Overview of errors that may occur during request processing

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. Check origin of webhook notificiation

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. The hash is created using encoding UTF-16 Little Endian (UTF-16LE). For the hash reconstruction is therefore needed to encode payload and a key with mentioned encoding.

6.1. Examples on how to compute hash

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

 

7. Generate an Open API client using the Swagger Editor

  • Open the Swagger Editor in your browser.
  • In a new browser tab, open the Swagger documentation KROS OpenAPI.
  • On the documentation page, click on the link /swagger/v1/swagger.json.
  • Copy the contents of the displayed JSON document and paste it in the left part of the Swagger Editor.
  • In the upper right corner of the Swagger editor, click the Generate Client button and choose the language in which you want to have the client generated.
  • You can download the generated client by clicking the Download button in the upper right corner.
KROS
Zmeniť heslo Odhlásiť sa
O nás
Blog
Kontakty