Events API Integration from Clients to Scalepoint

Introduction

Scalepoints EventApi solution is a B2B two-way messaging bridge, so events could be published from Scalepoint to Clients and vice versa. It is not necessarily required to have do the bi-directional messaging from the begining. For example, first clients could start receiving messages and at later starge clients could start publishing.

Clients to Scalepoint

In this page we discuss how clients can publish events to Event API using EventApi REST Interface.

Integration Process

The process of integration with event api is divided into two steps:

• Authentication
• Publish Events

Authentication

You need an access token in order to send data to the Integration Endpoint. This access token can be obtained from the Authentication Endpoint. Please refer to the documentation about details of authentication process.

Endpoints

Authentication endpoint

For authentication, Scalepoint provides two endpoints – one for production and one for everything else.

Production endpoint

https://accounts.scalepoint.com/connect/token

Non-production endpoint

https://sandbox-accounts.scalepoint.com/connect/token

Event Integration API endpoint

The integration endpoint is in the following format:

https://www.scalepoint.com/api/events/v1/<country>/external/<tenant>/send

The actual format of this will depend on the insurance company, the country in which it operates and the version of the API.

Assuming the following:

• Country: Denmark
• Tenant: ABC Insurance
• Other brands: Budget Insurance

The endpoint could look something like this:

https://www.scalepoint.com/api/events/v1/dk/external/abcinsurance/send

For testing purposes, you will be given access to a project server and the hostname-part of the endpoint would change accordingly:

https://<hostname>/api/events/v1/dk/external/abcinsurance/send

Please discuss with your account manager, which project server you have been assigned in order to determine the actual endpoint. Integration - Publish Event

Publish event contains of three different parts:

• Event data;
• Authorization header.
• Event Type header

Publish event data presented in JSON format is sent in the request body.

This is the example of the simplest publish event data:

{

  "eventType": "payment_status_updated",
  "payloadVersion": "1.0.0",
  "correlationId": "70c6d351-016f-4c9e-b1a9-d581fc3a596b",
  "timestamp": "2017-07-25T10:31:28.2519514Z",
  "payment": {
    "uuid": "967ce1a4-a55a-4765-bd5b-bafcb4178fd3",
    "status": "canceled",
    "statusReason": "Payment rejected by claimant's bank"
  }
}

Authorization header has name 'Authorization'. It has value built from access_token in following format:

Bearer access_token

Note the important space character between 'Bearer' and access_token value. Ensure that you send correct 'Content-Type' header. It should be 'application/json;charset=utf-8'

Event Type header has name 'Event-Type'.

Integration - Publish Event - Response

Publish event Response contains data in JSON format. Response contains following fields:

id - Scalepoint returns the unique value of the newly published event

Successful response

example, successful response returns HttpStatus.CREATED

{
   "_id": 1
}

Error response Examples Incorrect payload

{
  "message": "Incorrect payload, missing [xxxxxxxx]",
  "valid": false
}

Insufficient scope

{
  "error": "insufficient_scope",
  "error_description": "Insufficient scope for this resource",
  "scope": "events"
}

Authorization Header Missing or Unauthorized

{
  "error": "unauthorized",
  "error_description": "Full authentication is required to access this resource"
}

Event-Type Header Missing or Bad Request

{
  "timestamp": "2017-05-05T11:32:03.535+0000",
  "status": 400,
  "error": "Bad Request",
  "exception": "org.springframework.web.bind.ServletRequestBindingException",
  "message": "Missing request header 'Event-Type' for method parameter of type String",
  "path": "/api/events/v1/dk/external/abcinsurance/send"
}

Error codes