Visos kolekcijos
Darbas su Įvesk.lt sistema
API ir sąskaitų eksportavimo formatai
REST API
REST API

Everything you need to know how easily integrate your system with Įvesk.lt

Šarūnas Jončas avatar
Parašė Šarūnas Jončas
Atnaujinta prieš daugiau kaip savaitę

You can use REST API in JSON to upload files to Įvesk.lt and synchronize digitized results. Digitization could take up to 12 hours therefore file upload and result sync are separate actions and you choose to integrate with both or just one of them.

You can try out our interactive API here https://app.ivesk.lt/api/docs

Authorization

You need to pass x-api-key: <your secret api key> header with every request to API to be authorized to use API and access data.

You can generate your API key here https://app.ivesk.lt/settings/general

Upload file

File upload is a simple two step process:

  1. Get location from API where to upload file;

  2. Upload file;

Get location

To get the location where to upload the file, call:

GET https://app.ivesk.lt/api/pub/uploadlocation/<yourFileName>

Example:

curl --request GET \ 
   'https://app.ivesk.lt/api/pub/uploadlocation/somefile.pdf' \ 
   --header 'x-api-key: <your secret api key>'

Response:

{ 
    "url": "https://app.ivesk.lt/public/21d6d167-edda-4a87-a701-0e040e50ecfd?AWSAccessKeyId=ASIAQDMJYDC73OP47GHF&Content-Dispositio[...]", 
    "Content-Type": "application/pdf", 
    "Content-Disposition": "filename=\"somefile.pdf\"" 
}

You will get a temporary pre-signed URL and header values that will let you make a PUT request to our Amazon S3 bucket.

In case you need to know what file was processed and map it to your data, you can set userdata query parameter and we will return this data when you sync the results.

Upload

Use received URL and header values to upload file:

curl --request PUT 'https://<url from response>' \ 
   --header 'Content-Disposition: filename="failas.pdf"' \ 
   --header 'Content-Type: application/pdf' \ 
   --data-binary '@/path/to/somefile.pdf'

You will receive 200 HTTP status code if everything is ok. Otherwise consult S3 PutObject documentation for responses as you will be uploading files directly to Amazon S3.

Javascript example:

const fs = require('fs').promises;

async function index() {
    const signedUrlResponse = await fetch('https://app.ivesk.lt/api/pub/uploadlocation/<your-file-name: test.pdf>', {
        method: 'GET',
        headers: { 'x-api-key': '<your api key>' },
    });

    if (signedUrlResponse.ok) {
        const data = await signedUrlResponse.json();

        const fileBody = await fs.readFile('<path-to-your-file>');

        await fetch(data.url, {
            method: 'PUT',
            body: fileBody,
            headers: {
                'Content-Type': data['Content-Type'],
                'Content-Disposition': data['Content-Disposition'],
            },
        });
    }
}

index();

Synchronize results

When we finish digitizing the file, we put it in the digitized queue and the accountant is now able to see that the document is processed. Accountant inspects results, allocates expenses, vat class and other parameters. When they decide to import documents into the accounting system, they click Export to <accounting system name> button and those documents are then put in theput in to exported queue. You should choose one of the queues to integrate with. Here are some tips:

exported queue

digitized queue

Fully featured Įvesk.lt system:

  • Automatic expense allocation;

  • Accountant UI for more control of what, how and when to import into the accounting system;

  • API returns results after the accountant clicks Export to <accounting system name>

  • One API request returns single company invoices;

Just digitization service:

  • API returns results instantly after digitization is finished;

  • One API request returns multiple company invoices;

You should almost always integrate to the exported queue and give your accountant the best control and experience with the least integration time spent.

Choose digitized queue when you just want digitization service without additional helper features and you have your own UI and processes how to handle expense allocation, non-existent data in the accounting system etc.

You can constantly pull from the queue by sending a request with the from parameter to get new results. Documents are always sorted by digitizedat / exportedat and returned to you in ascending order. Responses contain results in pages of ~100 documents. You need to remember the last digitizedat / exportedat of a document and use it the next time you query for newly processed documents.

Example:

curl --request GET 'https://app.ivesk.lt/api/pub/exported?from=2020-12-18T11:52:42.313Z' \ 
   --header 'x-api-key: <your secret api key>'

Response:

{
    "$schema": "https://app.ivesk.lt/api/schema/jsonexport.json",
    "documents": [...], 
    "next": "2019-11-26T12:30:47.373Z"

}

Response schema with descriptions of document attributes can be found here: https://app.ivesk.lt/api/schema/jsonexport.json

If you get next in a response then there could be more data. You should repeat the query for the next page with [...]/exported?from=<next value> until the response does not have the next. next is basically the same as the last document exportedat.

Report synchronization errors

When you encounter error during invoice import into your accounting system you should report it to Įvesk.lt and let accountant know that the document was not synchronized. Accountant will be able to filter all the failed documents and see their error messages:

Example:

curl --request POST "https://app.ivesk.lt/api/pub/syncerrors"' \ 
   --header 'x-api-key: <your secret api key>'
   --data "{\"documentid\":\"7777707d-594d-420c-9174-ce278f823333\",\"companycode\":\"302320404\",\"message\":\"Country 'Japan' does not exist in the list.\"}"

Webhooks

You can listen for webhook events to know when new data is available to pull from Įvesk.lt. We support two types of webhooks:

  • on_digitized - when document was digitized

  • on_exported - when accountant clicked "Eksportuoti į <...>"

To get webhook events you have to subscribe and confirm your subscription.

Subscribe to webhook:

curl --request POST "https://app.ivesk.lt/api/pub/subscriptions"
     --header 'x-api-key: <your secret api key>'
     --data "{\"name\":\"SubscriptionName\",\"eventType\":\"on_exported\",\"target\":\"https://mydomain.com?secret=wehwev67sadv56\"}"

You will get POST to your target after webhook subscription. Initial JSON message will have "Type": "SubscriptionConfirmation" and SubscribeURL: "http<...>". Make a GET request to SubscribeURL to confirm the webhook subscription.

After confirmation you will be able to receive POST webhook events to your target with body similar to:

{
    "Type": "Notification",
    "MessageId": "403d0b09-f7de-556b-9961-537552b84bb0",
    "TopicArn": "arn:aws:sns:eu-west-1:007272210889:DPWebHook_onexport",
    "Message": "{\"companyCode\":\"302320404\"}",
    "Timestamp": "2021-01-16T08:26:14.705Z",
    "SignatureVersion": "1",
    "Signature": "dIeQZfeygLTBCD/esjrnh5EUu6EsbbqPp7w4pW930LQqBmes5mxIra2btsCJIqZix9UtrncFPXszAimK8ERNTUnf3azACF+4l5O6ETCIMGabNEzjhcVdiydMMajlmnRCGMiGWyWq1+37JO6sVMVAoOsRO8A8sxHGsMi9x+/FxzMV0RoGyMeDKf+wHMx8KclnSDpLvEVS89dpTLhBx9qwrzahjd3tvrG86hvZpipTraA+k5BLu4sB4kpvaop8dKqnAbA5/xEZ9ed5o+4sEbz02u5u2ELXOHQigIYuD10Oan3QdoMfpQsqNu8vRKjA6bw8CFAqWNT6B9YJKE0bVsFoQA==",
    "SigningCertURL": "https://sns.eu-west-1.amazonaws.com/SimpleNotificationService-010a507c1833636cd94bdb98bd93083a.pem",
    "UnsubscribeURL": "https://sns.eu-west-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:eu-west-1:007268210879:DPWebHook_onexport:e81cce37-a91c-41d1-a3fb-88806cf3dcc9",
    "MessageAttributes": {
        "account": {
            "Type": "String",
            "Value": "777756e2-a246-4031-93e2-5dcace3ccccc"
        }
    }
}

Message will have:

  • on_digitized - document data;

  • on_exported - companycode that new exported invoices exists;

Webhook event delivery retries

We will retry to deliver event up to 10 times with exponential backoff from 20 sec to 10 min. After that we will kill the message.

Tips

  • Upload files to Įvesk.lt as soon as you get them;

  • Add your file id in userdata so that you could match processed data to your file when you receive results;

  • Create hourly batch job or register Web Hook to pull results from Įvesk.lt;

  • When batch job starts you should pull pages until you get an empty page;

  • Remember last document exportedat / digitizedat or last page next for next batch job;

  • Use transaction for page (or document) processing and update your remembered exportedat / digitizedat just before transaction commit;

  • Report invoice import errors to Įvesk.lt;

  • Use realistic documents when testing, otherwise all will be rejected;

  • You can test Webhooks using something like https://requestbin.com/

Ar gavote atsakymą į savo klausimą?