API2
- Olle Aid Kvarnström (Unlicensed)
- Karl Lundkvist
- Oskar Bilén
Introduction
This introduction is written based on experience drawn from a lot of custom integrations. It is aimed at consultants implementing an integration for a BRP-customer.
An API-integration with BRP is a very complex task, not in a technical sense but the domain knowledge required for a successful end result is substantial. As a consultant you will have to spend a lot of time in cooperation with your client's BRP-users to gain a full understanding of the system and how it is used.
BRP is a standard system and very generic. It can be configured in a multitude of ways. BRP Support does not have knowledge of how a specific customer uses BRP.
Every integration project must have these three roles defined before even starting:
* A project leader representing the BRP-customer
* A project leader representing the consultant
* A project leader from BRP
BRP will debit the hours spent on the project.
There is a monthly fee for access to the API.
Support tickets
Be as specific as you can possibly be, for example:
Present yourself properly, who are you working for and who is our joint customer.
Show us the full request including URL and API-key.
Tell us what your result was and what result you were expecting.
Let us know if you got an error message and what it said.
Let us know how severe your problem is for your production.
Limited liability
This document is a work in progress and must be interpreted as such. Corrections and modifications can and will occur and BRP Systems shall not be held responsible for subsequent modifications required on part of end users.
Scope of purpose
The purpose of this API is not to offer a means to replacing the BRP java client but more to work as a complement for web and mobile based services. While the API is limited in its features in comparison to the main client, BRP is continuously developing and improving it. Suggestions are welcome.
Authentication
Basic HTTP-authentication is used. The username can be an e-mail adress, card number or customer number.
Error management
Any and all error messages will be displayed in English.
Example
<errors>
<error>
<code>1001</code>
<message>Invalid parameter, firstname</message>
<debuginfo>field=firstname</debuginfo>
</error>
</errors>
Format
Data type | Format | Example | Comments |
|---|---|---|---|
Date | yyyy-MM-DD | 2012-12-24 | GMT+1 (Stockholm) including adjustments required for summer and winter time |
Time | HH:mm | 14:54 | GMT+1 (Stockholm) including adjustments required for summer and winter time |
Timestamp | nnnnnnnnnnnnn | 1298023236 | Unix Epoch, Number of seconds since 1/1 1970, 00:00:00 GMT |
Boolean | true/false | true | |
ID-list | n,n,n.... | 1,2,45 | List containing object id |
String | Spinningsal | Text string UTF-8 in desired length. Characters are escaped in accordance with either XML or JSON standards. | |
Number | nnnnnnnnn | 124234 | Integers are always specified without thousands separators or 10 powers |
Decimal | nnnn.nnn | 34.45 | There are no limits for the number of decimals that may be used. No thousands separators or 10 powers. If the number of decimals is 0 no decimal divider will be sent. |
ID | nnnn | 43 | Integer that is an object ID |
Product type | groupActivity/ subscription/ package/ article/ service/ event/ stockProduct/ valueCard/ entry | groupActivity | Text strings that represent product groups |
Sex | male/female | female | Text strings denoting sex |
Valid e-mail address | |||
Personal ID number | 850101-123X | Valid Swedish, Norwegian or Finnish personal ID number, depending on the facility. For persons connected to a Swedish facility a Swedish personal ID number must be used. | |
Telephone number | 013-342 00 20 | Valid telephone number |
Miscellaneous
When currency is used it is specified in Swedish öre or Euro cents. For example: SEK 34,99 is formatted as 3499.
Encoding
When REST-objects are created or modified and HTML encoding is used the sent text must NOT be sent in the request string, it must be sent in the body. This is to avoid an improper display of characters when a LATIN-1 interpretation of a UTF-8 string will result in Göteborg instead of Göteborg.
Requests
Parameters
Parameter names must be formatted in lowercase.
Other parameters are to be interpreted as filtering parameters when list-calls are used.
When parameters are sent they must be properly formatted or an error will be returned.
There is support for sending parameters in the request string or body with Content-Type application/ x-www-form-urlencoded, application/json eller application/xml.
NOTE: Send parameters in either the request string OR body, not both, when using PUT. Using both will result in the parameters in the body being ignored.
https://api.brpsystems.se/brpgog/api/ver2/bazAPI key
An API key is required for all requests.
Example:
APIURL/restobjects.xml?apikey=3389367678838
The API key is available in three different levels:
Level 1: Required for GET requests where contents are only displayed, not modified. This is commonly used to display items such as today's schedule where no interaction is required.
Level 2: Required for PUT, DELETE and POST requests. This is used when objects need to be created, modified or even deleted. Amoung other uses this is commonly used when a user's login credentials are stored in a mobile phone.
Level 3: This level used for system to system requests where the user's credentials are not known. The IP number of the requesting device must be pre-registered in order for this to work.
Response
Response tags that represent valid objects always contain the objects unique ID, always an integer.
All tags and attribute names are lowercase.
The response will always be encoded in the coding the request was made in. If the request did not specify an encoding the default encoding of UTF-8 will be used for the response. From 2023-01-01 the response will always be encoded as UTF-8.
Responses can be in either XML or JSON and are specified in the URL.
Definitions
Word | Definition | Comments |
|---|---|---|
activitybooking | Class booking | Class booking and waiting list |
purchase | Purchase | Purchase of services, events, goods, subscriptions, value cards and deals |
person | User/booker | |
resource | Resource | Rooms, instructors, staff, equipment etc. |
activity | Group activity/class | |
event | Event | Events such as speaches, courses |
order | Order | Completed order, either paid or confirmed |
bokning | Booking | Based on type of product: service, goods, subscription, valuecard and deal |
receipt | Receipt | |
item | Order row or receipt row | |
timeslotsuggestions | Suggested time for service booking |