User Manual: An api roadmap to europisti’s tools

If you find errors or omissions in this document, please don’t hesitate to submit an issue or open a pull request with a fix. We also encourage you to ask questions and discuss any aspects of the project on the mailing list or in the chat room. New contributors are always welcome!

Release notes

14/12/2021, v1.0, initial release

1. Introduction

The Big Picture

The api gateway is a place where European Reliance’s API’s of web services as APIs are exposed together with a portal help site for developers.

What are the web services APIs?

Behind the gateway, exposed, are our enterprise insurance services, which can be used by external developers, for applications that produce and consume insurance data, consumed by external parties.

Namely, it is, at the moment:

mtr-api: Service for vehicle insurance application and policy processing, pricing, quoting plus more.
fire-api: Service for fire insurance application and policy processing, pricing, quoting plus more.
parameters-api: Service for listing common parameters among many services

2. API gateway

In front of all the services there is a common layer called gateway. It is enforcing constraints common to all services like security, accounting and rate limiting.

Gateway is responsible for:

The first level of authentication and authorization of every call to the internal services
Counting the invocations and rate limiting them.

It is essentially the gateway guard that every call must show its credentials in order to pass.

Each API call passes from two levels of authentication and authorization.

2.1. Authentication and authorization

Levels of authentication and authorization

First level: each call is being checked to see two things. if it contains an API key that is authorized to access the specified API resource and if it obeys some specified rate limiting access rules. If it doesn’t then a specific gateway error response is returned (see General Web Service Errors and Web Service Rate Limits).
Second level: Depending on the service, each call is checked if it contains an Authorization header with a valid Bearer token.

An authorization token is fetched first from a specific service endpoint.

Steps

If a company user wants to use an externally provided program (your program) he must first authorize it to impersonate him by following a specific procedure through our company’s portal.

Within that procedure the user publishes a user-key, a 40 character key, that ties his identity with the identity of your program. This bond can be enabled, disabled, deleted, and recreated by the user whenever he wants.

The user is instructed to deliver this user-key to your program in order for you to use it for the purpose of obtaining an authorization token from the API.

This authorization token together with your api-key must be supplied as header parameters with any API call.

2.1.1. First check

At first, you must obtain an API key that uniquely identifies you, by following the procedure of signing up. After approval you will be given access to certain provided APIs.

2.1.2. Second check

The second level of authorization is the API specific authorization. Each call is checked to see if it contains an authorization header. If not then a 401 Unauthorized error response is returned.

The authorization header is an “Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxx” where the xxxx part is the token and is obtained by accessing a specific “tokens” address (see later). Steps

Please take care of your api-key, the client user-key and the resulting authorization tokens are to be stored safely and never be shared with third parties.

Use always secure communication protocols

Our services are served under HTTPS only. If you believe that your api-key or any other key or token got leaked to the outside world contact us immediately. We will disable them and supply you with new one.

If we don’t disable them, they may be used in an illegal way by a third party without us having a way to differentiate a valid usage from an invalid one. If you want your api-key to be tied permanently with your IP for added security, contact us.

2.2. API Key Usage

How to use your API key after signing up.

After signing up, you’ll be given your own, unique API key which is a 40 character string. The key:

Uniquely identifies you.
Gives you access to europisti.gr’s web services.
Should be kept private and should not be shared.

The API may be used several ways. In order of precedence:

HTTP Header, the preferred way

Pass the API key into the X-api-key header:

curl -H 'X-api-key: DEMO_KEY' "https://gateway.europisti.gr/dev/fire-api/parameters/kindsOfRisks/"

GET Request Query Param

To use your key, simply pass the key as a URL query parameter when making Web service requests. For example:

curl https://gateway.europisti.gr/dev/fire-api/parameters/kindsOfRisks/?api_key=YOUR_KEY"

Regardless of the HTTP method being called, the API key can always be passed as a GET parameter in the URL query. So even if you are POSTing or PUTing to a specific service, the api_key query parameter can be supplied in the URL query parameters.

Alternative Method

Depending on your usage, it can sometimes be easier to pass the API key along as HTTP Basic authentication. If you want to use this method, pass your API key in as the username, while leaving the password blank. For example:

curl "http://YOUR_KEY_HERE@gateway.europisti.gr/dev/fire-api/parameters/kindsOfRisks/"

2.3. Web Service Rate Limits

Daily and hourly rate limits on accessing europisti.gr’s web services.

Rate Limits

There is a limit on the number of europisti.gr web service requests you can make using your API key. Rate limits may vary by service, but the defaults are:

Hourly Limit: 1,000 requests per hour

For each API key, these limits are applied across all europisti.gr web services requests. Exceeding these limits will lead to your API key being temporarily blocked from making further requests. Depending on the limit exceeded, the block will be lifted automatically by waiting until the next hour or calendar day.

2.3.1. How Do I See My Current Usage?

Your can check your current rate limit and usage details by inspecting the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers that are returned on every API response. For example, if an API has the default hourly limit of 1,000 request, after making 2 requests, you will receive these HTTP headers in the response of the second request:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

2.3.2. Understanding Rate Limit Time Periods

Hourly Limit

The hourly counters for your API key reset on a rolling basis. Example:

If you made 500 requests at 10:15AM and 500 requests at 10:25AM, your API key would become temporarily blocked.
This temporary block of your API key would cease at 11:15AM, at which point you could make 500 requests.
At 11:25AM, you could then make another 500 requests.

2.3.3. Rate Limit Error Response

If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).

2.3.4. Need Higher Limits?

If you’re building an application that needs higher rate limits, we’d be happy to work with you. Contact us for more details.

2.3.5. Errors at gateway’s level

Certain, general errors will be returned in a standardized way from all web services. Additional, service-specific error messages may also be returned (see individual service documentation for those details). The following list describes the general errors any application may return:

Error Codes
Error Code	HTTP Status Code	Description
API_KEY_MISSING	403	An API key was not supplied. Read API key usage for details on how to pass your API key to the API.
API_KEY_INVALID	403	An invalid API key was supplied. Double check that the API key being passed in is valid, or sign up for an API key.
API_KEY_DISABLED	403	The API key supplied has been disabled by an administrator. Please contact us for assistance.
API_KEY_UNAUTHORIZED	403	The API key supplied is not authorized to access the given service. Please contact us for assistance.
API_KEY_UNVERIFIED	403	The API key supplied has not been verified yet. Please check your e-mail to verify the API key. Please contact us for assistance if needed.
HTTPS_REQUIRED	400	Requests to this API must be made over HTTPS. Ensure that the URL being used is over HTTPS.
OVER_RATE_LIMIT	429	The API key has exceeded the rate limits. Read rate limits for more details or contact us for assistance.
NOT_FOUND	404	An API could not be found at the given URL. Check your URL.

Error Response Body

The error response body will contain an error code value from the table above and a brief description of the error. The descriptions are subject to change, so it’s suggested that any error handling must use the HTTP status code or the error code value for error handling (and not the content of the message description).

Error Message Response Formats

Depending on the detected format of the request, the error message response may be returned in JSON, XML, CSV, or HTML. Requests of an unknown format will return errors in JSON format.

JSON Example

{
 "error": {
   "code": "API_KEY_MISSING",
   "message": "No api_key was supplied. Get one at https://gateway.europisti.gr"
  }
}

XML Example

<response>
  <error>
    <code>API_KEY_MISSING</code>
    <message>No api_key was supplied. Get one at https://gateway.europisti.gr</message>
  </error>
</response>

CSV Example

Error Code,Error Message
API_KEY_MISSING,No api_key was supplied. Get one at https://gateway.europisti.gr

HTML Example

<html>
  <body>
    <h1>API_KEY_MISSING</h1>
    <p>No api_key was supplied. Get one at https://gateway.europisti.gr</p>
  </body>
</html>

2.4. Dev vs Prod

In order to access a developer’s sandbox for developing and testing reasons, it is enough just to add the word dev in the path after the server name and before the actual api’s path, for example:

Production URI        https://gateway.europisti.gr/fire-api
Sandbox URI           https://gateway.europisti.gr/dev/fire-api

Of course it is necessary for your API key to be accepted and given access to both environments by the authorization procedures that are established with your registration.

By having a valid and authorized X-api-key, any call can pass gateway’s checks and access any internal APIs that was given access to it. One such API is the fire-api.

3. FIRE-API intro

General information

The fire-api is accessible via https://gateway.europisti.gr/dev/fire-api. In order to use this API, you must pass:

Your API key via one of the supported methods, preferably as header parameter
AND an authorization token via the Authorization header.

To make requests to the API two headers are required:

X-Api-Key:     YOUR_API_KEY_HERE
Authorization: Bearer CLIENT_BEARER_TOKEN_HERE

Without these two headers all calls to fire-api will be rejected with the response 401-Unauthorized

3.1. Authorization

3.1.1. Getting authorization tokens

An Authorization client bearer token is thus required, and the way to get it is via a POST request to https://gateway.europisti.gr/dev/auth-api/resources/tokens which requires only the api-key header as prerequisite and a JSON encoded payload of the user-key.

As an example from command line use:

curl -i \
-H 'Content-type: application/json' \
-H 'X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-X POST https://gateway.europisti.gr/dev/auth-api/resources/tokens \
-d '{"user-key": "vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv"}'

With a correct and existing api-key and user-key which have been connected by the client internally, the response will be a 201 Created, and as the body the token and an Authorization header containing a token of type Bearer will be returned.

This token-in-body or token-in-header must be saved on the client side and must be used in all subsequent calls to every other fire-api. The only exception to this rule, of course, is the current https://gateway.europisti.gr/dev/auth-api/resources/tokens for creating new tokens.

A convenience header X-Token-Expires-In: xxxx seconds is returned by default. It is the time remaining in seconds for which the token will be valid. With this header it is possible to calculate beforehand when a token renewal call will be needed.

By default the token is valid for 30 minutes after which the server will reject subsequent calls with the response 401 Unauthorized and an extra error header X-Error: Token Expired

If the client receives this error he can request a new token which will be valid for 30 more minutes.

No extra header

If the client gets response 401 Unauthorized without the extra header, then that means the authentication failed on the server side due to either wrong keys or because the client of the user-key refuses access to the X-Api-Key holder. In such case it is advised to first get in contact with your client (of user-key) to remedy the situation.

User impersonating another user

Sometimes a user needs to impersonate another user. For example a secretary might need access to various services in the name of an agent that gave her such rights. If the user has the right to use another person’s code (as dictated by company’s internal rules), you can grand them permission by appending a field named “agent-code” with the impersonated agent’s code as value. As an example:

curl -i \
-H 'Content-type: application/json' \
-H 'X-Api-Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-X POST "https://gateway.europisti.gr/dev/auth-api/resources/tokens" \
-d '{"user-key": "vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv", “agent-code”: “SSSS”}'

string ISO date

When the specification of a date named field is “string ISO date”, it is expected to be supplied with a date in ISO 8601 format like “2018-10-28” or a datetime like “2018-10-28T13:55:00”.

The date fields are expected to be in the Greek time zone and the conversions are handled by the api. When a datetime field is returned and it doesn’t end with a 'Z' (which denotes a UTC date) then it is supposed to be a Greek LocalDate value.

3.2. Errors

When the fire-api encounters an error condition outside the normal flow, it tries to return that error condition with a specific header named X-Error. So when it encounters incomplete or bad requests, incoming data validation errors or specific internal error conditions, it sets the error header informing the client application with a more specific message.

You will use this information for correcting the condition and maybe retrying the operation. For example when the authentication token expires, the client application receives a 401 Unauthorized status with the specific header X-Error: Token Expired signalling that a new token must be obtained first from the “tokens” resource and then the operation can be retried.

3.2.1. Other headers

When an operation returns with a failure status, it is possible that a header named X-Error is returned and usually an error entity with error details for both.

For operations like POSTing new entities and for the success status 201 Created, a Location header is set, according to standards with the uri of the new entity.

Some operations return extra information or actions in the Link headers. For example when issuing an application a link for the notification document is included. The operations that return this kind of information are documented.

For reference purposes, click this link to find out more about known response status codes.

3.3. CORS

The fire-api supports CORS and set required headers.

4. Applications

Overview

The following API endpoints can be used to programmatically create, retrieve and delete applications.

Available actions are:

Search applications

Returns a list of applications for the search criteria. Can be paged if start and limit request parameters is used.

Retrieve an application

Retrieve an application.

Insert new application

Create a new application.

Update an application

Change an existing application for new policy, as long as it is in initial status.

Cancel an application

Cancel an application. Can be used to cancel a new application for policy or a renewal application in prepay status.

Insert objects insured

Insert a new object.

Update an object insured

Change an existing object insured.

Delete an object insured

Delete an object insured.

Insert claims history

Insert a new claim.

Update claims history

Change an existing claim info.

Delete claims history

Delete a claim history.

Insert co-owners

Insert co-owners.

Delete co-owners

Delete co-owners.

Insert mortgages loans

Insert a mortgage loan.

Update mortgages loans

Change an existing mortgage loan.

Delete mortgages loans

Delete a mortgage loan.

Application calculation

Perform the calculations required for the specific application.

Application edit

Make changes in the current application.

Request for application approval

Set an application that needs approval from an underwriter, in that status.

Send for acceptance

Trigger the application acceptance process.

Move an application to PREPAY status

A new application without errors must be set in PREPAY status in order to trigger the notification procedures. In that status, the user can create a payment notification document or even proceed with issuing the application to policy by charging his/her account if that is possible or even notify the client with a URI for online payment.

Guides

Fields with names ending in Code (like bundleCode) expect to receive the parametric code. The description fields are not required when inserting or updating an application, only the code fields are. Values for the code fields are supposed to be found from the appropriate parameter calls on parameters resource.

The api informs you for any payload validation errors or other type of errors with an error status and an entity.

A bundleCode is mandatory for an application. Any extra covers must be supplied in the form of space or comma delimited string in the field named extra_covers.

The status of an application does not change automatically without an action. With every action of inserting or updating an application, a new status is calculated. If you wanted to recalculate an application you should, for example, first fetch the current version of the application if you do not already have it and then update it with the same information. This will force the system to recalculate it. There are many criteria that an application must meet in order to be valid and some of them can not be influenced by the end user.

Status of an application
code	description	actions
00	in entry requiring user intervention and update ("Επεξεργασία αίτησης - Προς υπολογισμό")	updates an application. Next steps are application calculation (to: 00 or 25 or 01), or cancel (to: 02)
25	in entry requiring approval ("Επεξεργασία αίτησης - Χρήζει αποστολής για έγκριση")	updates an application. Next steps are application calculation (to: 00 or 25 or 01), request approval (PUT, to: 30) or cancel (to: 02)
01	it is OK and can proceed to prepay ("Υπολογισμένη αίτηση")	can proceed to application edit (to: 00), send for acceptance (to: 39), move to prepay (to: 45)
30	is pending and managed by an underwriter, it is possible that there are messages for any pending issues ("Σε έλεγχο από κεντρικά")	no edit is permitted. Next steps are done only from the underwriter
11	in approval process ("Σε Εγκριτική Διαδικασία")	no edit is permitted. Next step is request approval (GET, to: 30)
02	cancelled application ("Άκυρη")
39	send for acceptance
45	move to prepay ("Σε προείσπραξη")	next steps are payment code, issue by charging user

4.1. Search Applications

In order to search for user’s applications a GET request must be submitted to the resource. The response is a JSON array of search result rows.

Resource URL

GET https://gateway.europisti.gr/dev/fire-api/rsc/applications

Resource Information

Response formats

JSON

Requires authentication?

Yes (user context)

Rate limited?

Yes

Parameters

Query (url parameters)
Name	Optional	Comments
type	YES	Values : APPLICATION, POLICY
active	YES	0 = Inactive, 1 = Active
application_no	YES
policy_no	YES
client_name	YES

Method	Description
…/parameters/kindsOfRisks	Risk type
…/parameters/kindsOfRisks/subkindsOfRisks	Risk category
…/parameters/groupsInsured	Type of insurance (bulding, content, both)
…/parameters/groupsCovers	Covers for the specific type
…/parameters/bundles	Specific product bundles with covers
…/parameters/bundles/extra_covers	The additional covers available
…/parameters/listBundles	Available product bundles
…/parameters/constructionOfSkeletons	Construction of Skeletons
…/parameters/constructionOfWalls	Construction of Walls
…/parameters/roofsConstruction	Roofs Construction
…/parameters/fireProtectionMeasures	Fire Protection Measures
…/parameters/theftProtectionMeasures	Theft Protection Measures
…/parameters/typeOfSafetyShutters	Type of Safety Shutters
…/parameters/typeOfLocks	Type of Locks
…/parameters/alarmConnections	Alarm Connections
…/parameters/documentCategories	A document’s category
…/parameters/acceptance_methods	Ways of acceptance

Name	Optional	Comments
group_insured	YES
prefecture_code	NO
building_year	NO
subkind_of_risk	NO
construction_of_skeleton	NO
roof_construction	NO

Name	Optional	Comments
file_name	NO	testfile.pdf
mime_type	NO	application/pdf
category_id	NO
comments	YES

category	attribute	optional	data type	label	comments
fire_application	start_date	no	string ISO date	Έναρξη ασφάλισης	2021-11-01T00:00:00
fire_application	pay_frequency_in_months	no	number	Συχνότητα πληρωμής	Values : 3,6,12
fire_application	contact_way_code	no	string	Τρόπος διεκπεραίωσης	Contact ways
fire_application	application_acceptance_method	no	string	Τρόπος αποδοχής	Acceptance methods
fire_application	subagent_code	yes	string	Έμμεσος συνεργάτης	SubAgents
fire_application	service_code	yes	string		Only NN agent
fire_application	commission_code	yes	string		Only NN agent
client	.client	no		Λήπτης	Person
client	..consents	no		Δηλώσεις συγκατάθεσης	Consents
client	>>master_id	no	number
client	>>id	no	number
client	>>answer	no	string
insured	.insured	no		Ασφαλιζόμενος	Person
objects_insured	.objects_insured			Αντικείμενα ασφάλισης
objects_insured	kind_of_risk	no	string	Είδος κινδύνου	Kinds Of Risks
objects_insured	subkind_of_risk	no	string	Κατηγορία κινδύνου	Subkinds Of Risks
objects_insured	address	no	string	Διεύθυνση κινδύνου
objects_insured	address_number	yes	string	Αριθμός
objects_insured	city	no	string	Πόλη
objects_insured	post_code	no	string	Τ.Κ.
objects_insured	latitude	yes	string
objects_insured	longitude	yes	string
objects_insured	building_year	no	number	Έτος κατασκευής
objects_insured	building_commencement_year	yes	number	Έτος ανέγερσης οικοδομής
objects_insured	square_meters	no	number	Τετραγωνικά μέτρα
objects_insured	building_year_piping	no	number	Έτος αντικατάστασης σωληνώσεων
objects_insured	bordering	no	string	Συνορεύουσα	Values: 0=Όχι, 1=Ναι
objects_insured	is_owner_building	yes	string	Είστε ιδιοκτήτης της οικοδομής	Values: 0=Όχι, 1=Ναι
objects_insured	building_floors	no	array of numbers	Όροφοι οικοδομής	[-2,5]
objects_insured	insurance_floors	no	array of numbers	Όροφοι ασφάλισης	[4,5]
objects_insured	meters_from_river	yes	number	Πόσα μέτρα από το ακίνητο σας διέρχεται χείμαρρος ή ρέμα
objects_insured	construction_of_skeleton	no	string	Σκελετός οικοδομής	Construction of Skeletons
objects_insured	construction_of_walls	no	string	Κατασκευή τοίχων	Construction of Walls
objects_insured	roof_construction	no	string	Κατασκευή στέγης	Roofs Construction
objects_insured	type_of_locks	yes	string	Τύπος κλειδαριών	Type of Locks
fire_protections	..fire_protections	yes		Προστατευτικά μέσα πυρκαγιάς	Fire Protection Measures
fire_protections	>>id		number
fire_protections	>>has_protection		string		Values: 0=Όχι, 1=Ναι
fire_protections	>>multitude		number
fire_protections	theft_protections	yes	array of strings	Προστατευτικά μέσα κλοπής	Theft Protection Measures
fire_protections	alarm_Connections	yes	array of strings	Σύνδεση συναγερμού	Alarm Connections
fire_protections	type_of_safety_shutters	yes	array of strings	Τύπος ρολών ασφαλείας	Type of Safety Shutters
fire_protections	bundle_code	no	string	Πρόγραμμα ασφάλισης	Bundles
fire_protections	building_improvements	yes	number	Κτιριακές βελτιώσεις	Only kind_of_risk!=’04’
insured_values	..insured_values	no		Ασφαλιζόμενες αξίες
insured_values	>>group_cover		string
insured_values	>>insured_value		number
extra_covers	..extra_covers	yes		Επιπροσθετες καλύψεις	Extra covers
extra_covers	>>group_cover		string
extra_covers	>>cover		string
claims_history	..claims_history	yes		Ιστορικό Ζημιών
claims_history	>>claim_date	no	string ISO date	Ημ/νια ζημιάς
claims_history	>>claim_amount	no	number	Ποσό ζημιάς
claims_history	>>job_description	yes	string	Εργασίες αποκατάστασης
co-owners	..co-owners	yes		Συνιδιοκτήτες	Person
mortgages_loans	..mortgages_loans	yes		Ενυπόθηκα δάνεια
mortgages_loans	>>bank_id	no	string	Τράπεζα	Banks
mortgages_loans	>>amount_loan	no	number	Ποσό δανείου
discounts	..mortgages_loans	yes	array of numbers	Εκπτώσεις	Bundles

attribute	optional	data type	label	comments
person_type_code	no	string	Πρόσωπο	Person Types
last_name	no	string	Επώνυμο/Επωνυμία
first_name	*	string	Όνομα	*required only for individuals
father_name	*	string	Όνομα πατρός	*required only for individuals
birth_date	*	string ISO date	Ημ/νία γέννησης	*required only for individuals
gender_code	*	string	Φύλο	*required only for individuals, Genders
job_code	yes	string	Επάγγελμα	Jobs
address	no	string	Διεύθυνση
city	no	string	Πόλη
post_code	no	string	Τ.Κ.
phone	yes	string	Τηλέφωνο
mobile	yes	string	Κινητό
email	yes	string	email
afm	no	string	Α.Φ.Μ.
doy_code	no	string	Δ.Ο.Υ	Doy
identity_number	yes	string	Αρ. Ταυτότητας
identity_date	yes	string ISO date	Ημ/νία Έκδ. Ταυτότητας
amka	yes	string	ΑΜΚΑ
citizenship	no	string	Υπηκοότητα	Nationalities