API implementation

As a rule, the implementation of an existing API integration takes place in the other system, according to their instructions. To implement the API, go through the following steps:

1. Allow API interface use in the Procountor environment. This can be done under Management > Company info > Usage settings by selecting Allow the usage of invoiceable API clients. 
2. Select or create a Procountor username (API user) to which the integration is connected. 
3. Ensure that the user has the privileges necessary for the integration in Procountor. 
4. Implement the integration in the other system. Authentication in the interface is required before the integration can be implemented. Authentication uses your Procountor username. If the authentication method requires you to use an API key, you can either create one in Procountor or it can be created through the interface’s Login page by using the username and password you created in the previous step. 

 

1. Allowing the use of API clients

Before the 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.

 

2. API user

The interface connection is created for the following combination: integration + Procountor environment + username. The user connected to the integration must be a user in the environment where the integration is implemented, and they must have privileges in that environment to complete actions via the interface. 

If the interface connection is created for a company in the other system, we recommend creating a separate username, so-called API user, to ensure that the company’s connection is not linked to anyone’s personal username. 

Users with rights to the company’s identity management can create a new username (API user) as follows (Management > Users and privileges > Add a new user):

1. Name your username by, for example, using your company name as the first name and the integrated software or API as the last name. 
2. Enter other mandatory data (e-mail address and phone number). 
3. In the Username and password section, select Deliver to user personally. 
4. Grant the user the necessary privileges for integration.
5. In the Person info section, select Do not link user to person register. 
6. Click Ready and copy the username and password for safekeeping. Please note that you should be especially careful when storing and sending usernames and passwords.

 

3. Setting privileges

The API user should be granted privileges to the functions that are performed via the integration. For example, the API user can be given the Sales user role, if the purpose of the integration is to transfer sales invoices from the other system to Procountor. If sales transactions are retrieved from Procountor to the other system, the API user should also have viewing rights to Payment transactions. 

If the integration is used, for example, for retrieving accounting material, a suitable user role is Management/Auditor, who has viewing rights to all material but no editing rights.

We do not recommend making the API user the main user, because the main user’s privileges are too extensive.

 

4. Identification in the interface: authentication models

Authentication grants the integrator the authority to create a connection to the environment via the API interface. An existing API integration service can be implemented and authenticated in several ways, and the procedure depends on the integration provider.

• API authentication model, where the authentication takes place on the API login page of the other software using the refresh token. 
• M2M authentication model that uses API Key as the identifier. Depending on the implementation, you can create the API key in the Procountor user interface or authenticate on the API login page of the other software, after which the integrator can retrieve the API key via the interface.

If you are unsure how to implement the service and which model to select, please contact the integrator for further instructions.

 

API authentication model (refresh token)

In the API model, the user is directed from the other system to the Procountor API login page. The login is based on the so-called API username that is linked to Procountor. When you log in, you see a list of all the environments to which the username is connected. Select the Procountor environment to which you want to connect the integration. 

By logging in, you authorize the integrator to create an interface connection to the selected environment. 

 

M2M authentication model: API key

The API key used as the identifier in the M2M model is a user and environment-specific identifier key that enables the integrator to create a connection between Procountor and the other system via the API interface. The API key grants the integrator the authority to create the connection via the API interface. 

In the M2M model, the integrator can receive the API key in two ways: 

A) The user can create the API key in the Procountor user interface and deliver it forward. The other system might have, for example, a field for entering the API key. By delivering the API key, the user authorizes the integrator to create the connection. 

B) The integration can also use the API login page for the authentication, in which case the integrator is authorized to create the connection and retrieve the API key via the interface by logging in.

 

A) Creating the API key in Procountor

A user with full privileges to the company’s identity management in the environment can select the username for which the API key is created. 

To create the API key, select API Keys in the person icon on the upper right corner. Open the New API key button in the Search results window. At this point, you must have the Client ID used by the integration that you received from the integrator. The API key generated with the help of the Client ID is connected to the username in the environment, the integrated program and the Procountor environment.

1. Select the username to which you want to connect the integration in the User menu. 
2. The environment is the one where you are creating the integration API key. 
3. Enter the Client ID you received from the integrator in the Client ID field (usually in the format "xxxxxxxClient"). 
4. Click the Create button. 
5. Click the Copy API key to clipboard button. 
6. Click OK. 
7. Deliver the API key to the integrator in the agreed manner/following the integrator's instructions. 

 

B) Creating the API key on the API login page

1. The user is directed from the other system to the Procountor API login page. 
2. The login is based on the so-called API username that is linked to Procountor. 
3. When you log in, you see a list of all the environments to which the username is connected. 
4. Select the Procountor environment to which you want to connect the integration. 
5. After logging in, the integration automatically retrieves the API key via the interface.