Dynamics 365 Business Central

Overview legend

Introduction

Microsoft Dynamics 365 Business Central is a cloud ERP for small and medium-sized businesses, covering financials, operations, sales and customer service. Some operations need the Chift extension, available from Business Central version 23. See Connect Business Central.

Activate Business Central

Partner keys

You’ll need your own OAuth2 app, registered with Microsoft. The app is registered in Azure. No approval from Microsoft is needed.

Sign in to the Azure portal as an admin. If you do not have an account yet, create a free one.Your tenant name appears in the top-right corner. If you have no tenant, create one.

Go to App registrations and click New registration. Name the app, choose one of the Multitenant options depending on your needs, and register it.

Add the redirect URI

In the app, go to Manage › Authentication, click Add a platform, choose Web, enter the redirect URI below, and click Configure.

https://chift.app/oauth2/redirect

Grant the API permissions

Go to API permissions › Add a permission › Dynamics 365 Business Central. Under Delegated permissions, select Financials.ReadWrite.All, user_impersonation and User.Read, then click Add permissions.

Create a client secret

Go to Certificates & secrets › Client secrets and add a secret, with a description and an expiration date that suits you. Copy its value straight away. From Overview, copy the Application (client) ID.

Turn off assignment

In Enterprise applications, open the app and set Assignment required? to No.

Activate Business Central in your Chift account

In Connectors, enter your client ID and client secret.

Connector settings

Mandatory extension makes the Chift extension required for every new connection, so each one can use the extended capabilities.

No (default): connections are created without the extension. Operations that need it return ERROR_CONNECTOR_MISSING_EXTENSION.
Yes: the connection fails when the extension is not installed, and the end user is asked to install it.

Choose Yes if your use case relies on any operation the extension provides. See Chift extension for Business Central below.

The Deferral Codes setting in the Chift connector settings, with its options Not active and Active

Deferral Codes handles deferral codes on sales and purchase invoices.

Not active (default): no deferral code is applied.
Active: the end user picks a deferral code while connecting. Chift applies it to the lines of every invoice sent with a start and end date.

Choose Active if your invoices carry a start and end date to defer. The end user also needs the Chift extension installed.

The Delivery date as posting date setting in the Chift connector settings, with its options No and Yes

Delivery date as posting date uses the invoice’s delivery date as the posting date when Chift creates invoices.

No (default): the posting date is the forced financial period when one is sent, otherwise the invoice date.
Yes: the posting date is the delivery date. It only applies to invoices sent with a delivery date.

Choose Yes if your invoices must be booked on their delivery date.

Test Business Central


Environment	Self-service test account
How to get it	Sign up for a free trial, or test with one of your clients who uses Business Central
Demo data	Yes, the trial includes a demonstration company with sample data

Vendor fees

No vendor fees, for you or your end users.

Connect Business Central

Business Central setup guide for end users

The full step-by-step, with screenshots.

Before they start, your end users need:

Business Central online (on-premises Business Central is not supported)
a Microsoft account with access to their Business Central environment
the Chift extension, for the operations listed below

To connect, they:

sign in with their Microsoft account
grant your app access to their Business Central environment
choose the Business Central environment, then the company to connect
if you enabled the matching settings, choose a default analytic plan and a deferral code

Chift extension for Business Central

The extension gives access to data that Business Central’s standard API does not expose. It does not change how Business Central behaves. It is required to:

create invoices
create and read journal entries
read journal entry attachments
create financial entries
read outstandings
match entries
read and create bank accounts
push bank transactions, from extension version 1.0.6
create ledger accounts
use deferral codes on sales and purchase invoices, together with the connector setting above

It is available from Business Central version 23. Existing customers can add it without changing their current connections. New customers can install it before or after setting up the connector.

The extension is only available through Microsoft AppSource. It cannot be installed on on-premises Business Central or on environments without AppSource access.

Bank transactions setup

If you push bank transactions, your end users need:

the extension in version 1.0.6 or later. Without the extension, the push returns ERROR_CONNECTOR_MISSING_EXTENSION. With an older version, it returns ERROR_CONNECTOR_OUTDATED_EXTENSION.
a Bank Acc. Recon. Template Name and Bank Acc. Recon. Batch Name in General Ledger Setup, when their company makes journal templates mandatory. They set them once for the whole company.

The transactions arrive in a Payment Reconciliation Journal, where the end user posts them. The General Ledger Setup steps are in the end-user guide.

Rate limits

Business Central applies OData limits per user, meaning the Microsoft account that authorized the connection.

Limit	Value
Requests	6,000 per 5-minute sliding window
Processed at the same time	5 requests
Accepted at the same time	100 requests, including a queue of 95

When the limit is exceeded, Microsoft returns HTTP 429 Too Many Requests. Chift automatically manages these limits to optimize performance and prevent interruptions. However, once the API rate limit is reached, Chift cannot bypass these limitations. See Microsoft’s operational limits documentation.

Limitations & specificities

Invoices

Status mapping: invoice statuses correspond as follows:

Chift	Business Central
Draft	Draft
Posted	Open
Paid	Paid

Direct to paid: depending on the vendor or customer payment configuration, an invoice can go straight to Paid when posted, skipping Open.For purchase invoices, this happens when the vendor’s payment method has a balancing account: Business Central then posts the payment together with the invoice. See Microsoft’s Settle purchase invoices promptly.

Chart of accounts & VAT

Detail accounts only: summary ledger accounts cannot be used in invoices or entries.One VAT posting group per request: all VAT codes in a request must belong to the same VAT posting group.First bank account: Chift cannot create the first bank account of a company. It needs an existing one to find the ledger account.The end user creates the first bank account manually in Business Central.VAT-exempt mode: Chift can post invoices and entries in VAT-exempt mode. The end user first completes the VAT-exempt invoicing setup in Business Central.You then pass one of two identifiers with the invoice data:

CHIFT_FREE_VAT_CODE: Chift omits the VAT code and lets Business Central’s Posting Group configuration resolve it. If set up correctly, it falls back to the 0% entry.
Your own VAT code: the identifier of the exact VAT Posting Group combination, if there are several exempt configurations.

Chift matches the identifier to the corresponding VAT Posting Setup entry. If nothing matches, invoice creation fails.

Payments & matching

Matching after a financial entry: matching only works immediately after the financial entry is created, while the batch is still unposted. Once the batch is posted, the standard flow can no longer match it.Instead, set the automated_matching_number field when creating the financial entry: no separate matching call is then needed.

Multi-folder

One company per connection: a connection covers a single Business Central company, chosen by the end user when connecting.

Coverage

Troubleshooting

Specific errors for Business Central:

Error Code	Error description	Resolution
ERROR_CONNECTOR_OUTDATED_EXTENSION	The extension is installed but the endpoint or the provided body/params requires the extension to be updated.	Update the extension through Business Central’s interface.
ERROR_ACCOUNT_NUMBER_CONFIGURATION	Ledger accounts need the “Gen. Prod. Posting Group” configured to be used in accounting documents.	Configure the “Gen. Prod. Posting Group” on the ledger account in Business Central.
ERROR_ACCOUNT_NUMBER_NOT_GOOD_SCOPE	Summary ledger accounts cannot be used in bookings/invoices in Business Central.	Use a detail (non-summary) ledger account.
ERROR_BUSINESSCENTRAL_NOSERIES_CONSUMED	The No. Series has been fully consumed and needs to be extended.	Update the No. Series settings in Business Central to extend the allowed range.
ERROR_CONNECTOR_CONFIGURATION	A deferral template must be set up to use deferral codes (start_date and end_date) in invoices.	Set up a deferral template in Business Central.
ERROR_CONNECTOR_MISSING_EXTENSION	The Business Central Chift extension is required but not installed or outdated.	Install or update the Chift extension for Business Central.
ERROR_INVALID_BODY	At least one input field of the body is invalid.	Verify the provided fields and values are correct for Business Central.
ERROR_MULTIPLE_VAT_REGIMES_USED	You can only use VAT codes from the same VAT posting group in Business Central.	Ensure all VAT codes in the request belong to the same VAT posting group.
ERROR_TAX_CODE_NOT_CONFIGURED	The VAT ledger accounts (payable/deductible) must be set up correctly in Business Central.	Configure the VAT payable and deductible ledger accounts on the tax code.
ERROR_NO_GL_ACCOUNT_CODE_FOUND	Cannot determine the ledger account number for the new bank account because no existing bank accounts exist for reference.	Create an initial bank account manually in Business Central first.
ERROR_CURRENCY_NOT_ALLOWED	The currency sent differs from the bank account’s currency (the company’s local currency when the account has none), for a bank statement or for entries in a journal balanced on that bank account.	Send the statement or entries in the currency of the bank account.
ERROR_INVALID_FIELD_FORMAT_STATEMENT_NUMBER	The bank statement number is longer than 20 characters.	Send an `external_bank_statement_id` of 20 characters or fewer.
ERROR_BANK_STATEMENT_ALREADY_EXISTS	A statement with this number is already open in a Payment Reconciliation Journal for this bank account.	Use a new statement number, or delete the open journal in Business Central and push again. A posted statement number cannot be reused.
ERROR_BANK_STATEMENT_OPENING_BALANCE_MISMATCH	The `opening_balance` sent differs from the bank account’s Balance Last Statement in Business Central.	Send the bank account’s Balance Last Statement, or leave `opening_balance` out.

​Introduction

​Activate Business Central

​Partner keys

Activate Business Central in your Chift account

​Connector settings

​Test Business Central

​Vendor fees

​Connect Business Central

Business Central setup guide for end users

​Chift extension for Business Central

​Bank transactions setup

​Rate limits

​Limitations & specificities

​Coverage

​Troubleshooting

​Specific errors for Business Central:

Introduction

Activate Business Central

Partner keys

Connector settings

Test Business Central

Vendor fees

Connect Business Central

Chift extension for Business Central

Bank transactions setup

Rate limits

Limitations & specificities

Coverage

Troubleshooting

Specific errors for Business Central: