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:
- 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.
- Select or create a Procountor username (API user) to which the integration is connected.
- Ensure that the user has the privileges necessary for the integration in Procountor.
- 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. Using personal username may have unnecessarily comprehensive access rights. In addition, if a personal username is used and the user changes their password or workplace and leaves the company's Procountor environment, the integrations stop working.
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):
- Name your username by, for example, using your company name as the first name and the integrated software or API as the last name.
- Enter other mandatory data (e-mail address and phone number).
- In the Username and password section, select Deliver to user personally.
- Grant the user the necessary privileges for integration.
- In the Person info section, select Do not link user to person register.
- 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.
Processing purchase invoices
Purchase invoices can be applied to another software for allocating purchase invoices to projects.
In order for purchase invoices to be processed (Verification) via the interface, the following rights are required:
Purchases > New purchase invoice > Viewing rights
Purchases > Search invoices > All rights
Purchases > Verification > All rights
Purhcases > Supplier register > All rights
In order to assign invoices to projects, the following rights are required:
Management > Basic accounting info > All rights
If purchase invoices are accepted in another software, the following rights are also required:
Payment transactions > Approval > All rights
Paying purchase invoices
Paying purchase invoices takes place in Procountor. Purchase invoices are returned to Procountor when they have been assigned to projects. The person who is supposed to pay the purchase invoices, pays the invoices with their own personal user ID , so that the user stamps shows who paid the invoice. Payment is made with your own personal user ID by using a personal Procountor Key application. The payer needs the following payment rights:
Purchases > New purchase invoice > Viewing rights
Purchases > Search invoices > All rights
Payment transactions > Payment > All rights
Payment transactions > Mark paid elsewhere > All rights
Only allow M2M login to API
In API authentication model, it is possible to limit the API user's use of the Procountor, that the user can login to Procountor only through integration:
User rights limitations > Allow only M2M login to API > In use
We recommend using this user right limitation, when using M2M.
Note! If you use a personal user ID (which we do not recommend) when using the integration, never turn this limitation on, because otherwise you won't be able to log in to the Procountor.
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.
- 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.
- API authentication model, where the authentication takes place on the API login page of the other software using the refresh token.
If you are unsure how to implement the service and which model to select, please contact the integrator for further instructions.
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.
- Select the username to which you want to connect the integration in the User menu.
- The environment is the one where you are creating the integration API key.
- Enter the Client ID you received from the integrator in the Client ID field (usually in the format "xxxxxxxClient").
- Click the Create button.
- Click the Copy API key to clipboard button.
- Click OK.
- 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
- 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.
- After logging in, the integration automatically retrieves the API key via the interface.
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.
If you use this API-authentication method then refresh token expires 180 days and it's necessary to refresh it when time expires. Re-login is done by integrator instructions.
API Keys and active integrations
API client Keys, created either by M2M authentication or from Procountor UI via API Client Keys > "New API key. API key doesn't expire but it can be revoked via UI. If API client key has been already created for user-environment-api client, it returns the same one when user tries to create a new one for the same api client in same environment.
User can see all API keys created by other users in the environments user has main user right to user management. Main user can see active integrations from the person icon on the upper right corner > API Client sessions. You can terminate API client sessions by press Terminate session.