Under this heading you’ll find the documentation of the REST APIs which is BLA API. Our hope is that using these will feel intuitive and that the classical HTTP verbs will make you reach the resources you wish in a predictable way.

The documentation is divided into a first, common part, describing how calls are made. Then there’s the Meta part which describes how the handshakes are made between you, the Integrators, and the Customers so you are able to start your relation and make the settings you want. Then the Resources offered to customer databases, and lastly the Error Messages you bump into.

 

JSON is used to communicate with our APIs, but they are XML-ready, so if that’s something you need, don’t hesitate to contact us.

 

All communication between you and the APIs is via HTTPS, and the security solution is based on OAuth2 to make sure that both your and our customers’ data is safe.

 

When naming the different endpoints of the resources we’ve strived to mirror the concepts, and the naming nomenclature introduced with SIE5. Thus, resources are called using English nouns. In the cases where the APIs provide additional properties we’ve chosen to follow suit and provide these too in English.

 

Click for more information::

 

  1. The first step to start a new integration is for you to create an Integrator’s account. This will give you the information you’ll use to identify as an Integrator in coming steps. You will also get your first Customer, a test customer you can use when developing and testing your solution against our APIs.

Calling the APIs we offer happens in two stages. First you call our validation server using the information you got in step one, validating that you’re you, and you get a Token which makes it possible for you to call the APIs during a limited time.

To validate and receive a Token to make API calls

POST https://apigateway.blinfo.se/auth/oauth/v2/token with the following contents:

Headers:

Content-Type = application/x-www-form-urlencoded

Body:

grant_type=client_credentials

scope=

client_id= [the client_id you received when you registered as an integrator]

client_secret=[ the client_secret you received when you registered as an integrator]

Response (example of a successful validation):

{
"access_token": "d142f691-d1e9-41gd-871c-267xbfd23452",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "oob"
}

The value of the parameter access_token is what you’ll use in the following calls to the resources you want to reach. More about that in step two.

Response (example of a failed validation):

{
"error": "invalid_client",
"error_description": "Failed to get client credentials"
}

 

In step two you call the APIs you’re interested in, together with the Token you received. That way we can make sure that you are you, and that you are entitled to the resource you ask for.

Using a Token to make an API call looks like this.

To call a resource, do the following:

Headers:

Authorization=Bearer d142f691-d1e9-41gd-871c-267xbfd23452 (where d142f… is the access_token you received in the previous step.)

Some resources need a User-Key in the header, identifying the client whose data you want to use (for example User-Key=ln3I9ujdcVaQw4ubgj_SYHQvML5CIljGpzi4Q2Vl).

In User-Key you put the publicKey for the specific customer you want to reach. You can read more about how to find the customers’ public keys here.

GET/POST/PUT/DELETE to https://apigateway.blinfo.se/bla-api/v1/exempel (where exempel is the resource you want to reach, for example https://apigateway.blinfo.se/bla-api/v1/sp/account which is described here).

 

Response (example of successful validation and control of available permissions:

{depending on resourcee and scope}

Response (example of unsuccessful validation – either expired or inaccurate Token):

{

”error”: ”invalid_request”,
”error_description”: ”Validation error”

}

One of the first calls you want to make is to read out what resources, and what restrictions (scopes) the APIs offer via / common-service (see below)

COMMON – SERVICE

This endpoint lists the resources and endpoints available in the system. It also reports whether the respective call (path) is subject to requirements to request the client’s permission to access the corresponding data (scopable).

Properties:

  • description: Description of the service
  • path: Path to the service
  • scopable: (true/false) Indicates whether the customer’s consent is needed to use

Adresses:

GET /sp/common/service – Provides list of linked customers

[
{
"description": "Ingen beskrivning ännu.",
"path": "account",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "article",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "common",
"scopable": false
},
{
"description": "Ingen beskrivning ännu.",
"path": "costbearer",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "costcenter",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "customerinvoice",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "journal",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "order",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "project",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "supplier",
"scopable": true
},
{
"description": "Ingen beskrivning ännu.",
"path": "supplierinvoice",
"scopable": true
}
]

/sp/common/service

ased on these, you choose which resources and scopes you are interested in as described below:

COMMON – ME & SCOPE

Properties:

  • description: Description of the integration – displayed to customers when choosing between the integrations they want to connect to
  • email: E-mail address Customers can reach the integrator via. Shown to customers
  • enabledScopes: n/a
  • live: (true/false) Indicates whether integration is in production or under development – check if integration is shown to live customers
  • name: Name of integration – shown to customers
  • phone: The phone number customers can reach the integrator via. Shown to customers (optional)
  • publicKey: Reference key used by customers to refer to the integrator
  • requestedScopes: List of scopes that the integrator wants access to from the customers (see below). Shown to customers
  • www: Reference key used by customers to refer to the integrator (optional)

Adresser:

GET /sp/common/me – provides data for the current integrator

{
"description": null,
"email": null,
"enabledScopes": [],
"live": true,
"name": "DigitMan Integration AB",
"phone": null,
"publicKey": "fmeSJ9v4QTZvB8erKNNqg4Z9fM7jkfCjxCWeoffdoqm-f",
"requestedScopes": [
{
"accessTypes": [
"CREATE",
"UPDATE",
"DELETE"
],
"serviceName": "Account"
},
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Article"
},
{
"accessTypes": [
"CREATE",
"UPDATE"
],
"serviceName": "Invoice"
}
],
"www": null
}

/sp/common/me

POST /sp/common/me – provides data for the current integrator
The following properties can be added via /sp/common/me: description, email, name, phone, and www. Other features will be ignored. Excluded properties will not be affected.

{
"description": "En bra beskrivning",
"email": "info@testbolaget.se",
"name": "Testbolaget AB",
"phone": "0123456789",
"www": "www.testbolaget.se"
}

/sp/common/me

GET /sp/common/scope – returns the integrator’s desired scope. That is, the rights they ask for customers to approve.

[
{
"accessTypes": [
"CREATE",
"UPDATE",
"DELETE"
],
"serviceName": "Account"
},
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Article"
},
{
"accessTypes": [
"CREATE",
"UPDATE"
],
"serviceName": "Invoice"
}
]

/sp/common/scope

POST /sp/common/scope – sets the integrator’s desired scope. That is, the rights they ask for customers to approve.
Available service names are “Account”, “Article”, “CostBearer”, “CostCenter”, “CustomerInvoice”, “Journal”, “Order”, “Project”, “Supplier”, “SupplyInvoice” and the possible accessTypes are “CREATE” , “READ”, “UPDATE” and “DELETE”. Note that release dates for each individual AccessType may vary per service. If the update was successfully completed, identical data is returned.

[
{
"accessTypes": [
"CREATE",
"UPDATE",
"DELETE"
],
"serviceName": "Account"
},
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Article"
},
{
"accessTypes": [
"CREATE",
"UPDATE"
],
"serviceName": "Invoice"
}
]

/sp/common/scope

In this mode, you are ready to start calling your customers. Which of these are you can list by /common/client (see point 6.) which returns a list of the customers who opted to associate with your integration. To facilitate testing and development, a test customer was created and linked to your Integrator account in step 1.

common – client

Properties:

  • email: Customer email-address
  • externalCustomerId: Customer ID from the Integrator – Writable to the Customer to demonstrate an existing customer relationship between them and the integrator
  • name: Customer name
  • publicKey: Reference key to address current customer in api call
  • scopes: Authorizations granted by the customer. Describes the availability of the client to the customer’s data

Addresses:

GET /sp/common/client – Provides list of linked customers

[
{
"email": "thomas@testbolaget.se",
"externalCustomerId": "B1-0012",
"name": "Thomas Larsson Bygg AB",
"publicKey": "ln3I9ujdcVaQw4Fbgj_SYHQ2vML5CIljGpziadQ2Vl",
"scopes": [
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Account"
},
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Article"
},
{
"accessTypes": [
"UPDATE"
],
"serviceName": "Invoice"
}
]
}
]

/sp/common/client

PUT /sp/common/client/:clientKey/:externalCustomerId – Sets the integrator’s own ID to the customer

[
{
"email": "thomas@testbolaget.se",
"externalCustomerId": "XC-0101",
"name": "Thomas Larsson Bygg AB",
"publicKey": "ln3I9ujdcVaQw4Fbgj_SYHQ2vML5CIljGpziadQ2Vl",
"scopes": [
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Account"
},
{
"accessTypes": [
"CREATE",
"READ",
"UPDATE"
],
"serviceName": "Article"
},
{
"accessTypes": [
"UPDATE"
],
"serviceName": "Invoice"
}
]
}
]

PUT /sp/common/client/ln3I9ujdcVaQw4Fbgj_SYHQ2vML5CIljGpziadQ2Vl/XC-0101

DELETE /sp/common/client/:publicKey – ends the relationship with the client with publickey. A successful call returns the integrator’s base data according to call to /sp/common/me

Satisfied?

When you feel satisfied with your integration, please contact us, and we will publish your integration for customers to choose from. These will then be able to take part in your presentation and see what resources / scopes you want to share and activate a link to your integration.

Documentation

KONTAKTA OSS

Hör gärna av dig till oss om du har några frågor. Vi återkommer till dig så snart som möjligt.

Sending

Björn Lundén Information AB | Box 84 | 820 64 Näsviken | Tel 0650-541400 | www.blinfo.se | api@blinfo.se

or

Log in with your credentials

or    

Forgot your details?

or

Create Account