API - reference manual

What is the "QUOTE API"?

The QUOTE API is used to get a price for an insurance.

As input paramet- ers you should provide:

• some authentication
• the trip/stay/ticket/... characteristics (start date, end date, country of origin, country(ies) of destination, ...).

The API will reply with the insurance price.

What is the "NOTIFY API"?

The NOTIFY API shall be used to send us an insurance that's just been sold.

Same input parameters as above:

• some authentication
• the trip/stay/ticket/... characteristics (start date, end date, country of origin, country(ies) of destination, ...).

And more:

• a unique reference id
• the customer's email (so we can send him/her the insurance confirmation)
• the insured name(s)

The API will reply to confirm that the insurance has been registered.

How do I send a request?

You need the API URL (e.g. https://api.chapka.fr/quote/index.php?request=quote for the QUOTE API).

Most requests are made using the POST method.

The parameters are gathered in a JSON structure, that is sent as a "raw payload" of the POST request. Alternatively, the JSON can be sent in a "form data", into a variable named "message". Both will give the same result.

What is the JSON like?

Here is some simple example:

{
    "SENDER" : "AGENCE-XYZ",
    "SIGN" : "123abc456def789...",

    "PRODUCT" : "CAP-EXPLORER",
    "DEPART" : "15/10/2024",
    "RETOUR" : "20/10/2024",
    …

    "REFERENCE" : "REF-123",
    "PREMIUM" : "340.00",
    "EMAIL" : "joe@mail.com",
    …
}

First two parameters (SENDER and SIGN) are the authentication parameters.

They are necessary for QUOTE API as well as NOTIFY API.

Second group (PRODUCT, ...) are the insured item characteristics (PRODUCT is the chosen insurance product, and others are things like start date, end date, destination, ...).

They are necessary for QUOTE API as well as NOTIFY API.

Third group (REFERENCE, EMAIL, ...) are meant for the NOTIFY API only.

Authentication

SENDER is your login ID. Thus, this is a fixed value, something like "MY-COMPANY": Chapka will provide this value.

SIGN is a cryptographic signature. To compute the signature, you need two things: the JSON and a secret key provided by Chapka.

Here is how you compute the signature:

Step 1: get the JSON parameter labels and sort them in ascending order (but do not include "SIGN").

In the prior example, the labels are: SENDER, PRODUCT, DEPART, RETOUR, REFERENCE, PREMIUM, EMAIL.

In ascending order you get: DEPART, EMAIL, PREMIUM, PRODUCT, REFERENCE, RETOUR, SENDER.

Step 2: concatenate the values in the order of sorted labels (do not include any separator).

In the prior example, you'll get a string like: "15/10/2024joe@mail.com340.00CAP-EXPLORERREF-12320/10/2024AGENCE-XYZ".

Step 3: add up the secret key.

This will lead to a longer string: "15/10/2024joe@mail.com340.00CAP-EXPLORERREF-12320/10/2024AGENCE-XYZ1a2b3c4d5e6f..."

(key is colored in red).

Step 4: compute the SHA1 of this string.

The result is the signature that shall be put into "SIGN" parameter.

NOTE: SHA1 produces a 160 bits string, which leads to a 20 bytes string, which results into a 40 characters string. Hence, leading zeros, if they exist, shall not be destroyed!!!

QUOTE API

The QUOTE API URL is:

https://api.chapka.fr/quote/?request=quote

Payload example:

The QUOTE API will give three types of response:

• There is a technical problem or syntax issue (e.g. the "SENDER" parameter is missing, the "SIGN" parameter is missing, the signature is incorrect, ...); 

The HTTP status code will be 400.

The HTTP text response will be a JSON like:

QUOTE API - other functionalities

This URL can also be used:

https://api.chapka.fr/quote/?request=product

With payload:

This will list all available product codes.

Example:

Note that not all parameters are necessary to get a quote.

Examples:

• With "FORMULE=AS" there is no use in providing "MONTANTS";
• With "FORMULE=<others>" the parameter "MONTANTS" is compulsory;
• Parameter "SAR" shall not be used (specific cases only);
• ...

QUOTE API for affiliates

Affiliates are not selling the insurance. They can quote, but customers will buy on Chapka's website.

To quote, an affiliate shall:

• replace "SENDER" field, by "AFFILIATE" field with its affiliation code;
• add a "LANGUAGE" field (without such field, French is used). 

Example:

The response will likely be:

NOTIFY API

The NOTIFY API offers multiple transactions:

• to create an insurance: https://api.chapka.fr/notify/?request=create
• to delete an insurance: https://api.chapka.fr/notify/?request=delete

Create

Sample payload:

Note: there are as many "GENREi", "PRENOMi", "NOMi", as indicated by "NOMBRE".

Typical reply (when no error is reported) will be:

{
    "id":12415,
    "status":200,
    "msg":"successfully created"
}

Note 1: that "id" is a unique number refering to the message received. This is not the created policy number.

Should you need to get the insurance policy details (e.g. the URL to download the insurance documents), you might want to look into the webhook paragraph, below.

Note 2: NOTIFY is a notification protocol. Should you receive a failure, a loss of connection, a timeout, ... be aware that your message probably hasn't been received. Thus your system should handle a retry queue, in order to retry some moments later.

NOTIFY - Webhook

When calling the "create" transaction, you are being returned a simple confirmation along with an ID that is the confirmation that your request has been received.

But should you need to get some more information, like the policy number or the URL leading to the insurance policy documents, then you might want to request Chapka to setup a webhook.

The webhook is a URL in your platform, that Chapka will call everytime a policy is created. The call transports a couple parameters (policy number, document URL, ...). 

Product specific information

Find below some products and the requested JSON parameters.

Parameters for product CAP EXPLORER

CAP EXPLORER is a general travel insurance product, gathering multiple covers.

For product cover details and pricing, please see here.

The parameter "PRODUCT" (or "PRODUIT") will have the following value: "CAP-EXPLORER".

Below are the product specific parameters:

Parameters for product TRANQUILOC

TRANQUILOC has been advised to you if you offer appartments or villas for rent.

For product cover details and pricing, please see here.

The parameter "PRODUCT" (or "PRODUIT") will have the following value: "TRANQUILOC".

Below are the product specific parameters:

Parameters for product CAP ANNULATION

CAP ANNULATION is a cancellation only insurance.

The product specific parameters are: