API Certification

Procountor API certification checkpoints

Procountor Software Partner Program provides you a path to our ecosystem and enables growing your business together with us. API certification is pre-requisite to join our Procountor Software Partner Program.

Our primary objective is to help you maximise your ability to support your customers. Even if you do not intend to be officially certified by us or join the Procountor Partner Program for Software companies, we strongly encourage you to follow the certification checkpoints listed below.

Getting started with Procountor API is quick and convenient. Procountor API Documentation is available online. Make sure you have read it. Begin by browsing through General Information to see what kind of possibilities Procountor API would provide to your use case and how you can integrate with the API. Start building your integration. Make sure you meet all the relevant requirements in the certification checkpoints. Use the Examples and Procountor API use cases to get the user experience right. Onboard testing customers. Please request access to production when you are ready.


Checkpoints required for all integrations

1. Test environment

Ensure that you have tested your integrations and it works in Public testing server (PTS) before requesting access to production. Use the form provided in Request Testing Environment to register yourself as a developer in order to get access to your private testing environment in Public testing server.

2. Integration communication

Learn how to communicate with Procountor API. To integrate with us, you will need to first familiarize yourself with request and response formats and generic conventions used when making Procountor API requests, limits, paging, errors, webhooks etc. Please follow instructions here and also check validation codes, which will help with interpreting invalid requests.

3. Authentication and authorization with Procountor API

Accessing Procountor API requires authentication and authorization. Users need to prove with an access token they have permission to use the API. Access token can be created via M2M or API authentication. It's important to handle tokens properly.

  • Procountor API offers two different OAuth 2.0 flows for authentication:

    1. The client credentials flow M2M authentication (recommended)
      M2M authentication: You want integration to connect to some service and act on behalf of it. For example, you have a reporting service and you want to read invoices from Procountor. The client credentials flow is the most commonly used authentication and recommended way to use.
    2. The authorization code flow API authentication
      API authentication: You want integration to behave on behalf of a person, with her rights and authorization. For example, you have a mobile application where user can approve only her own invoices.

  • Access token generated from either M2M or API authentication:

    • Is valid for one hour (3600 seconds) from the time of issuing.
      • Do not request a new access token for every API call. Access tokens are reusable until they expire. Reuse the token.
    • Is invalidated when user changes her password, user logs out with a POST /logout request or user is removed from the company the access token is connected to.

API endpoints that use two-factor authentication require API authentication and they can't be used with M2M authentication.

3.1. M2M authentication and API Key

  • Client credentials flow used in M2M authentication is best suited for machine-to-machine integrations like reporting or monitoring platforms and backend integrations and for example ERP solutions.
  • M2M authentication uses OAuth 2.0 Client Credentials Grant flow with API Keys used as credentials.
  • The API Keys are credentials bound to a specific user, company, and client application. An API Key is valid as long as the user is valid in the company, or until the user or a company admin revokes the API Key using Procountor UI.
  • M2M authentication is the only authentication method available for users with "API login only" user right. This limitation is enabled in Procountor UI (Management > Users and privileges > Allow only M2M login to API > In use).
  • API Key can be created in Procountor UI or via your API login page.
    • To create API key in Procountor UI, go to section Personal info and settings > API client keys > New API key.
    • To create an API Key for a user without the need to navigate through Procountor UI, as described in M2M authentication you need to have the user log in API Key login page first. Then after obtaining authorization code, swap it for an API Key.
  • API key is saved in a secure location within your application.
  • API key is then exchanged for an access token to access API endpoints.
  • To use API endpoints that require two-factor authentication, API authentication that uses Procountor Key must be used as M2M authentication doesn’t support two-factor authentication.
Things to avoid:
  • Avoid using natural persons for M2M integrations. M2M technical user never leaves the company. If you use credentials belonging to a natural person, when she leaves the company, most probably your integration will break.
  • Avoid sending sensitive information (password, API client secret, API key, refresh token, authorization code) in the request URL [OWASP guidelines].

3.2. API authentication, refresh token, two-factor authentication and Procountor Key

  • Authorization code flow used in API authentication is best suited for interactive applications like web and mobile apps. API endpoints that use two-factor authentication require API authentication as they can't be used with M2M authentication.
  • API endpoints that use two-factor authentication require Procountor Key. Procountor Key can be used only by natural person. For example, integration can modify purchase invoices in Procountor but payment must be approved by natural person.
Token handling, refresh and access tokens
  • API authentication uses access tokens and refresh tokens. As described in API Authentication, after trading authorization code for access token successfully, you will receive response with access and refresh tokens. You need to reuse the access token for your subsequent API calls as access tokens are reusable until they expire. When the access token expires, re-create a new one from the valid refresh token. Refresh token is valid for six months from the time of issuing.
  • Refresh token is invalidated when it runs past its expiration date, user changes her password in Procountor, user logs out with a POST /logout request, user is removed from the company the refresh token is connected to or there are already 100 refresh tokens for the same combination (API client, company, user).
Things to avoid:
  • As mentioned above we recommend you to use M2M authentication for reporting or monitoring platforms, backend integrations and for example ERP solutions. But if you are still using API authentication, avoid using natural person for M2M integration. Instead, create a technical API user with correct user rights.

4. API users, permissions and user rights

  • Person who has all rights to company (Management in Procountor UI) can add new users and can modify user rights in Procountor UI (Management > Users and privileges).
  • Technical API user. Interface is activated by adding the technical API user, modifying the user rights and creating the API key or token. We recommend to use API technical users as integration users. To access Procountor API resources, use dedicated users with limited permissions it demands. Make sure that your users have only the required user rights to perform the specific operation. Add new technical API user in Procountor UI (Management > Users and privileges > Create new user). Name the technical user for example by company name, software name, API.
  • Natural person as API user can be used with API Authentication and is best suited for interactive applications like web and mobile apps.
  • Technical API user’s user rights. Modify technical API user’s user rights. You can create a technical API user with minimum amount of user rights and use it in M2M authentication. This way possible security breaches have minimum impact. Pay attention also to user right limitations. M2M authentication model is good to have “allow only M2M login to API in use”, otherwise the integration interface has rights equal to the user interface. Select a user role from the Role menu or use default role Customised and set suitable rights for the user. Check Users and privileges for more information.
  • Currently logged in API user’s rights. When testing your integration, you can check user rights. GET /users/rights endpoint returns details of user rights for the currently logged in user in a certain Procountor environment.
  • Allowing the use of API clients. Before the chargeable integration can be enabled, the use of invoiceable interfaces must be allowed in Procountor’s usage settings. The setting can be found under Management > Company info > Usage settings > Integration settings > Allow the usage of invoiceable API clients.

Things to avoid:

  • When API user is a natural person, do not use limitation to user rights “allow only M2M login to API in use”, because that prevents user from using Procountor UI.

5. Product type

Procountor API is meant to be used for the Procountor Financials/Taloushallinto version.

6. Webhooks

In addition to regular REST API endpoints, Procountor API also supports webhooks for push notifications.

Instead of having to constantly poll to get information about the changes, Procountor API client can utilize webhook to receive notification on the event it is interested in, thus avoiding redundant requests.

  • Webhooks are currently supported for following endpoints that require two-factor authentication:
    • Creation of direct bank transfer payment
    • Creation / cancellation of direct salary payment
    • Creation / deletion of invoice payments
    • Update of user information

Please check Webhooks reference to learn more.

7. Performance

API rate limits

  • Please make sure that your API client is not exceeding our limits. Use of Procountor API is limited to a maximum of 60 requests per second per customer on production server. Exceeding the limit may result in suspending the service for the API client in question. This limit is subject to change.

Pagination

  • Use Pagination to get your data faster. Procountor API paginates the results to make sure responses are easier and faster to handle. Most GET endpoints which return collections feature a paging mechanism. Default page size for all collection endpoints is 50, but it can be overridden by providing size yourself - maximum up to 200.
  • There are two optional ways to control the paging.

Exponential Backoff Strategy, retry strategy

  • Adjust your client for a proper retry strategy. Dealing with Server Errors needs to be planned.
  • Procountor API may return Server Error HTTP Status Code but client can retry the same request as is.
  • Each retry should be done after a delay. An exponential backoff algorithm is one of the best ways to do such retries. It enables the API clients to retry after progressively longer wait times between next retries. For example, retry after 1 second, 2 seconds, 4 seconds, 8 seconds, 16 seconds… and so on.

Getting data

  • Procountor API lets you fetch a collection or a specific resource with GET endpoint. For example, to fetch all products, GET /products should be used. To get detailed information on one specific product, GET /products/{productId} should be used. For highly used endpoints, Procountor API also supports batch endpoints (e.g. for Products, Invoices, Ledger receipts) to fetch up to 200 specified resources with a single API call by requesting multiple comma-separated resource ids.

Searching and filtering

  • To narrow down search and limit the number of returned resources, most GET collection endpoints support query parameters. For example, you can search Business Partners with query parameter type CUSTOMER in GET /businesspartners.
  • To filter invoices by last modified date in GET /invoices, query parameters versionStartDate and versionEndDate can be used and the result ordered by orderByVersion. Please familiarise yourself with other query parameters.
  • For privacy reasons some data are supported only in HTTP headers and not in query parameter. For example, accountNumber in GET /bankstatements and GET /referencepayments.

8. Error handling and request, feedback from Procountor API to users, troubleshooting

  • We recommend notifying the end-user if the request was successfully handled or not. When you make a request to API and the server successfully receives the request, you can notify the end-user that the request was successfully handled. Based on the response’s status code and error message, you can surmise the result of the request. List of validation error codes that API endpoints may return can be found from here.
  • We want to support you technically. Make sure that your logs are helpful in troubleshooting. To help us resolve your problems quickly, when discussing with our technical support integrations@procountor.com, please include in your message: integration (= API client ID), API endpoint in question, JSON files for API request and response, server (production or testing) and API version that were used, time stamp or time frame when error occurred, session's companyId and/or userId.

9. Release notes, API version and API Reference

  • Procountor API exposes several API versions. Make sure that you are using the correct one. Please follow Procountor API Release Notes to stay up-to-date with the breaking changes and new features. We are constantly adding new functionalities to Procountor API. It may be also the reason why sometimes a new version of API is not backwards compatible for some endpoints. In such case, API clients can use one of the older versions of Procountor API.
  • However, we recommend API clients to use the latest API version to take advantage of the latest features and fixes. Breaking changes are always communicated ahead of the release in API newsletter to give clients enough time to prepare for the necessary changes. If latest version can't be used, we expect clients to use at least the supported API version.
  • Latest OpenAPI specification is available here.
  • Make sure that you read API reference pages. API Reference page presents the complete API reference documentation for the available versions of Procountor API. Procountor API enables clients to easily and quickly find the documentation of each particular API endpoint. Documentation is available here.
  • We recommend subscribing to our API mailing list to get notifications about upcoming API changes.

10. Use supported web browsers

We are providing API login UI page for authentication. Please use only supported web browsers. These browsers, which are no longer supported by Procountor UI will soon be made obsolete also in API login page: Internet Explorer (all versions), Safari 9 (or older).

11. Software’s Client name

The Client name must reflect the go-to-market name of your software or product.

12. Write guidance for customers

  • Please inform your customers how to connect the integration, including how to create API technical user, correct user rights and API Key:
    1. In Procountor UI: Management > Company info > Usage settings > Allow the usage of invoiceable API clients.
    2. Add new technical API user: Management > Users and privileges > Create new user. Name the user by company name, Software name, API
    3. Modify technical API-user’s user rights. Pay attention also to the user right limitations: Management > Users and privileges > Allow only M2M login to API, otherwise the integration interface will have the right equal to the user interface.
    4. Create API key: Personal info and settings > API client keys > New API key OR by trading authorization code created in M2M authentication for API key.
    5. In your software: Connect / Activate to Procountor

Inform customers - for example, what information can be transferred and how often, where is the master data. If customer wants to deactivate her own usage, inform customers to remove API user and revoke API key from Procountor UI.

If you want to deactivate the integration completely, please inform our integration team integrations@procountor.com.