Web Shop Integration

This section will describe what a typical web shop integration - for example WooCommerce, Shopify or a custom implementation - might look like. It can be seen as a special application of the more general description in the Concepts section, where only the pieces relevant to a web shop are covered and a lot of options that do not apply to this scenario are removed.

Even if you are reading this in preparation for a web shop integration it might be worthwhile to look through the Concepts sections first.

Main Entities

There are three main types of objects the API is concerned with:

• User - the customer buying an item in the web shop
• InsurableObject
• Insurance

In the following the Owner entity represents the user who is buying an item in the web shop.

In a rental scenario, the Counterpart will typically be the person who rents the object. In a web shop setup there is no renter and instead the Counterpart will be a fixed, pre-defined identity. The entity is set up by Omocom and is represented by a Guid which is communicated as part of the onboarding process.

Typical Web Shop Flow

The API is typically used in the following sequence:

• The platform uses the PremiumInformation endpoint to retrieve the current premium price list from Omocom. The details will vary depending on what kind of premium calculation will be in effect for the particular integration.
• The price will be displayed to the user, typically as an add-on purchase suggested to the user of the type "You might also be interested in this".
• Once the user has placed the items he wants to purchase, he checks out from the web shop.

At this point the platform need to purchase the insurances with Omocom:

• A user is created (POST User) if not already in the system from a previous purchase.

For each insurance to be purchased, the following should happen:

• One InsurableObject is POSTed, containing details on the object to be insured; make, model, description etc.
• One Insurance is POSTed with details on Insurance Product Name, the duration of the insurance, the counterpart ID etc. and a price quote is returned, along with a list of add-on insurances, if any.
• The Insurance is Accepted - everything is ready.

When the given start time of the insurance comes, the insurance will be automatically activated and insurance information will be sent to the customer via email.

Sample Flow

Below is an example of what a web shop intgration could look like for a fictive webshop Electroshop. Note that some details are dependent on the kind of insurance agreement is set up between the platform and Omocom, so an actual integration might divert from the below.

Create User

If the user is new to the platform, a User object must be created. To find an existing user there is a /find endpoint available.

POST https://<API URL>/v1.3/electroshop/SE/Users
Authorization: Bearer <access_token>
Content-type: application/json

{
    "MarketName": "SE", 
    "UserId": "someusername123", 
    "FirstName": "Glen", 
    "LastName": "Clarkson", 
    "SocialSecurityNumber": {
        "SSN": "19840726-1234", 
        "Country": "SE"
    }, 
    "PhoneNumber": "+46705554422", 
    "StreetAddress": "Somestreet 6", 
    "ZipCode": "12950", 
    "CountryCode": "SE", 
    "EmailAddress": "glen.clarkson.476@gmail.com", 
    "Culture": "sv"
}

Create Insurable Object

objectId need to be an unique ID that represents the device. If no such nubmer is available the order number or receipt number can be used, if necessary with a counting suffix like -1, -2 and so on.

The exact set of ExternalProperties will be agreed upon in collaboration with Omocom.

POST https://<API URL>/v1.3/electroshop/SE/InsurableObjects
Authorization: Bearer <access_token>
Content-type: application/json

{
    "objectId": "", 
    "objectCategory": "Tablet", 
    "ownerHandle": "<the guid representing the owner from previous step",
    "shortDescription": "iPhone 12 128Gb white blah blah", 
    "description": "Optional extra description",
    "ExternalProperties": [
        {
            "name": "Make",
            "value": "Apple"
        },
        {
            "name": "Model",
            "value": "iPad Air 4 128Gb Space Grey"
        },
        {
            "name": "IMEI",
            "value": "123456789012345"
        }
    ]
}

Create the Insurance

The ObjectHandle part of the URL is the identifier returned from the POST of the InsurableObject. counterpartHandle is a constant that will be provided by Omocom for each platform. The property ReceiptNumber should represent order, shopping cart, receipt or some other entity that is distinctively identifying the purchase.

POST https://<API URL>/v1.3/electroshop/SE/Insurances/<ObjectHandle>
Authorization: Bearer <access_token>
Content-type: application/json

{
    "product": "Refurbished Electronics Insurance",
    "insuranceStartDateTime": "2022-10-03T11:36:48.0000000+01:00", 
    "insuranceEndDateTime": "2023-10-02T23:59:59.0000000+01:00", 
    "counterpartHandle": "66006782-1921-4AE9-9E21-698BA45C99C9", 
    "properties": [{
        "name": "PurchasePrice",
        "monetaryValue": {
            "amount": 8500,
            "currency": "SEK"
        }
    },
    {
        "name": "ReceiptNumber",
        "value": "7589438924370954"
    }]
} 

Accepting the Insurance

The insurance POST will return the insurance ID and a price quote for the insurance. The last step is to /accept the quote, after which point the insurance is active.

POST https://<API URL>/v1.3/electroshop/SE/Insurances/{{InsuranceId}}/accept
Authorization: Bearer <access_token>
Content-type: application/json

[]

An insurance letter will be sent to the policy holder, and the insurance will eventually be invoiced to the platform.