Expense automation

Introduction

There are several functions in Next & Hub that allow a partner to help automate the economic transactions and advance workflow.

This document is intended for partners and customers of Next as a guideline for what is possible, how to configure Next and which Hub functions to use.

Definitions

A cost associated to an account and assignment

Definition	Description
Customer	A real estate agency using Next
Expense
Hub	The API for communication with Next
MVA	Norwegian VAT
Next	A web-based system for real estate agents in Norway
Partner	A supplier to a customer using Hub
Posting code	A template for an expense

There is a set of functions in Hub for handling expenses. They allow for adding, updating and deleting an expense in Next. All expenses must be tied to an estate.

Each case needs its own unique posting code tag created in Next. This tag is used when calling Hub to identify the posting code, which describes how cost should be handled. I.e., which account should be charged (buyer / seller / broker), which MVA rate should be used and should the amount be paid to the partner’s account / KID at settlement or must the partner invoice it separately.

If the customer is lacking the posting code with the specific tag Hub returns 412, it is important to have proper error handling to avoid mishandling of economic information. For more information, see error handling.

Expense types

There are two types of expenses that can be used, the call to Hub is the same but the setup in Next differs. The major difference between them is if the amount should be payed automatically at settlement (remit) or if it will be invoiced separately (cost).

Remit posting code

– Amount must include mva if applicable
– Posting code in Next must be setup with remit
– Posting code in Next should be setup without MVA
– Charges buyer / seller / customer depending on posting code
– Payed when settlement is done

Cost posting code
– Amount must include mva if applicable
– Posting code in Next must be setup without remit
– Posting code in Next should be setup with correct MVA (normally “Utgående mva 25%”)
– Charges buyer / seller / customer depending on posting code
– Payed when separate sent invoice is due

See next section for more information and screenshot.

Setup in Next Office

To setup posting codes in Next, start Next Office and from the menu Next Office, select “Posteringskoder”.

1. The first section with kode, navn and tag are used for identifying the posting code. Tag is the external identifier to be used in Hub.
   The tag must be known to the partner and the customer and should be decided by the partner. All customers using the same product should have the
   same tag so the partner does not need to use different tags for different customers for the same product.

   Vitec recommends the tags to have the following format HUB__.

   For example HUB_PHOTOINC_DRONE for expenses regarding drone videos and photos. Max length of the tag is 31 characters.

2. Which MVA code should be used. Normally for Remit and Utgående mva 25% for Cost
3. Which accounts should be used for debit and credit, i.e. which party should bear the cost.
4. If the amount should be remitted (see expense types). If remit is selected it will be remitted to the account with the KID sent to Hub. If KID is missing matrikkel will be used as KID if that checkbox is checked.

Hub functions

There are Post, Put and Delte calls nessecary to avalable in Hub to add, update and delete an expence. A tag (set up as descripbed abowe) must be provided when creating a new expense.
It is possible to alter the expense (PUT and DELETE) as long as the expense is a draft. After the expense been (economically) posted, there is no way to change the expense through Hub.

It is possible to send a new expense with a correction though as long as the settlement is not finished.

Subsequent postings does not affect the budget but will create now postings of the same type. Duedate is normally unused and payment will be sent at
different times depending on expense type (see above) at different times depending on expense type (see above).

Handling of posted expense

A posting code belonging to the seller can be marked as being a part of the budget for the assignment. Then it will be shown in the “oppdragsavtale”. The
first update to that posting code through Hub will update the sum and text in the budget as well as creating a posting.

Postings will follow the configured behavior for moving from status draft to posted in the same way postings created in Next does.

Error handling

Since there is no guarantee for an error free connection between the partners, client and Hub it is imperative that all solutions are built with proper error handling.

HTTP Status code in the 200-299 segment means that the information was written successfully. Other status codes should lead to retries with some exceptions
(for example 401 and 403 which denotes that the partner have the wrong credentials or are lacking rights). See the technical documentation for more information on http status codes.

If information cannot be written, it should be stored for retrial. Retries can for example be sent on an increasing schedule, this is called “exponential backoff”.
First retry after 5 minutes, then 10 minutes, 20, 40 etc. with a maximum retry interval of 4 hours. If the call does not succeed for a couple days,
the owner of the system should be notified to handle the situation.

NB! An ultimately unsuccessful call to Hub to post an expense will end up in a loss of money (if it is a remit expense, for the partner, if it is a cost expense for the customer).
Good error handling and follow-up on errors is imperative!

Monitoring

So, how do we verify that the total amount of expenses for a partner is correct for a month?

For the customer there is a report in Next called “Posteringsoversikt” that summarizes expenses with a certain code. Using this it is possible to summarize all expenses for a certain partner for a month.

Compare this report to the invoice sent by the partner for the same period and everything should match.

The partner should of course monitor that all their Hub calls have received a 200 ok and have insight on which expenses have failed and why.