Examples | Procountor Developers

Examples

Here are some examples on how to use our API. You can find more examples from Procountor's online manual.

Procountor API use cases in online manual

Posting a sales invoice

One of the most common use cases for Procountor API is posting sales invoices from an external system to Procountor Financials. Assuming you have acquired an access token as described on the API authentication page, you can make requests to our endpoints listed on the API reference.

The API reference shows which fields in the invoice model are optional. This example presents a minimalistic sales invoice with bank transfer as payment method. To that model, you can add optional fields according to your needs.

First, make sure you have set up a bank account in your Procountor Financials environment. As we know, sales invoices with bank transfer as payment method require a bank account the buyer will pay the invoice to. The bank account can be set in Procountor Financials by using the guided onboarding tool or navigating directly to the page called Bank account information.

Regarding sales invoices, we refer to the buyer as the counter party of the invoice.

Request

We can create a simple sales invoice with the following request.

POST https://api.procountor.com/api/invoices HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json

{
  "type": "SALES_INVOICE",
  "status": "UNFINISHED",
  "date": "2020-10-01",
  "counterParty": {
    "counterPartyAddress": {
      "name": "Buyer name"
    }
  },
  "paymentInfo": {
    "paymentMethod": "BANK_TRANSFER",
    "currency": "EUR",
    "bankAccount": {
        "accountNumber" : "FI2799999900031563"
    },
    "dueDate": "2020-10-11",
    "currencyRate": 1
  },
  "extraInfo": {
    "accountingByRow": false,
    "unitPricesIncludeVat": false
  },
  "discountPercent": 0,
  "invoiceRows": [
     {
      "product": "Coffee cup",
      "quantity": 2,
      "unit": "PIECE",
      "unitPrice": 3.5,
      "discountPercent" : 0,
      "vatPercent": 24
    }
  ],
  "vatStatus": 1,
  "invoiceChannel": "NO_SENDING",
  "language": "FINNISH"
}

Notice that every value of the invoice fields is validated. For example, value of the accountNumber field must represent a valid and existing bank account. In addition to that and general format validation rules, some validations depend on the settings of the current environment. In this example, that means the value of the vatPercent field must match the VAT (Value Added Tax) settings of your environment which in turn reflect the VAT regulations in your country.

Response

A response with HTTP status code 200 indicates a successful request. The response body contains the invoice model that was saved into Procountor database. Practically, you will receive the original invoice with a couple of ID fields added: id and ledgerreceiptId.

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 01 Oct 2020 12:00:00 GMT
Content-Type: application/json
Content-Length: 935
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Credentials

{
  "id": 8485084,
  "partnerId": null,
  "type": "SALES_INVOICE",
  "status": "UNFINISHED",
  "date": "2020-10-01",
  "counterParty": {
    "counterPartyAddress": {
      "name": "Buyer name"
    },
    "bankAccount": {},
    "einvoiceAddress": {}
  },
  "billingAddress": {
    "name": "Buyer name"
  },
  "deliveryAddress": {
    "name": "Buyer name"
  },
  "paymentInfo": {
    "paymentMethod": "BANK_TRANSFER",
    "currency": "EUR",
    "bankAccount": {
      "accountNumber": "FI2799999900031563"
    },
    "dueDate": "2020-10-11",
    "currencyRate": 1.00000000,
    "paymentTermPercentage": 0.0000,
    "cashDiscount": {
      "numberOfDays": 0,
      "discountPercentage": 0.0000
    }
  },
  "extraInfo": {
    "accountingByRow": false,
    "unitPricesIncludeVat": false
  },
  "discountPercent": 0.0000,
  "invoiceRows": [
    {
      "id": 61697769,
      "productId": null,
      "product": "Coffee cup",
      "quantity": 2.000000,
      "unit": "PIECE",
      "unitPrice": 3.500000,
      "discountPercent": 0.0000,
      "vatPercent": 24.00
    }
  ],
  "invoiceNumber": 3,
  "vatStatus": 1,
  "invoiceChannel": "NO_SENDING",
  "language": "FINNISH",
  "ledgerReceiptId": 14068672,
  "factoringContractId": null
}

Posting a journal (ledger receipt)

Another common use for Procountor API is posting journals containing accounting data. As a prerequisite for using this feature, basic knowledge of accounting is assumed. For instance, choosing the correct vatStatus and the choice between CREDIT and DEBIT depends on the case.

Note that correct ledger accounts must be known before making the request. The chart of accounts for the current environment can be fetched by using the GET /coa endpoint.

Request

The following request creates a simple journal type ledger receipt:

POST https://api.procountor.com/api/ledgerreceipts HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json

{
  "type": "JOURNAL",
  "status": "UNFINISHED",
  "name": "Example journal",
  "receiptDate": "2020-10-10",
  "vatType": "PURCHASE",
  "vatStatus": 1,
  "transactions": [
    {
      "transactionType": "REVERSING_ENTRY",
      "account": "1900",
      "accountingValue": -44,
      "vatPercent": 0
    },
    {
      "transactionType": "ENTRY",
      "account": "4000",
      "accountingValue": 44,
      "vatPercent": 0
    }
  ]
}

Response

The response with HTTP status code 200 will contain the assigned receiptId as well as other details, such as version timestamp, generated in Procountor.

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 01 Oct 2020 12:00:00 GMT
Content-Type: application/json
Content-Length: 631
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Credentials

{
  "id": 14068674,
  "receiptId": 14068674,
  "type": "JOURNAL",
  "status": "UNFINISHED",
  "name": "Example journal",
  "receiptDate": "2020-10-10",
  "vatType": "PURCHASE",
  "vatStatus": 1,
  "invoiceId": 8485086,
  "invoiceNumber": 1,
  "receiptValidity": "EMPTY",
  "version": "2020-07-17T15:23:31",
  "depreciation": "EMPTY",
  "transactions": [
    {
      "id": 101264271,
      "transactionId": 101264271,
      "transactionType": "REVERSING_ENTRY",
      "account": "1900",
      "accountingValue": -44.00,
      "vatPercent": 0.0000,
      "vatDeductionPercent": 100.0000
    },
    {
      "id": 101264272,
      "transactionId": 101264272,
      "transactionType": "ENTRY",
      "account": "4000",
      "accountingValue": 44.00,
      "vatPercent": 0.0000,
      "vatDeductionPercent": 100.0000
    }
  ]
}

Should you like to add an attachment to the journal, use the invoiceId provided for linking as described in the API reference.

Adding an attachment to an invoice

Procountor API allows to attach files to certain resources, such as invoices and ledger receipts. These attachments can be accessed through the API or on the UI. The target resource must exist in Procountor prior to posting the attachment.

In this example, let us assume we have an invoice with id 8485084 and a JPG file named picture.jpg.

Request

The request to add attachments contains two parts: the file as file parameter value and the meta data as meta parameter value. The full request would look something like the following.

POST https://api.procountor.com/api/attachments HTTP/1.1
Authorization: Bearer <access token>
Content-Type: multipart/form-data; boundary=----------

----------
Content-Disposition: form-data; name="meta"
Content-Type: application/json

{
  "name": "Example picture.jpg",
  "referenceType": "INVOICE",
  "referenceId": 1234
}
----------
Content-Disposition: form-data; name="file"; filename="example.jpg"
Content-Type: image/jpeg

<image data here>
----------

Here are two things to notice.

First, make sure you include the correct file extension to the attachment name. Otherwise, the attachment will not be shown correctly on the UI.
Second, the mimeType field listed in the reference is determined based on the file extension. It is thus ignored when posting the attachment, but present in the response and when getting a particular attachment.

Response

A successful request will result in a response with HTTP status code 200. The response contains the meta data of the file sent. In addition to the fields posted, the meta data now includes an attachmentId generated by Procountor and the mimeType determined from the file extension.

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 01 Oct 2020 12:00:00 GMT
Content-Type: application/json
Content-Length: 128
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Credentials

{
  "id": 13522,
  "name": "example.jpg",
  "referenceType": "INVOICE",
  "referenceId": 8485084,
  "mimeType": "image/jpeg",
  "sendWithInvoice": true
}

Defining accounting information for invoices

To define accounting information such as ledger accounts, dimensions and VAT status for an invoice, first create an invoice as shown by the earlier example. The invoice returned by the server contains the ledgerreceiptId for the ledger receipt that was automatically generated to hold the accounting information of the invoice. To modify that accounting information, update the ledger receipt as follows:

Get the ledger receipt

Using the ledgerreceiptId, make a GET request to the /ledgerreceipts/{ledgerreceiptId} endpoint to get the ledger receipt in its current form.

GET https://api.procountor.com/api/ledgerreceipts/14068672 HTTP/1.1
Authorization: Bearer <access token>

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 01 Oct 2020 12:00:00 GMT
Content-Type: application/json
Content-Length: 806
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Credentials

{
  "id": 14068672,
  "type": "SALES_INVOICE",
  "status": "UNFINISHED",
  "name": "Buyer name",
  "receiptDate": "2020-10-01",
  "vatType": "SALES",
  "vatStatus": 1,
  "invoiceId": 8485084,
  "invoiceNumber": 3,
  "version": "2020-07-17T15:17:48",
  "transactions": [
    {
      "id": 101264266,
      "transactionId": 101264266,
      "transactionType": "REVERSING_ENTRY",
      "account": "1700",
      "accountingValue": 8.68,
      "vatPercent": 0.0000
    },
    {
      "id": 101264265,
      "transactionId": 101264265,
      "transactionType": "ENTRY",
      "account": "3000",
      "accountingValue": -7.00,
      "vatPercent": 24.0000
    },
    {
      "id": 101264267,
      "transactionId": 101264267,
      "transactionType": "RECONCILIATION_ENTRY",
      "account": "8890",
      "accountingValue": 0.00,
      "vatPercent": 0.0000
    }
  ],
  "attachments": [
    {
      "id": 13522,
      "name": "example.jpg",
      "referenceType": "INVOICE",
      "referenceId": 8485084,
      "mimeType": "image/jpeg",
      "sendWithInvoice": true
    }
  ]
}

Modify the ledger receipt

Modify the ledger receipt as required. For instance, you may add a vatStatus field to it or change the values of account fields in its transaction objects. Furthermore, transactions allow defining a value for dimensionItemValues field to assign dimension items and their values to a particular transaction, which is what we are doing now.

Use PUT /ledgerreceipts/{ledgerreceiptId} to supply the updated ledger receipt. Remember to include the original version timestamp to the request.

PUT https://api.procountor.com/api/ledgerreceipts/14068672 HTTP/1.1
Authorization: Bearer <access token>
Content-Type: application/json

{
  "id": 14068672,
  "type": "SALES_INVOICE",
  "status": "UNFINISHED",
  "name": "Buyer name",
  "receiptDate": "2020-10-01",
  "vatType": "SALES",
  "vatStatus": 1,
  "invoiceId": 8485084,
  "invoiceNumber": 3,
  "version": "2020-10-10T12:00:00",
  "transactions": [
    {
      "id": 101264266,
      "transactionId": 101264266,
      "transactionType": "REVERSING_ENTRY",
      "account": "1700",
      "accountingValue": 8.68,
      "vatPercent": 0.0000
    },
    {
      "id": 101264265,
      "transactionId": 101264265,
      "transactionType": "ENTRY",
      "account": "3000",
      "accountingValue": -7.00,
      "vatPercent": 24.0000,
      "dimensionItemValues": [
        {
          "dimensionId": 88593,
          "itemId" : 159637,
          "value" : -7
        }
      ]
    },
    {
      "id": 101264267,
      "transactionId": 101264267,
      "transactionType": "RECONCILIATION_ENTRY",
      "account": "8890",
      "accountingValue": 0.00,
      "vatPercent": 0.0000
    }
  ]
}

A succesful request will return the updated resource with new version timestamp.

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 01 Oct 2020 12:00:00 GMT
Content-Type: application/json
Content-Length: 933
Connection: keep-alive
Access-Control-Allow-Origin: *
Access-Control-Expose-Headers: Access-Control-Allow-Origin,Access-Control-Allow-Credentials

{
  "id": 14068672,
  "type": "SALES_INVOICE",
  "status": "UNFINISHED",
  "name": "Buyer name",
  "receiptDate": "2020-10-01",
  "vatType": "SALES",
  "vatStatus": 1,
  "invoiceId": 8485084,
  "invoiceNumber": 3,
  "receiptValidity": "EMPTY",
  "version": "2020-10-10T12:30:00",
  "depreciation": "EMPTY",
  "transactions": [
    {
      "id": 101264266,
      "transactionId": 101264266,
      "transactionType": "REVERSING_ENTRY",
      "account": "1700",
      "accountingValue": 8.68,
      "vatPercent": 0.0000
    },
    {
      "id": 101264265,
      "transactionId": 101264265,
      "transactionType": "ENTRY",
      "account": "3000",
      "accountingValue": -7.00,
      "vatPercent": 24.0000,
      "dimensionItemValues": [
        {
          "dimensionId": 88593,
          "itemId": 159637,
          "value": -7.0000
        }
      ]
    },
    {
      "id": 101264267,
      "transactionId": 101264267,
      "transactionType": "RECONCILIATION_ENTRY",
      "account": "8890",
      "accountingValue": 0.00,
      "vatPercent": 0.0000
    }
  ],
  "attachments": [
    {
      "id": 13522,
      "name": "example.jpg",
      "referenceType": "INVOICE",
      "referenceId": 8485084,
      "mimeType": "image/jpeg",
      "sendWithInvoice": true
    }
  ]
}

Calculating invoice sum

Procountor does not store separate "total sum" information for invoices. Always when a total sum is needed, it is calculated from invoice rows. Clients using the API must implement total sum calculation by themselves if they need the information.

Solution

The formula for calculating invoice row sums depends on the setting "unit prices include VAT". The corresponding property in ExtraInfo data model is unitPricesIncludeVat. In the formulas below, the round function rounds its argument to two decimal places.

Unit prices include VAT

The sum of an invoice row is calculated as follows:

Sum(InvoiceRow_n) = round(quantity * unitPrice * (1 - discountPercent / 100))

Unit prices do not include VAT

To calculate the sum of an invoice row:

Calculate the row sum without VAT and round the sum to two decimal places.
Calculate the amount of VAT based on the previous sum and round the amount to two decimal places.
Add the amount of VAT to the row sum without VAT.

To formulate the steps above:

Sum(InvoiceRow_noVAT_n) = round(quantity * unitPrice * (1 - discountPercent / 100))
Sum(InvoiceRow_VAT_n) = round(Sum(InvoiceRow_n_noVAT) * (vatPercent / 100))

Sum(InvoiceRow_total_n) = Sum(InvoiceRow_noVAT_n) + Sum(InvoiceRow_VAT_n)

Invoice sum

The total sum of an invoice is the sum over all (rounded) invoice row sums:

  Sum(Invoice) = Sum(InvoiceRow_total_1) + ... + Sum(InvoiceRow_total_N)

Calculating ledger receipt sum

As with invoices, Procountor does not store separate "total sum" information for ledger receipts. Always when a total sum is needed, it is calculated from receipt transaction rows. Clients using the API must implement total sum calculation by themselves if they need the information.

Solution

The sum of a ledger receipt transaction is calculated as follows:

Sum(Transaction_n) = round(accountingValue * (1 + vatPercent / 100))

Above, the round function rounds the sum to two decimal places. The total sum of the ledger receipt is the sum over all rounded transaction sums:

Sum(Receipt) = Sum(Transaction_1) + ... + Sum(Transaction_N)

In most cases, this sum should equal zero. Otherwise, the receipt does not reconcile and possibly requires a reconciliation row.

Receipt accounting value

The accounting value of a ledger receipt is defined as the sum of all positive rounded transaction sums.