Expense Integration API

Introduction

This page describes the Expense Integration API. This API can be used to integrate expenses from external companies. This will reduce time spent on manually processing such expenses.

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

Submit Expense

Endpoint URL has the following format:

https://<hostname>/host/api/integration/<version>/expense/submit

Example of the endpoint URL for production environment:

https://entry.scalepoint.com/ecx/host/api/integration/v2/expense/submit

Request

POST https://entry.scalepoint.com/ecx/host/api/integration/v2/expense/submit
Authorization: Bearer <access_token>
Accept-charset: utf-8
Accept: application/json
Content-Type: application/json
{
  "meta": {
    "timestamp": "2020-07-29T12:49:45Z"
  },
  "data": {
    "claim": {
      "id": "8976EADF-3805-4E96-8F0D-F0F57F798503",
      "tenant": "insurance1"
    },
    "expense": {
      "number": "Invoice-12345",
      "date": "2020-07-29T12:49:45Z",
      "dueDate": "2020-08-27T12:49:45Z",
      "expenseType": "Invoice",
      "invoiceType": "ExternalSupplier",
      "isDraft": false,
      "invoiceIdentifier": {
        "fik": {
          "type": "71",
          "identifier": "123456789012347",
          "creditorNumber": "12345678"
        }
      },
      "issuer": {
        "name": "Material Supplier A/S",
        "email": "mail@supplier.com",
        "faxNumber": "+4512345678",
        "phoneNumber": "+4512345679",
        "address": {
          "street": "Ingemansvej 9",
          "postalCode": "1964",
          "city": "Frederiksberg C",
          "country": "DK"
        },
        "companyTaxId": "123123123",
        "giro": "12581145",
        "bankBranchNumber": "1111",
        "accountNumber": "12345678"
      },
      "payer": {
        "name": "Aage and Son",
        "email": "contact@aageandson.com",
        "faxNumber": "+4534343434",
        "phoneNumber": "+4598989898",
        "address": {
          "street": "Ingemansvej 9",
          "street2": "",
          "postalCode": "1964",
          "city": "Frederiksberg C",
          "country": "DK"
        },
        "companyTaxId": "983123123",
        "giro": "92581145",
        "bankBranchNumber": "1111",
        "accountNumber": "92345678"
      },
      "items": [
        {
          "title": "Brick",
          "category": "Materials",
          "unit": "Sum",
          "quantity": 10,
          "unitPrice": 10,
          "subtotal": 100,
          "vat": 25
        },
        {
          "title": "Door",
          "category": "Materials",
          "unit": "Sum",
          "quantity": 2,
          "unitPrice": 50,
          "subtotal": 100,
          "vat": 25
        }
      ],
      "subtotal": 200,
      "vat": 50,
      "total": 250,
      "description": "Invoice description",
      "invoiceRemark": "Invoice remark",
      "externalSupplier": {
        "relatedCraftsmanId": "1AC3EADF-3805-4E96-8F0D-F0F57F798503"
      }
      "extraProperties": {
        "additionalData": {
          "property1": "value1"
        }
      },
      "files": [
        {
          "name": "invoice.oioubl",
          "size": 1024,
          "description": "Invoice in OIOUBL format",
          "content": "RmlsZSBjb250ZW50"
        }
      ]
    }
  }
}

Response

200 OK

{
  "meta": {
    "timestamp": "2020-07-29T12:49:45Z"
  },
  "data": {
    "expense": {
      "url": "<url_to_expense>",
      "status": "Proposed"
    }
  }
}

Error handling

400 Bad Request - when the server could not understand the request due to invalid syntax. 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

{
  "meta": {
    "timestamp": "2020-07-28T10:54:24Z"
  },
  "data": {
    "error": "Claim with [id] 8976EADF-3805-4E96-8F0D-F0F57F798503 could not be found"
  }
}

{
  "meta": {
    "timestamp": "2020-07-28T10:54:24Z"
  },
  "data": {
    "error": "Validation failed: you can either specify [fik] or [kid] but not both"
  }
}

Duplicate requests handling

If Scalepoint already has an expense with the same claim id claim.id, the same Service Partner id data.expense.externalSupplier.relatedCraftsmanId (if present in payload) and the same expense number data.expense.number then existing expense will be overwritten if timestamp of the new one is bigger than the timestamp of the existing one. In case if timestamp of new expense is less than or equal to timestamp of existing expense then the new expense will be ignored and 200 OK will be returned.

Implementation notes

If by some reason Scalepoint fails to submit invoice then it always tries to save it as a draft instead and report back Draft status and URL to complete invoice in HUB Property.

Some insurance companies can restrict submitting full invoice. In this case draft invoice is only supported.

External supplier expenses

All external suppliers must provide the following additional data in data.expense object:

externalSupplier – object which contains additional data from external suppliers
- relatedCraftsmanId – should contain id of the Service Partner which current expense is related to (path in JSON is data.expense.externalSupplier.relatedCraftsmanId)

All requests from external suppliers without these data will be rejected with 400 Bad Request.

External suppliers could integrate only the following expenses:

invoiceType ExternalSupplier with expenseType Invoice
invoiceType None with expenseType CreditNote

All requests from external suppliers with other values will be rejected with 400 Bad Request.

Expense Integration API

On this page