Soliditet integrationslösningar

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:

The following codes are not errors per se, but they are also returned as SOAP faults.

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

Java

If you are writing your client code in Java, we recommend that you use the open source SOAP engine/framework called Axis to generate proxy client code for the Bisgateway web services. This recommendation is for all services except the Annual Report PDF service, which uses SOAP attachments. For this web service we have included an entire code example with client code that can be used to call this service. Please refer to http://ws.apache.org/axis/ for more information about Axis and to download the latest version.

Generating Java Client Code with Axis 

In Axis there is a tool called WSDL2Java that can be used to generate Java client stub code from a web service WSDL file. To use this tool you just run it with java from the command prompt:

java org.apache.axis.wsdl.WSDL2Java -a <WSDL URL>

Please notice that you must have java.exe in your path before running this and that all jar files used by Axis (found in the lib directory under your Axis installation directory) must be in your classpath before you can use the command above.
If successful the command above should result in a lot of new java classes being created for you. If we run this command with the NRG Consumer Search WSDL file as an input parameter then the following classes and interfaces should be generated:

• NRGConsumerSearchLocator.java

• NRGConsumerSearchSoapBindingStub.java

• BRGService.java 

• NRGConsumerSearch.java

• NRGConsumerSearchRequest.java

• Criteria.java

• NRGConsumerSearchResponse.java

• Consumer.java

• BRGFault.java

• ToCountry.java

• UserId.java

• UserPassword.java

• CustomerCode.java

• CustomerCodeOwner.java

• FromCountry.java

• IncludeEmptyFields.java

• Language.java

• TimeTaken.java

This might seem like a lot of classes, but don’t worry too much about what they do right now. Please see Using the generated code section below for an example on how to use the generated code.
WSDL2Java have a lot of optional parameters that can be used to specify which java package you want the generated code to be placed in, which directory they should be placed under etc. Please refer to the Axis user guide at http://ws.apache.org/axis/java/user-guide.html for a complete documentation on WSDL2Java.

Using the Generated Code

After you have generated client code with Axis you probably want to use the code. Here you will find a basic example code that shows how to use the Axis generated client code to perform a consumer search (please see the NRG Consumer Search section below for further information about this web service).

Client Code to Annual Report PDF

The following example code can be used when calling the Annual Report PDF service in the Bisgateway. This code uses a javax.activation.DataHandler, which holds the PDF file. It also uses SOAP with Attachments API for Java (SAAJ) and commons-httpclient 2.0 from Apache which can be downloaded at http://jakarta.apache.org/commons/httpclient/. Note: This code will be distributed as a ready-to-use component in the download section.

.Net

Here follows an example on how to build your client using the Microsoft .Net framework. The code example is given in C# but it could easily be changed into VB.Net. 

Generate a Proxy in .Net

The .Net SDK contains a tool called wsdl.exe that can be used to generate client proxy code from the WSDL-file of any web service.

To use the tool you just type:

wsdl /l:CS /protocol:SOAP <WSDL URL>

into a Visual Studio Command Prompt. If you do this on the Consumer Search service WSDL for example it should generate a source file called NRGConsumerSearch.cs.

You can also use the Add Web Reference functionality in Visual Studio which will let you add a web service reference to your project by simply pointing out a WSDL file. This action will also generate client proxy code, much like above. Please refer to the Microsoft Visual Studio documentation for more information about how to do this.

Using the Generated Code

The following example shows how to use the generated proxy code.

Decision Support Consumer

The Decision Support DSC service returns credit decision support information on a consumer.

The input criteria should identify the consumer and include information about the applied credit. Please see the WSDL file for a detailed description on what is possible to include in the input criteria.

Note that the SOAP headers toCountry, fromCountry and language are mandatory as well as login information.

WSDL Url: https://www.bisgateway.com/brg/services/NRGDecisionSupportConsumerInt?wsdl
SOAP Action: NRGDecisionSupportDSC
Example Request: cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedDSArchive/ExampleDS1

Decision Support Business

The Decision Support DSB service returns credit decision support information on a company.

The input criteria should identify the company and include information about the applied credit. Please see the WSDL file for a detailed description on what is possible to include in the input criteria.

Note that the SOAP headers toCountry, fromCountry and language are mandatory as well as login information. f(clean);

WSDL Url: https://www.bisgateway.com/brg/services/NRGDecisionSupportBusinessInt?wsdl
SOAP Action: NRGDecisionSupportDSB
Example Request: cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedDSArchive/ExampleDS2

Decision Support Archieve

This service will let you access decisions stored in your archive. The input criteria should identify the company and include information of the date of order for the decision you want to access in the archive. Please see the WSDL file for a detailed description on what is possible to include in the input criteria.

WSDL Url:https://www.bisgateway.com/brg/services/NRGDecisionArchiveReport?wsdl

When integrating Business Monitor you have a couple of choices depending on how you want to work an depending on the number of businesses that you are monitioring. You can choose to use webservices for adding or deleting objects in your monitoring portfolio and webservices for retrieving the events that have been generated. You can also choose to use ftp to send in new objects and to receive new events and basic facts om monitored objects that have generated an event. It is also possible to, to a certain extent, combine the two setups.

Business Monitor – description of Code Events 
The document describes the different monitoring event codes that can occure in the Swedish Business Monitor solutions (webservices and ftp). Link below show a list of the current event codes that is presented both in the webservice and FTP solution.

Länk till: Description of Code Events

Webservices

WSDL: 
https://www.bisgateway.com/brg/services/NRGBevakning?wsdl
https://www.bisgateway.com/brg/services/NRGBevakningMonitor?wsdl
https://www.bisgateway.com/brg/services/BusinessMonitor?wsdl

FTP

When using the FTP solution it is important that the match file sent to Soliditet is in the correct pre defined format. It is also important to know that the files sent from Soliditet will be in a pre defined format. Below you will find specifications for the layout of the match file (sent to Soliditet) and the event and basic fact file that is sent from Soliditet.

Länk till: Matchning Analys Layout för Business Monitor.pdf 
Länk till: Layouter till kund med Händelsekod KKförvaltare Rekonstruktör information.pdf

Company search

The Company Search service can be used for searching for companies. The search can be made on any combination of the following parameters:
Apart from this input the mandatory SOAP headers toCountry, fromCountry and language must be set in all requests as well as login information. The optional header includeEmptyFields can be used to specify that all fields should be returned for all companies in the response. If a particular company does not have any data in a specific field then an empty field will be returned.

The Company Search service returns zero to 50 company elements. If the search results in more than 50 hits then a “TooManyHitsException”, error code 201 will be returned. If no companies are found then a “NoHits”, error code 200, will be returned. 

WSDL Url: https://www.bisgateway.com/brg/services/NRGCompanySearch?wsdl
https://www.bisgateway.com/brg/services/NSDBCompanySearch?wsdl
SOAP Action: NRGCompanySearch
Example request:/cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Example1 

Company report rating

The Company Report Rating service returns rating information about a company. The input criteria, identifying the company, are a combination of DUNS number, organization number and VAT number.

Apart from this input the mandatory SOAP headers toCountry, fromCountry and language must be set in all requests as well as login information. The optional header includeEmptyFields can be used to specify that all fields should be returned for each main section in the response.

For detailed information about what data lies within each of these sections, please refer to the WSDL file.

WSDL url: https://www.bisgateway.com/brg/services/NRGCompanyReportRating?wsdl
SOAP Action: NRGCompanyReportRating
Example request:/cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Exampleintegration2

Company report standard

The Company Report Standard service returns general information about a company. The input criteria, identifying the company, are a combination of DUNS number, organization number and VAT number.

Apart from this input the mandatory SOAP headers toCountry, fromCountry and language must be set in all requests as well as login information. The optional header includeEmptyFields can be used to specify that all fields should be returned for each main section in the response.

For detailed information about what data lies within each of these sections, please refer to the WSDL file.

WSDL Url: https://www.bisgateway.com/brg/services/NRGCompanyReportStandardInt?wsdl 
SOAP Action: NRGCompanyReportStandard
Example request:/cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Example3

Family tree

The Family Tree service will return a family tree report for a company. Input data is the company’s organization number and login account information in the form of SOAP headers.

Please see the service’ WSDL file for detailed information about what kind of data the report includes.

WSDL Url: https://www.bisgateway.com/brg/services/NRGFamilyTree?wsdl 
SOAP Action: NRGFamilyTree
Example request: cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Example6

Group Account Financials

The Group Account Financials service should be used to retrieve group financial statements for a company.

The input criteria should identify the company which can be done by submitting the country registration number, the DUNS number or the vat number.

Note that the SOAP headers toCountry, fromCountry and language are mandatory as well as login information. ]]> f(clean);

The response includes general company data and the available group financial statements for the specific company. Note that there could be several statements in the response.
Please refer to the WSDL file for detailed information about the data that each section contains.

WSDL Url: https://www.bisgateway.com/brg/services/NRGGroupAccountFinancials?wsdl 
SOAP Action: NRGGroupAccountFinancials
Example request: cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Example7

Company Score Report Denmark

The Company Score Report Service returns score reports for a company.

The input criteria should identify the company which can be done by submitting the country registration number, the DUNS number or the vat number.

Note that the SOAP headers toCountry, fromCountry and language are mandatory as well as login information. f(clean);

The response includes general company data and the company score reports for the specific company.

WSDL Url: https://www.bisgateway.com/brg/services/NRGCompanyScoreReport?wsdl 
SOAP Action: NRGCompanyScoreReport
Example request: cms/site/soliditetse/lang/sv_SE/Integrations/IntegratedKU/Example8

Consumer search

Consumer Search lets you search for a person by entering name, social security number and address etc.

Apart from this input the SOAP headers toCountry, fromCountry and language as well as login information are mandatory in all requests. The optional header includeEmptyFields can be used to specify that all fields should be returned for all consumers in the response. If a particular consumer does not have any data in a specific field then an empty field will be returned.

If no consumers are found then a “NoHits”, error code 200, will be returned.

WSDL Url: https://www.bisgateway.com/brg/services/NRGConsumerSearch?wsdl
SOAP Action: NRGConsumerSearch
Example request: cms/site/soliditetse/lang/sv_SE/soliditet/Integrations/IntegratedKU/Example9Consumer

Consumer report standard

The Consumer Report Standard service returns credit information about a consumer. The input criterion consists for example of a social security number but the service also offers a number of other ways to identify the consumer in question. Please see the service’ WSDL file for a detailed description on the allowed input criteria.

Apart from this input the SOAP headers toCountry, fromCountry and language are mandatory as well as login information. The optional header includeEmptyFields can be used to specify that all fields should be returned for each main section in the response.

WSDL Url: https://www.bisgateway.com/brg/services/NRGConsumerReportData?wsdl
SOAP Action: NRGConsumerReportStandard
Example request: cms/site/soliditetse/lang/sv_SE/soliditet/Integrations/IntegratedKU/Example10Consumer

Can I write my client code in another language than Java and .Net?
Yes, we offer sample code in Java and .Net (C#) but you can use any language/platform to write your client. The BRG web services conform to the Web Service Interoperability Organization’s Basic Profile standard, see http://www.ws-i.org/Profiles/BasicProfile-1.0-2004-04-16.html and you can write your client in any language that supports this.

Which encoding does the BRG services use?
All SOAP communication with BRG should be encoded in UTF-8.

What are the login criteria and when do I need to add them?
There are four different login criteria in BRG, which are described in the WSDL files of all services that require them. They are always a part of the namespace http://www.dnbnordic.com/brg. The services that require login information are all except AnnualReportPDF and AnnualReportPDFList. The criteria are:

• CustomerCode
• CustomerCode
• CustomerCodeOwner
• UserId
• UserPassword

The criteria should be set as SOAP headers in the request. Please refer to the code examples sections to see how to include SOAP headers in a request.

What should I put in the SOAP headers language, toCountry and fromCountry?

These SOAP headers are mandatory for some of the services. Please refer to each service’ WSDL file to see for which of the services they are mandatory. 
Header description

What does the SOAP header includeEmptyFields do?

The includeEmptyField SOAP header is optional and can be used when calling the following services:

• ConsumerSearch

• CompanySearch

• ConsumerReportStandard

• CompanyReportStandard

• CompanyReportStandardNB8

• GroupAccountFinancials

When this header is set to “yes” all second level elements in the response will be returned, even if the particular element is empty. For example, if it’s set to yes in a request to Company Report Standard then all elements under e.g. actionsOfDistraint will be returned. To avoid ambiguity the element actionsOfDistraint itself will still be returned zero, one or more than one time.

The reason for this is so is perhaps more clear for the Company Search service where the header simply means that all fields should be returned for all companies in the response. But of course the company element itself might still be returned zero to many times, depending on how many companies matched the search.
If it’s not set then it defaults to “no”.

What does error code xxx stand for?

Please see section Error Handling for detailed information about error codes.