<
* [Environments](#environments)
* [Operation tracking](#operationTracking)
* [Authentication](#authentication)
* [Common data types](#common)
* [Error handling](#error)
* [Error Codes](#errorCodes)
## What has changed and why <a name="whatAndWhy"></a>
After the release of GBox services V1 some key changes in our core systems took place:
* We moved from our classic Application based system to a Quotation based one (in motor)
* We released our central web application **OneView** with the aim of group together all our previous web applications and offer a consistent and effective solution to our brokers.
The result was an increase in the complexity of our API and the impossibility to align both our web services API and OneView web application. Updating our services would have forced us to introduce breaking changes that would cause trouble to the already in production vendor systems. That is the reason why we decided to release a new set of services instead and guarantee the backwards compatibility of the previous.
**GBox Services V1 will continue working as usual, so you are not required to switch to the new version.**
Development of new features though will mostly affect V2.
We have tried to simplify our API without creating something totally different, so you will soon notice that most services remain the same or they present minor changes.
That said, the biggest changes in V2 respect to V1 are:
* Authentication system aligned with OneView.
* No more Application references, only Quotations and Policies.
* Better test data: You can now use the same set of credentials in production and in test, so you can access the test data related to your clients.
* All motor uses are supported: You can now insure any kind of vehicle supported by OneView (Cars, trucks, motorcycles...)
MotorWs and JournalWs have been split and their methods regrouped in a more logical way:
V1 | V2
--- | ---
HeartbeatWs | HeartbeatWsV2
DataWs | DataWsV2
MotorWs | MotorWsV2, QuotationWsV2
JournalWs | PrintAndPayWsV2, PolicyWsV2
## Environments <a name="Environments"></a>
GBox services API provides 2 different environments in which to run our services:
<table>
<tr><td>**Test**</td>
<td>Uses test data. The test data mirrors production data, which means you will get similar results to the ones you would in production. There are some few exceptions in which we may alter the test data in order to ease the testing process. Test data is periodically synchronized with production, so eventually all the operations you run will be reverted and your data replaced with the latest production data.</td></tr>
<tr><td>**Production**</td>
<td>Uses production data. Use with caution.</td></tr>
</table>
## Authentication <a name="authentication"></a> ##
Gbox services API uses basic HTTP authentication. Each service request, therefore, requires sending both username and password within the HTTP header.
Heartbeat service may help you easily test your connection and correct authentication into our system.
Unauthenticated requests will result in **401 (Not Authenticated)** HTTP response, or **403 (Unauthorized)** HTTP response if the user is authenticated but has no access to a specific module.
#### Sample header
```
POST http://www.generali.gr/gbox-ws/soap/v1/motor HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: ""
Content-Length: 235
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic ZGVtbzoxMjM0
```
### Credentials
Gbox services API V2 uses the same authentication system as OneView. In OneView users are created by brokers through our registration application and automatically bound to their production codes (distribution channels).
Once a broker has an account in OneView he can easily activate the **3rd party integration** option from the settings menu as shown in the picture:
When activating this option, a username and password are being generated. These credentials are the ones required to connect to our services on behalf of that concrete broker. Every broker is only allowed to generate one set of credentials. The **3rd party integration** option can be activated/deactivated by the broker at any moment, which will grand/deny access accordingly and immediately to our services API. Notice that every time the option is being enabled, the credentials change.
**The web service credentials generated through OneView are valid for both test and production environments.**
In order to prevent accidental manipulation of production data the suffix **-test**, should be added to the password when connecting to the test environment.
As an example, the following OneView generated credentials:
Would be used in test as:
* **Username**: ws-00000425Blvdz
* **Password**: 5wPkZtXu2g-test
Whereas in production would be just:
* **Username**: ws-00000425Blvdz
* **Password**: 5wPkZtXu2g
## Operation tracking <a name="operationTracking"></a> ##
In order to track your requests and provide better technical support we would like to know which vendor company is behind each request. You can provide us this data through an extra header attribute called **vendor**.
The value of the attribute is of your choice, but it should be always the same.
A good choice in order to avoid collisions is your company's web domain.
#### Example
If your company name was *InsuranceHeroes*, and your web domain *insuranceheroes.gr* you could use the vendor property as:
```
vendor: insuranceheroes.gr
```
The whole header would look like:
```
POST http://www.generali.gr/gbox-ws/soap/v1/motor HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: text/xml;charset=UTF-8
SOAPAction: ""
vendor: insuranceheroes.gr
Content-Length: 1446
Host: localhost:8080
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)
Authorization: Basic NTAwNzI6MTIzNA==
```
## Common data types <a name="common"></a>
### Message
Represents a message from the system. Normally used as a response type.
Field | Type | Value | Description | Example
----- | ---- | ----- | ----------- | -------
code | Integer | Integer | A code representative of the error *(see error handling section below)* | 5
severity | String | error/warning/success/info | The severity of the message | error
target | String | XPath | The blamable node | /package/cover[@="800000000"]/sumInsured
body | String | Text | The body of the message | The value is missing
### Report
Gathers validation messages from our operations. Normally used as a response type.
Field | Type | Description | Example
----- | ---- | ----------- | -------
valid | Boolean | ** *true* **: If report is valid ** *false* **: If report has errors | true
messages | List [Message] | List of messages of the report | List [Message ["1", "The value is missing", "error", "distChannelCode"]]
### ParamInfo
Represents a parameter in the system. A parameter is a combination of code and description
Field | Type | Value | Description | Example
----- | ---- | ----- | ----------- | -------
code | String | Numerical | The identifier code of the parameter | 013
description | String | Text | The description of the parameter | MERCEDES
## Error handling <a name="error"></a>
GBox is a platform that offers a large variety of services, some of which contain complex inputs or are tied to dynamically changing business rules. We have tried to design an simple error handling mechanism flexible enough to cover all the scenarios and at the same time provide as much detail as possible for any client to handle them in their own way.
We consider that a client request can have only two different outputs from an error handling point of view. Either it was processed correctly, either it was not. Requests that are correctly processed return a result unless they are void. Wrongly processed requests return the standard **SOAP Fault**.
We distinguish two types of SOAP Faults:
###SystemMaintenanceException###
The system cannot process the request due to maintenance tasks. This exception should occur rarely. There is nothing that can be done while the system is under maintenance.
###ValidationException###
The system cannot process the request due to errors in the input. This errors could be caused by an incorrect use of the API but also as the result of the application of business rules.
From our point of view, we consider all the errors the same.
Errors are reported by using the **Report** object, which is merely a list of **Message** objects.
*Note that even though the report has a "valid" field, there is redundant to check it whenever it comes within a SOAP Fault*
provides information about the error type and about the offending element.
####Understanding the error
The **Message** object contains a *human readable* text describing the error (body). This text is in Greek language and can be used directly in a client application if wished.
Along with the text, it also provides a *machine readable* code in case the client application wants to use customized error messages.
The relation of message codes is as following:
####Understanding the origin of the error
In case the client application needs to track the element causing the error we provide a *target* field.
The *target* field is based on a very basic subset of the **Xpath object notation** and it only targets single elements.
Having the following input:
```
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://v1.soap.ws.api.gbox.generali.gr/">
<soapenv:Header/>
<soapenv:Body>
<v1:tariffy>
<distChannelCode>50072</distChannelCode>
<insurable>
<driverBirthdate>1983-12-24</driverBirthdate>
<driverMaritalStatusCode>1</driverMaritalStatusCode>
</insurable>
<package code="801">
<cover code="12345678">
<sumInsured></sumInsured>
</cover>
<cover code="87654321">
<param type="CGY"> 805 </param>
</cover>
</package>
</v1:tariffy>
</soapenv:Body>
</soapenv:Envelope>
```
The following targets:
Target | Description
------ | -----------
/distChannelCode | Targets the distribution channel code
/insurable/driverMaritalStatusCode | Targets the driver marital status
/package | Targets the package
/package[@code="801"] | Targets the package with code *801* (in this case the effect is the same if we do not specify the code because there is only one)
/package[@code="801"]/cover[@code="12345678"] | Targets the cover in the package *801* with code *12345678*
/package[@code="801"]/cover[@code="12345678"]/sumInsured | Targets the sum insured in the cover with code *12345678* in the package *801*
/package[@code="801"]/cover[0]/sumInsured | Targets the sum insured in the first (0) cover in the package *801*
/package/cover[@code="87654321"]/param[@type="CGY"] | Targets the param with type *CGY* in the cover with code *87654321*
###AuthorizationException###
The system doesn't allow you to complete your request because of authorization issues. This exception usually occurs if you are trying to have access to data, you are not authorized to.
## Error Codes <a name="errorCodes"></a>
Code | Description
------ | -----------
0 | Unspecified
1 | The value is missing
2 | The value shouldn't be empty
5 | The value is not existing
7 | The action is not allowed
8 | The action is not allowed in the specific location
9 | The value is in the wrong format
11 | The value is longer than it should
12 | The value is shorter than it should
13 | The values are not equal
14 | The value is lower than it should
15 | The value is lower or equal than it should
16 | The value is greater than it should
17 | The value is greater or equal than it should
18 | The value is out of range
22 | The value is not a valid afm
23 | The value is not a valid email
24 | The value is not a valid license plate
25 | The user is not authorized for this action
26 | The value is not valid
27 | The value already exists
202 | Main insured and policy holder should not be the same if policy holder is company
203 | If policy holder is a company, surname field should be empty
204 | If policy holder is a company, name1 field should be empty
206 | Invalid eurotax code
207 | Invalid market value
214 | Invalid postal code
215 | Invalid number of claims
301 | Ysae down (*Warning*)
]]>