<
* [Operation tracking](#operationTracking)
* [Authentication](#authentication)
* [Common data types](#common)
* [Error handling](#error)
* [Error Codes](#errorCodes)
## Environments <a name="Environments"></a>
GBox services API provides 3 different environments in which you can run the services:
<table>
<tr><td>**Development**</td>
<td>Uses mock implementations of our internal services, where the response data is meaningless (normally static or random). Response times are very fast. You can use this environment in order to get a taste of the API and start integrating the services with yours.</td></tr>
<tr><td>**Test**</td>
<td>Uses real implementations of our internal services but with test data. The test data is meaningful from a business perspective and it should be consistant with the services called, though it can be reseted at any time of the day. Response times should be equivalent to production.</td></tr>
<tr><td>**Production**</td>
<td>Uses real services with real data. Use with caution.</td></tr>
</table>
## Authentication <a name="authentication"></a> ##
Gbox public API services use basic HTTP authentication. Every service request, therefore, will require passing both username and password.
Unauthenticated requests will result in **401 (Not Authenticated)** HTTP response, or **403 (Unauthorized)** HTTP response if the user is authenticated but has no permission to execute the selected method.
#### 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
```
### Development authentication
Only valid for our demo services.
* **Username**: demo
* **Password**: 1234
### Production & Testing authentication
* **Username**: Master distribution channel of the end user (ex: 50072)
* **Password**: Will be provided
## 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 could 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*)
]]>