General information

The basics of using Procountor API

Home  ⫽ General information

About Procountor API

Procountor API (application programming interface) an open interface to Finago Procountor, the friendly accounting software. With its diverse support for financial management features, the API can be used for building value-creating integrations with both commercial software and internal systems. The API was published in the early 2017 and is being extended with new endpoints.

Information: This website is intended as a technical reference for software developers building integrations with Finago Procountor API. For information about the software itself, please have a look at Finago.com.

Procountor API mainly adheres to the REST model and uses JSON as data presentation format. At least two latest versions are always supported. Integration partners may keep themselves up to date on changes by following the news page or subscribing to Procountor Developers mailing list.

Accessing the API

Accessing Procountor API requires obtaining an authorization grant for the external application used and authenticating the user. These procedures follow an OAuth2 process explained on a separate page:

See instructions

When developing an integration with Procountor API, it is necessary to consider the most suitable approach for implementing authorization and authentication for end users. After familiarising with authorization for testing purposes, proceed with reading the following guide:

Read how to implement authorization

Using endpoints with 2-step verification

API v8 introduced the new payment endpoints and together with them, a new 2-step verification model. At the current stage only Finago Key(previously known as Procountor Key) can be used to verify, but the plan is to enable one time password usage later as well.

The core concept is that performing critical operation such as payment will require verification from user that comes from outside the client-API requests.

Overall flow is as follows: 1. Client sends request to API to perform an action 2. API validates the request and if everything is ok returns http code 202 and a transaction id in the body 3. User gets automatically prompted in the Finago Key app if they want to confirm this action 4. Client calls confirmation endpoint using the previously returned transaction id, which will check the status of the user confirmation for that action and re-validate and complete the action if user has confirmed it.

The confirmation request to user will expire in 5 minutes. The confirmation endpoint in the API will provide information about the status of the transaction or complete the action if user has confirmed it. See the API reference for full documentation on different http codes and messages returned in different situations.

Currently the test server does not support Finago Key usage, so THE TEST SERVER WILL ALWAYS MOCK USER CONFIRMATION AS OK

Example flow when making a new payment

Example user flow: 1. Fill payment data in client application and perform payment action 2. Verify with Finago Key

Example client flow: 1. Send payment data to POST /payments to receive transaction id 2. Poll confirmation endpoint with the transaction id (will return http code 202 as long as pending, after user has confirmed 200 and response json, see detailed http codes from API reference) 2. As an alternative to polling, the client can implement a button for user, which user presses to indicate that they have confirmed the action.

API servers

The development process for integrations with Procountor API starts by utilising a dedicated server for testing purposes. It is intended to contain the same software platform as the production server. Accordingly, when launching the integration in production, the only necessary actions are changing the server address and access credentials in the external application.

On both testing and production servers, there are two different URLs available: one proxy URL that always points to the latest API version, and one for accessing a specified version. Ensure you are aware of possible compatibility issues when using the proxy URL. Refer to the news page for information about supported versions and changes.

Testing server

Resource URL
Latest API version https://api-test.procountor.com/api
Specified API version (X) https://api-test.procountor.com/procountor.api.vX/api
Procountor UI https://api-test.procountor.com/procountor/

UI for testing purposes

All API testing environments can be accessed through the user interface as well. Feel free to create new user accounts and environments. For more infomation about creating new user accounts, have a look at Procountor user manual.

Information: Use the same credentials for accessing both API and the UI. User accounts in production are not available on the testing server.

Note that two-factor authentication is not used on the testing server. After receiving the credentials to log in with, select one-time password list as login method on the first login. You will no longer be asked for an one-time password.

Production server

Resource URL
Latest API version https://api.procountor.com/api
Specified API version (X) https://api.procountor.com/procountor.api.vX/api
Procountor UI https://secure.procountor.com/procountor/

Making requests

Headers

All JSON-based API requests must include the following header information unless otherwise stated:

Content-Type: application/json
Authorization: Bearer <access token>

Example: If the access token is b4a24f..., supply a header Authorization: Bearer b4a24f....

File transfers, such as sending attachments, use multipart/form-data as content type for the request as a whole.

Formats and encoding

Value Format Example
Date ISO 8601 2017-01-30
Datetime ISO 8601 2017-01-30T15:20:00
Currency code ISO 4217 SEK
Decimal value Separated by dot. Scale depends on the field. 19.2022
Any Encoding: UTF-8
Character set: Windows-1252
Not allowed: Ŕ, ೠ
Values as URL or POST parameters URL encoded abc+äö -> abc%2B%C3%A4%C3%B6

Request limits

Use of Procountor API is limited to maximum 20 requests per second per clientId on both test and production servers. Exceeding the limit may result in suspending the service for the API client in question. The limit is subject to change.

Optional fields

As a principle, the API omits fields for which there is no data and correspondignly returns no empty arrays. Generally, fields marked as optional are subject to this kind of logic, and possible exceptions are indicated in the API reference. Values for optional fields are validated if and only if they are provided in a request.

For instance, if a product on an invoice does not have a corresponding entry in the product register, the optional productId field must not be present in the invoice POST request. Then, the server's response does not include that field either. If provided in the original request, the value of the productId field is validated and must match an item in the product register.

Read only fields

Fields marked as read only in the complete reference contain values automatically generated or assigned by Procountor. While they are present in the server's responses, they cannot be defined by the user in POST or PUT requests.

Removing values

Some endpoints support updating resources with a PUT operation. In those cases, values for optional fields can be removed by excluding the entire field from the updated resource model. Accordingly, objects in arrays can be removed by excluding them from the updated model.

Paging

Most GET endpoints returning aggregated data feature a paging mechanism. Practically, it means all results are not returned at once if their amount exceeds a preset limit. Moving forward within the search results is done with URL parameter previousId. It indicates the ID of the last search result in the given order that is to precede the ID of the first result in the new result set.

Example: If the first result set contains IDs 1 to 50, and you would like to get a second result set with IDs from 51 onwards, the second result set would be achieved by using previousId=50.

One-time passwords

Some endpoints require users to supply their one-time password (OTP) with the request. An OTP can be requested from a dedicated endpoint as stated in the API reference. The OTP will be sent by SMS to the user's pre-set phone number. Endpoints requiring the OTP can be used when requests are made according to user's interactions on the UI of the integrating system, and the user has been authenticated with personal Procountor credentials.

Changing password

User's password can be changed in https://secure.procountor.com/procountor/authorization with following parameters added:

  • api_login (mandatory)

    • Specifies the address where user is redirected to after the password has been changed.
  • previous_url (optional)

    • Should be set to the address from where the user came to the change password page.
    • Is used to determine where user is forwarded to when clicking on the Back button on the change password page.
    • If parameter is missing then no Back button will be displayed on the change password page.

Example: When adding both parameters then the url for changing the password would look like this: https://secure.procountor.com/procountor/authorization?api_login=<api_login>&previous_url=<previous_url>

Changing the password follows these steps when the required api_login parameter is included:

  1. Navigate to change password page as explained above.

    • User fills information about username, current password and new password.
    • It is checked that all the information is filled correctly before the Change password button is enabled.
    • If previous_url parameter was given a Back button is displayed which takes the user to the address specified in the previous_url parameter.
  2. User receives an SMS containing a verification code and is forwarded to the confirm changing password page.

    • User enters the verification code and clicks Confirm. If verification code is correct password is changed.
  3. User is forwarded to password successfully changed page.

    • User is informed that the password has been successfully changed.
    • User can click on Back to login button which forwards the user to the address specified in the api_login parameter.

In case the api_login parameter is missing:

  • An error page informing the user that the api_login parameter wasn't found is displayed.

    • If previous_url parameter was given a Back button is displayed which when clicked forwards the user to the address specified in the previous_url parameter.

Miscellaneous

Uniqueness of IDs

Most resources in the API have a unique identifier (ID). Examples of those IDs are Invoice.id, LedgerReceipt.receiptId and Product.id. The identifiers are unique within a given Procountor environment but not globally. In other words, two Procountor environments may have invoices, ledger receipts, products and other resources with identical identifiers. A unique identifier for resources consists of the combination of a resource ID and the corresponding company ID. To fetch the current company ID, use the GET /users endpoint.

Procountor user manual

Procountor user manual answers several questions regarding general usage of Procountor. The manual is available in English, Finnish, Swedish, Norwegian and Danish on Procountor support site. If the API reference does not provide a satisfying amount of information for your problem, the user manual is worth checking.

See user manual

Differences between countries

The API is equal in each country: Denmark, Finland, Norway and Sweden. However, due to legislation and product feature differences, validations for some of the API fields are country-dependent. These differences are documented in the complete API reference. When developing an integration intended to be used in multiple countries, please request testing environments for respective countries.

Pricing

Actions made through the API respect the standard limits and pricing of the Procountor environment in question. For instance, creating invoices or ledger receipts through the API count to possible quotas associated with the environment and are priced as if they were made on the UI. Additionally, usage of Procountor API may involve monthly or similar fees.

The current monthly fee for using the API, including an unlimited amount of integrations, is as follows:

  • Finnish environments: EUR 9.95 (excl. VAT)
  • Swedish, Norwegian and Danish environments: EUR 0

The price will be charged from the end-user company as an add-on service. Always confirm the latest rates for API usage on Procountor.com for Finland, Sweden, Norway and Denmark. Pricing is subject to change.

All actions made in testing environments on the api-test server as well as accessing the testing environments through the API or UI are always free of charge.