General information
Before you can start to make calls to the Soliditet web services, make sure you have the following information:
Soliditet live server URL
If you have the URL to the server then you can access the WSDL file to each Soliditet web service on the following URL:https://www.bisgateway.com/brg/services/<service_name>?wsdl
The URL to where the web service itself can be accessed follows the following standard:
https://www.bisgateway.com/brg/services/<service_name>/
A login account
Most of the Soliditet web services demand that you submit login information when you call the service. When requesting data for Credit Reports or Decision Support, the login account consists of four parameters:
-
Customer code
-
Customer code owner
-
User id
-
User Password
When requesting data for Nordic Business Key
The login account consists of three parameters:
-
Customer code
-
User
-
Password
SOAP
All communication with the Bisgateway takes place using the Simple Object Access Protocol (SOAP) as protocol/message format. This means that all of the Bisgateway web services should be accessed with SOAP requests via HTTP. Each service’ interface is described in detail in a Web Service Definition Language (WSDL) file.
A raw SOAP request message to the gateway might look something like this Example 1
The corresponding SOAP response message looks like this Example 2
Please see each service’ section below for a SOAP example request to each service.
All services require that you set a SOAP action as a HTTP header. This is for the Bisgateway to be able to route the message to the correct service. In you don’t specify a SOAP action then the gateway won’t be able to handle the request.
SOAP Headers
Several of the Bisgateway web services uses SOAP headers to communicate for example login account information. The SOAP headers are placed in the Header section of the message Example 3
The SOAP response message could also contain headers, for example the timeTaken header Example 4
SOAP headers which are not specified in the WSDL file, except in the schema part, are called optional headers. They can be sent in a request but they are not mandatory. If you generate proxy code from the WSDL file, specific code for these headers will not be included. If you want to send them, you have to specify them yourself. Please refer to the FAQ Java section for an example on how to do this in Java.
Error handling
The Bisgateway defines a number of standard errors that can occur during a call. These are all communicated to the caller in the form of SOAP faults. In the WSDL files for all services a standard brgFault is defined, which includes an errorCode and an exception that will hold detailed information about which error occurred. ErrorCode and exception will be sent under the detail-element in the SOAP fault. These elements are both within the namespace http://www.dnbnordic.com/brg/faults.
A SOAP fault example, as it will look when returned from the Bisgateway Example 5
The following table shows the specific errors that the Bisgateway can return:
ErrorCode | Exception | Description |
---|---|---|
100 | LoggableXmlMessageException | General error (none of the below) |
101 | AuthenticationException | Incorrect login |
102 | AuthorizationException | The service requested is not allowed for specified the user |
103 | BackendCommunicationFailureException | An error has occured in the communication with the Bisgateway and the back end system (e.g. NRG) |
104 | BackendFailureException | An error has occured in the backend system |
105 | InvalidInputException | Incorrect input, e.g a mandatory header, such as language, from Country or to Country is missing |
The following codes are not errors per se, but they are also returned as SOAP faults.
ErrorCode | Exception | Description |
---|---|---|
200 | NoHitsException | No hits in the back end database |
201 | TooManyHitsException | Too many hits in the back end database |
Namespaces
The WSDL files to all services have elementFormDefault set to qualified in the schema parts. This means that when making the SOAP request all elements in both the header and body section have to be namespace qualified. If you’re writing your SOAP request manually, don’t forget to check which namespaces the elements belong to.
Here follows an overview of all namespaces used in the Bisgateway web services. The namespaces are ordinary xml namespaces, used to distinguish the xml elements in the SOAP headers and body from one another.
Each service has two separate namespaces for request and response data:
http://www.dnbnordic.com/brg/<service_name>/request
http://www.dnbnordic.com/brg/<service_name>/response
The following namespace is general to all services. General SOAP headers belong to this namespace:
http://www.dnbnordic.com/brg
The log namespace is used for logging information:
http://www.dnbnordic.com/brg/log
The faults namespace is used for detailed fault information (see Error Handling for further details):
http://www.dnbnordic.com/brg/faults