Mode 1: Mode based on billing documents without accounting functionality, formerly known as VERK

Mode 2: Invoice-based mode with accounting functionality, formerly known as FIBU

Mode 3: Mode based on billing documents with accounting functionality, formerly known as VERK2FIBU

(Mode 2, Mode 3)

Midoco connects to the XERO Accounting API to transmit journals created in Midoco. This transmission is done globally for all customers working with that interface on a scheduled basis. Currently, the transmission is done at 04:00 CET/CEST - so once a day for anything that happened up to that point.

Midoco connects to XERO using an app provided by XERO having the 'custom connection' flavour.

Setup of the API connection

In order to make use of that API connection, you need to register an app connection for Midoco in your XERO App management.

To register Midoco, please:

1. read the following article provided by XERO https://developer.xero.com/documentation/guides/oauth2/custom-connections/#setting-up-a-custom-connection
2. go to https://developer.xero.com/app/manage and hit the "New App" button
3. provide at least:
   1. a name for the connection for you to recognise later on
   2. make it a 'Custom Connection' please
   3. the following URL: https://developer.xero.com/
4. after hitting the "Create App" button, please provide min. the following scopes (these are the permissions for Midoco in the API):
   1. accounting.settings
   2. accounting.transactions
   3. accounting.contacts
   4. accounting.contacts.read
5. next you will get an email issued by XERO asking you to 'Connect' and authorise the app

Walking through those steps successfully, you will be provided with a 'Client ID' by XERO which you are kindly requested to pass on to your Midoco Project Manager. This Client ID is required to set up the interface on our side.

Additionally you need to create the "Client Secret"

Setup of Master Data

There are some things you need to take care of to when using the Midoco-XERO API interface. If ignored, the API will return errors which will make the transactions get stuck (they wont transfer to XERO).

BEFORE you create the first journal line in Midoco (before GoLive)

1. Provide Midoco with all your TAX CODES

   1. to do so, you need to retrieve your TAX CODES via the XERO API Explorer: https://api-explorer.xero.com/

   2. if you never used API Explorer before, you might need to select/connect the API Explorer to your XERO Organisation (XERO will guide you there)

   3. once done, please do the following:

      1.  1= make sure your organisation that Midoco is supposed to send journals to, is selected here, if not, please select the XERO Organisation Midoco is asked to send data to

      2.  2 = in API operation, please select:

         1. API = XERO Accounting API

         2. Endpoint = TaxRates

         3. Operation = Get Tax Rates

      3. 3 = Make the request (asking XERO to return a response that includes your Tax Rates and the corresponding TAX CODES

      4. 4 = copy the result that you get to your clipboard

      5. open a text editor and paste the copied data there

      6. save the file

      7. send that file to your Midoco Project Manager

2. Make sure that all accounts set up in Midoco Chart of Accounts also exist in XERO

   1. any account receivable in Midoco needs to be a Customer Contact in XERO having not only the name but also the Account Code used in Midoco (define it via "Add account number" for the Customer Contact)

   2. any account payable in Midoco needs to be a Supplier Contact in XERO having name and Account Code used in Midoco (define it via "Add account number" for the Supplier Contact)

   3. when working with Accruals, Midoco needs to transfer them as manual journals. This requires the setup of the non-P&L accrual accounts (e.g. for purchase accrual, commission accrual) in XERO Chart of Accounts.

   4. all other account types in Midoco need to be set up in Accounting → Chart of accounts in XERO

   5. payment accounts (e.g. for taking credit card payments from your clients) need to be set up in Chart of accounts in XERO as an Account Type = Current Asset and need to have the "Enable payments to this account" checkbox ticked. Example:

3. Working with Agency Cost Centres? Set-up of XERO Tracking Categories.

   1. When working with agency cost centres please set them up both in XERO :
      1. Accounting → Advanced:
         
      2. Go to Advanced settings → Tracking categories
         
      3. Set up a tracking category having the Tracking category name = Cost Centre
         
   2. ... and please set them up in Midoco Midoffice before making use of them.
      1. Order Master Data → Cost Centres: 
         
   3. Please ask Midoco Helpdesk to enable working with Tracking Categories in your XERO interface for your Midoco Org.Unit.
   4. potentially you can have a different wording for the Tracking Category in XERO. If that is the case, please let our Helpdesk Team know the exact name of your Tracking Category for cost centres in XERO.

Transmitting Data Midoco → XERO

The Midoco - XERO interface is working seamlessly for you in background - given the setup is correct. A scheduled job triggers the transactions to be sent to XERO via the API automatically - this applies to all Midoco customers using the Midoco-XERO interface. Today, the scheduled job transmits data every morning at 04:00 CE(S)T (which is 03:00 GMT).

Midoco flags each journal line once successfully transmitted to XERO with the Is Exported checkbox and it gets an Export ID (columns usually found on the right edge of the table):

In the Accounting Export tab you will find each of the exports done for your Midoco Org. Unit. You can download the files by using the button in the Export column and look at what we transmitted successfully.

There is no button to manually trigger the export at the moment, as this is a fully automated background interface.

Transmission Sequencing

Each XERO data transmission is done in the following sequential (consecutive) steps to make sure an invoice arrives first before an allocating credit note or payment which needs to refer to it is sent:

1. Transaction Dates found oldest to newest.
2. Within each transaction date:
   1. Sales Invoices
   2. Purchase Invoices
   3. Sales Credit Notes
   4. Purchase Credit Notes
   5. Sales Payments
   6. Purchase Payments
   7. Manual Journals

Transaction References

Supplier Invoices and Supplier Commission Invoices

Midoco appends the account payable (where commission receivable set up with the supplier also that account receivable) to the transaction reference to make transaction references unique.

In addition - to facilitate the option of partially booking a supplier invoice in Midoco today and booking the other part(s) later - the Midoco Journal ID of the first item in the supplier/supplier commission invoice is appended.

Example:

You are provided with a supplier settlement going by the invoice number 123456 issued by Hertz who happen to deduct supplier commission at source.

Your Midoco supplier setup has a (supplier) account payable for Hertz =  4711 and in addition a (commission) account receivable = 0815.

This setup tells Midoco you want to see the commission values for Hertz on a separate account receivable/contact 0815. All the purchase prices (without commission deduction) will go to the supplier contact with account ID 4711.

Midoco is now creating the following invoices in XERO:

In XERO an invoice number can have up to 255 chars.

Payment on Supplier Invoices

When paying off supplier invoices in Midoco the same logic will be applied of splitting this payment accordingly to the invoice numbers in Xero.

Transaction Description

Midoco appends the transaction description for each journal line by:

• %iID:xxxxxxxx$  → this is the Midoco itemID prefixed by a separator % and suffixed by a separator $. this itemID can also be found in Midoco Mode 2´s booking journal export see Release 17.1 (12.04.2023)#Accounting-BookingJournal
• ' - jID: xxxxxxxx  → this is the Midoco Booking Journal journal ID

So depending on your units Booking Text setup (happy for you to check with your Midoco Project Manager) the description for an invoice line can look like this:

• 2023-01-01 - Purchase Invoice  4711 - %iID:123456789$ - jID: 362817
  (determined by your units Booking Text setup) - %iID:the Midoco itemID for this journal line$ - jID: the Midoco Journal ID for this journal line

A journal in Midoco can be linked to an item when:

• a billing document/sales invoice is started in the order and all billing positions on the invoice link to an order
• any suppliers purchase or commission invoice which is entered in the orders supplier invoice tab, in Manual Supplier Settlement or Electronic Supplier Settlement as well as Commission Invoicing

A journal in Midoco does not link to an item when:

• billing positions on a sales invoices are created (entered) manually by the user in the billing document (so not coming from an order´s invoicing process)
• manually created journals
• payment positions on a billing document
• bank payments, credit card payments or any other payment entered in Midoco (payments never refer to an item but to an invoice which can include multiple items)
• clearing journals (Lists → Account Entries → Accounts/Ageing Reports using the Clearing button)

Transaction Dates

Midoco determines the transaction date in Midoco Midoffice based on your Turnover Recognition Policy.

The invoice date (sales invoice issue date, purchase invoice date) are the ones usually taken into account.

However, when a user enters an invoice date (e.g. in supplier settlement) which will hit a date that you already finished the tax reclaim for/P&L allocation already done, than this might lead into unexpected situations.

Therefore we recommend to work with closing accounting periods in Midoco (Applications → Accounting → Accounting Periods).

When the period is closed in Midoco for which you entered an invoice, Midoco will still keep that entered date as transaction date in Midoco Midoffice.

In the Midoco → XERO transmission the Transaction Date/Invoice Date is modified to be the first date of the first open period.

XERO Response Information

InvoiceID/BillID

XERO upon transmitting an invoice or bill via the interface creates an invoiceid or billid which is a (unique) hash value that you can also see in XERO in the URL when looking at a specific invoice or bill:

In Midoco you can find this invoiceid or billid hash information in the comment of an invoice (sales or purchase):

XERO API Communication

Any Midoco request sent to XERO (batch transmission) is available via the Download column in Applications → Accounting → Accounting Export:

For any erroneous transaction Midoco also provides the XERO API feedback in this file available via Download:

XERO API Restrictions

There are some restrictions to the Midoco-XERO interface which you need to pay attention to when creating journals in Midoco.

Hence we would like to recommend to keep the following in mind.

Best Practice

• When creating new accounts/contacts, please create them first in XERO and only than in Midoco Chart of Accounts
• When creating new TaxRates in XERO, please do ProvideMidocowithallyourTAXCODES again
• Make sure, that there is a 1:1 relation of a supplier invoice to an account payable/contact already when doing the supplier settlement in Midoco. So please check before you book the settlement:
  
  • for an invoice issued by a supplier, that only this suppliers account payable is used
    
    • no deviating settlement types which link to another account payable
    • no other supplier set up with the item
    • correct the items (change supplier, change/remove settlement type) before booking the settlement
  • for a settlement/statement issued by a financial vendor/3rd party like your credit card company when using your TMC´s credit card for paying the supplier:
    • only this financial vendors settlement type is used
    • all the items have that settlement type set
    • correct the items which do not match the above before booking the settlement
• Always link payment transactions to invoices.
  • for Credit Card payments this is done by entering the credit card in the sales invoice before printing the sales invoice.
  • for Bank payments this is done by selecting the contacts (customer or supplier)´s account code and than use the magnifier icon next to the Transaction Reference field:
    
• Allocate max. the invoice value´s worth of payment amount (by amending the amount field) to the invoice. XERO returns an error message when trying to send a higher payment amount than the invoice amount.
  Also when a customer e.g. pays their invoice in > 1 payment, the total of those payments must not exceed the invoices value.
  • If you need to work with Overpayment, please get in touch with your Midoco Project Manager to talk about your requirements.

How to book in Midoco

Midoco handles DR/CR account assignment and the amount for automatically / system created journals (Sales invoices, credits, Purchase invoices, credits).

However, when working with manual booking, doing bank statement handling etc. you need to do it this way around to make the transactions arrive successfully in XERO.

Export Errors

The XERO API returns an error when not accepting the journal line. When there is e.g. a huge bulk invoice or huge supplier settlement and only one of the journal lines created for that document, the whole document would not transmit to XERO.

Any non-transmitted journal entries can be found in Midoco Midoffice → Applications → Accounting → Accounting Export:

To find out which transactions are affected by the error, please change to the Booking Journal tab and query for transactions having such an ErrorTransactionsXERO export ID:

Any of those lines shown for such an Export ID has not transmitted to XERO and needs manual creation in XERO.

Error E-Mails on XERO Errors

Additionally, Midoco sends an E-Mail to your Org.Unit E-Mail address found in Org.Unit Master Data → E-Mail in case a XERO Export Error happens.

Please take care of that address being up to date and the mail account being checked frequently for new messages.

The E-Mail has got the subject "Xero Export Error List for Export ID: XXXX":

The CSV contained in that E-Mail gives you a detailed listing of the journals affected by the XERO errors which need to be created manually in XERO (because they will not transmit due to errors).

Please check each of them individually and

• amend the error reason in XERO (e.g. create the missing contacts or account ID´s) and
• create the transactions which resulted in an error manually in XERO

No Error Emails

The error emails are sent only in case Xero does not create an invoice/bill or manual journal based on our transmission.

In return that means, that on the some situations we are not able to create such an error email report such as:

• the Xero interface is not available (Xero is down e.g. for maintenance reasons or other)
• Xero accepted the invoice/bill or manual journal but was unable to process a payment reconciliation due to this invoice already being paid off or a (full) credit / void of that invoice)