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.
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
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"
}
]
}
}
}
200 OK
{
"meta": {
"timestamp": "2020-07-29T12:49:45Z"
},
"data": {
"expense": {
"url": "<url_to_expense>",
"status": "Proposed"
}
}
}
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
{
"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"
}
}
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.
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.
All external suppliers must provide the following additional data in data.expense
object:
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:
ExternalSupplier
with expenseType Invoice
None
with expenseType CreditNote
All requests from external suppliers with other values will be rejected with 400 Bad Request
.