Material Supplier Integration API

Introduction

This page describes the Scalepoint Material Supplier Integration API. This API can be used to retrieve information about the claim and assigned Service Partner as well as to integrate information about materials requested by the Service Partner and invoices for the materials provided to Service Partner.

Overview

The process of Material Supplier Integration can be done using the following api:

  • Event-api (for receving information about new claims)
  • Integrate material order
  • Integrate material invoice

The whole flow is shown on the diagram below:

Material Supplier Integration flow

Unified events

When a service on a claim is requested with material provider usage, we send a message to unified events queue.

To recieve these please refer to Events API.

Message structure

{
    "eventType": "repair_updated",
    "payloadVersion": "1.0.0",
    "correlationId": "cafdfac8-f472-4eef-a231-2a3fe9f42028",
    "timestamp": "2020-10-21T08:45:53.3406753+02:00",
    "case": {
        "id": "2f29eca7-bec3-4061-8817-6b29cf13464d",
        "damageCause": "Brand",
        "damageCategory": "Brandskade",
        "policy": {
            "insuranceCompany": {
                "alias": "insurance1",
                "subcompanyAlias": "insurance1",
                "subcompanyName": "insurance one"
            }
        },
        "number": "20200826-01"
    },
    "service": {
        "referenceNumber": "20200826-01-8",
        "id": "25875a6d-5c7b-48e3-8cb9-e620378d99bc",
        "startDate": "2020-12-10T08:12:14.2170965Z",
        "endDate": "2020-12-10T08:41:46.4739975Z"
    },
    "servicePartner": {
        "id": "30574be6-fe0c-45f3-8c3d-016211c166bb",
        "displayName": "Aage and Søn",
        "companyTaxId": "23345622",
        "phoneNumber": "+4512345678",
        "faxNumber": "",
        "responsibleUser": "craftsman_name Last"
    }
}

Material order integration

Authentication

You need an access_token with the scope material-supplier:write to call the material order Endpoint.

Please refer to the documentation about details of authentication process.

Calling the api

To integrate a material order you send a request with an order payload to the dedicated endpoint. Endpoint URL has the following format:

https://<hostname>/host/api/integration/<version>/materialorder/materialsuppliersubmit

Example of the endpoint URL for production environment:

https://entry.scalepoint.com/ecx/host/api/integration/v1/materialorder/materialsuppliersubmit

Optional

Service order number is optional. If provided, it will attach the material order to specific service on a claim.

Request

POST https://entry.scalepoint.com/ecx/host/api/integration/v1/materialorder/materialsuppliersubmit
Authorization: Bearer <access_token>
Accept-charset: utf-8
Accept: application/json
Content-Type: application/json
{
  "timestamp": "2020-12-04T13:16:50Z",
  "payload": {
    "claim": {
      "id": "8976EADF-3805-4E96-8F0D-F0F57F798503",
      "policy": {
        "insuranceCompany": {
          "alias": "companyname"
        }
      }
    },
    "service": {
      "orderNumber": "20200826-01-8",
    },
    "servicePartner": {
      "id": "1AC3EADF-3805-4E96-8F0D-F0F57F798503"
    },
    "order": {
      "number": "123456789",
      "subtotal": 100500.42,
      "vat": 256,
      "total": 12122.21,
      "items": [
        {
          "lineNumber": 1,
          "id1": "ITEM1_ID1",
          "id2": "ITEM1_ID2",
          "title": "ITEM1_TITLE",
          "unit": "Sum",
          "quantity": 7,
          "unitPrice": 22.3,
          "discount": 99.9,
          "subtotal": 212.32,
          "status": "Invoiced"
        }
      ]
    }
  }
}

Response

200 OK

{
  "success": true
}

Error handling

400 Bad Request - when the server could not understand the request due to invalid syntax (e.g. payload doesn't have required data etc...). Client needs to fix the request payload

401 Unauthorized - when client is not authorized (e.g. expired or no Bearer, expired certificate etc...)

404 Not Found - when claim is not found or Service Partner is not found. Status description will provide more details about what exactly caused this error

500 Internal Server Error - unexpected error in Scalepoint system

Error response examples

{
  "success": false,
  "errorDescription": "payload.claim.id with value 'CLAIM_GUID' is not ok. Reason: Provided value is invalid",
  "errorType": "InvalidFormat"
}
{
  "success": false,
  "errorDescription": "Missing materialSupplierId data from the OAuth system",
  "errorType": "GenericError"
}

Duplicate requests handling

If Scalepoint already has a material order with the same claim id claim.id, the same Service Partner id servicePartner.id and the same material order number data.order.number then the existing material order will be overwritten if timestamp of the new one is bigger than the timestamp of the existing one. In case if timestamp of the new material order is less than or equal to timestamp of the existing material order then the new material order will be ignored and 200 OK will be returned.

Material invoice integration

For expense intregration the following endpoint should be used:

https://<hostname>.scalepoint.com/ecx/host/api/integration/v1/expense/materialsuppliersubmit

access token should be optiain with scope: material-supplier:write

Field $.payload.expense.items[].rewardPercent will override default value defined in HUB Property. Please omit this field in request if no override is needed.

Without any rewardPercent defined in items, reward calculation is based on $.payload.expense.subTotal property, so there is no need to provide subtotals for every item.

If there is at least one rewardPercent defined in items then reward is based on subtotals in each item $.payload.expense.items[].subTotal. Remember to provide all subtotals.

Required fields are:

  • $.payload.claim.id taken from repair_updated event
  • $.payload.expense.externalSupplier.relatedCraftsmanId taken from repair_updated event
  • $.payload.expense.expenseType = "Invoice"
  • $.payload.expense.invoiceType = "ExternalSupplier"

Optional fields are:

  • $.payload.service.orderNumber = "Order number of a service that the invoice is related to"

Request example

POST https://<hostname>.scalepoint.com/ecx/host/api/integration/v1/expense/materialsuppliersubmit
Authorization: Bearer <access_token>
Accept-charset: utf-8
Accept: application/json
Content-Type: application/json

{​
  "timestamp": "2021-01-28T08:21:35Z",
  "payload": {​
    "claim": {​
      "id": "416BAE39-972A-47C7-A2B8-B0CB57D60AD3",
      "policy": {​
        "insuranceCompany": {​
          "alias": "companyname"
        }​
      }​
    }​,
    "service": {
      "orderNumber": "20200826-01-8"
    },
    "expense": {​
      "number": "invoice1/2021",
      "invoiceIdentifier": {​
        "kid": "829378273182937189273"
      }​,
      "date": "2021-01-28T08:21:35Z",
      "dueDate": "2021-02-04T08:21:35Z",
      "expenseType": "Invoice",
      "invoiceType": "ExternalSupplier",
      "isDraft": false,
      "issuer": {​
        "name": "Aage and Son",
        "email": "mail@example.com",
        "faxNumber": "+4512345678",
        "phoneNumber": "+4512345679",
        "address": {​
          "street": "Ingemansvej 9",
          "postalCode": "1964",
          "city": "Frederiksberg C",
          "country": "DK"
        }​,
        "cvrNumber": "18476542",
        "giro": "12581145",
        "bankBranchNumber": "1111",
        "accountNumber": "12345678"
      }​,
      "items": [
        {​
          "title": "Brick",
          "id1": "ITEM1_ID1",
          "id2": "ITEM1_ID2",
          "category": "Materials",
          "unit": "Sum",
          "quantity": 10,
          "unitPrice": 10,
          "subtotal": 100,
          "vat": 25,
          "rewardPercent": 5
        }​,
        {​
          "title": "Door",
          "category": "Materials",
          "unit": "Sum",
          "quantity": 2,
          "unitPrice": 50,
          "subtotal": 100,
          "vat": 25
        }​
      ],
      "subtotal": 200,
      "vat": 50,
      "total": 250,
      "description": "description",
      "invoiceRemark": "Invoice remark",
      "externalSupplier": {​
        "relatedCraftsmanId": "618A6DA6-0931-4765-A9E8-1B24A98A543F"
      }​,
      "files": [
        {​
          "name": "damagedesc.txt",
          "mimeType": "text/plain",
          "size": 541,
          "description": "Sent by claimant",
          "content": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gUGVsbGVudGVzcXVlIGRpYW0gbWF1cmlzLCBwZWxsZW50ZXNxdWUgc2VkIG1ldHVzIHF1aXMsIHBlbGxlbnRlc3F1ZSBzYWdpdHRpcyBvZGlvLiBNb3JiaSBsZW8gbmliaCwgbGFjaW5pYSBhdCBsb3JlbSB2aXRhZSwgZWxlaWZlbmQgc29kYWxlcyBlc3QuIFNlZCBhdCB0dXJwaXMgbGVvLiBGdXNjZSBwZWxsZW50ZXNxdWUgbG9yZW0gdmVsIGxlbyBsYW9yZWV0IG1vbGxpcy4gUGVsbGVudGVzcXVlIHZlbCBuaWJoIGZlbGlzLiBQZWxsZW50ZXNxdWUgdm9sdXRwYXQgaGVuZHJlcml0IHVybmEgdXQgc2VtcGVyLiBTZWQgaWQgcXVhbSByaG9uY3VzLCBpYWN1bGlzIGxlY3R1cyBldSwgZmlzc2ltIGxhY3VzLiBOdWxsYSBmYWNpbGlzaS4gRnVzY2UgbG9yZW0gZXJhdCwgdGVtcG9yIGluIG9yY2kgaWQsIHZlbmVuYXRpcyByaG9uY3VzIHF1YW0uIEludGVnZXIgbW9sbGlzIG9ybmFyZSBiaWJlbmR1bS4gVmVzdGlidWx1bSBub24gYWxpcXVldCBhcmN1Lg=="
        }​
      ]
    }​
  }​
}​