API integration guide 2.1

This documentation is intended to serve as a comprehensive guide for our various user groups, including resellers, suppliers, and other types of businesses. Finfo’s API provides a robust and flexible solution for managing and accessing critical data, tailored to different stakeholders within the industry.

To ensure seamless integration, all new endpoints in Finfo’s API v2.0 require that the finfoArticleId is correctly stored within the recipient’s system. This unique identifier (finfoArticleId) is used as a primary key for executing requests. It is of utmost importance that integrating systems handle this ID properly to enable efficient data retrieval and interaction with the API.

Swagger Documentation

Finfo provides tailored Swagger documentation for different user groups:

Resellers (Subscriber Documentation)
Suppliers (Supplier Documentation)
Other Businesses (Enterprise Documentation)

API Access and Authentication

To ensure secure and efficient use of our API, we utilize OAuth2 with the Password Grant for authentication. The following information is required to gain access:

Access Token URL: https://sso.logiq.no/auth/realms/finfo/protocol/openid-connect/token
Client ID: finfo-api
Client Secret: [Client secret provided separately]
User: [Username provided separately]
Password: [Password provided separately]
Grant Type: password
Scope: openid

Example of OAuth2 Authentication

Below is an example of how to request an OAuth2 token using Python:


def get_oauth2_params():
    return {
        'access_token_url': 'https://sso.logiq.no/auth/realms/finfo/protocol/openid-connect/token',
        'client_id': 'finfo-api',
        'client_secret': '[Client secret]',
        'user': '[Your username]',
        'password': '[Your password]',
        'grant_type': 'password',
        'scope': 'openid'
    }

Expected Response from the API (JSON):

{
  "access_token": "[Access token]", 
  "expires_in": 900, 
  "refresh_expires_in": 1800, 
  "refresh_token": "[Refresh token]", 
  "token_type": "Bearer",
  "id_token": "[ID token]", 
  "not-before-policy": 0, 
  "session_state": "[Session state]", 
  "scope": "openid email profile"
}

Token Management

Tokens are valid for 15 minutes.
It is prohibited to generate new tokens for every request.
For renewal, use the refresh_token with client_id, client_secret, and grant_type=refresh_token.

To ensure fair and efficient use of our API, we want to emphasize the importance of using assigned tokens responsibly. Each token issued has a lifespan of 15 minutes and is intended to be used until its validity period expires.

Abuse of the token retrieval process, such as repeated unnecessary requests for new tokens before the current token’s validity has expired, will be considered a violation of our terms of use.

We actively monitor usage to identify and prevent abuse. Please note that repeated misuse of our token management system may result in temporary or permanent suspension of your API access. This measure is taken to protect the integrity of the system and ensure a stable service for all users.

Endpoint Version Management

To ensure the stability and continuous development of our API, we use a versioning strategy that allows both backward compatibility and flexibility to introduce new features.

Versioning Model

Our API follows a two-tier versioning model in the format major.minor (e.g., v1.0):

Major Versions (v1, v2, etc.): Introduced when breaking changes are made, requiring recipients to update their integration to continue using the API.
Minor Versions (v1.1, v1.2, etc.): Used to introduce new features or data extensions that do not affect existing implementations.

We strive to keep minor updates backward-compatible, meaning recipients do not need to update their implementation unless they wish to take advantage of the new features.

Version Update Policy

Transitioning from a Minor Version (e.g., v1.2 → v1.3):
- No action is required by recipients unless they wish to utilize the new information or functionality.
- Documentation and changelogs are updated to clearly communicate additions and improvements.
Transitioning to a New Major Version (e.g., v1 → v2):
- API clients should upgrade their integration to the new version within 12 months of its release.
- During the transition period, both versions will be available to facilitate migration.

Exceptions

There may be cases where a new major version is introduced for business or operational reasons without technical breaking changes. Such changes will be clearly communicated in advance.

Common Server Responses

Understanding server responses is essential for effective troubleshooting:

200: OK - Requested data returned.
204: No Content - No data found.
403: Forbidden - Access denied.
404: Not Found - API unavailable or incorrect URL.
429: Too Many Calls - API overloaded.
500: Internal Server Error - Server error, try again later.

Operations and Maintenance

The API is monitored 24/7 for disruptions.
Any disruptions are communicated via email.
Deployments to production typically occur outside business hours but may occasionally happen during the day.
The API is regularly updated with non-breaking changes for continuous improvement and expansion.