How to: Implement external integration with Microsoft Business Central

General info:

Now in Sapera is implemented internal integration with one of Microsoft Business Central provider: Inventio.It. This document is intended to propose aproach how similar integration may be implemented by external development team.

Basic information for all requests

HTTP word - POST

All requests should contain header Content-Type - application/json.

Authentication process to Sapera is described in followind document: How to: Integrate web shop with CRS platform | Authentication

Work with Get[Something]Page requests

In documentWork with Get[Something]Page requests is described how to fetch entities in paing way using requests like Get[Something]Page.

Financial data syncrhonization

In Sapera financial entries are created during booking of draft draft entrires. Each booking process is registered in system as BookingOperation entity. So algorithm of Sapera financial entries with Business Central may be following:

Periodically check for new booked Booking Operations. Each booking operation have Draft property which indicates to which Sapera draft booked draft entries of in scope of booking operation. In Sapera we have a mapping between Sapera drafts and Business Central Journals to decide to which Business Central journal need to be exported financial entries. Same map may be organized in external system or may be decided to export all entries to one specific journal.
Take financial entries for each booking operation in paged way to syncrhonize with BusinessCentral.
Make sure that actors mentioned in financial entries are registered in Business Central as customers or vendors;
Register financail entries in Business Central.

Get booking operations (paged)

Word: POST
URL: {host_url}/api/accounting/bookingOperation/getBookingOperationsPage
Minimal request:

{ 
   "sortInfo":[
   ],
   "offset":0,
   "count":page_size,
   "includeOverallEntryCount":true
}

Following optional filters are available and need to be mentioned:

[BookedDateFilter]- allows to filter operations by BookedAt date. This filter need to be used to retrieve booking operaations booked after previous syncrhonization run;
[OrganizationalUnitId] - allows to specify organizational unit which accounting metadata will be used to filter booking operations by accounting metadata. In case when OrganizationalUnitId is not specified, will be used Organizational unit to which user is logged in;

Get financial entries by booking operations (paged)

Word: POST
URL: {host_url}/api/accounting/bookingOperation/getBookingOperationEntriesPage
Minimal request:

{ 
   "bookingOperationId":{
    "value":booking_operation_id
   },
   "sortInfo":[
   ],
   "offset":0,
   "count":page_size,
   "includeOverallEntryCount":true
}

Syncrhonization of involved actors

Each financial entry in Sapera have EntryKind property. Possible values: Financial, Debtor and Creditor.

Each Debtor and Creditor financial entry have ActorId reference. Before export financial entries we need to be sure that involved actors are exported to BusinessCentral too because for these entries on export actor identifiers will be used as account numbers.

Customers are presented in BusinessCentral as Customers, Suppliers are presented as Vendors.

To syncrhonize customers, ActorInfos need to be resolved for actors mentioned in Debtor financial entries. In document How to create/update Actor | Get actor infos(paged) is described how to get actor infos. Each ActorInfo entity have Identifiers collection. For each actor need to be taken customer identifier from this collection and checked is Customer with same identifier presented in BusinessCentral. If not - Customer need to be registered in BusinessCentral using their API.

To syncrhonize suppliers, ActorInfos need to be resolved for actors mentioned in Creditor financial entries. Each ActorInfo entity have Identifiers collection. For each actor need to be taken supplier identifier from this colleciton and checked is Vendor with same identifier presented in BusinessCentral. If not - Vendor need to be registered in BusinessCentral using their API.

To get Sapera Actor data in order to compose api calls to register Customers/vendors in BusinessCentral may be used GetActorPage method with filter by ActorIds. It is described in following document: .

Note about export financial entries

Instead of our financial entry kind that presented in Sapera Business Central entries have AccountType with following options:

"Finanskonto" (Sapera invariant - EntryKind = Financial) - for account number is used number of FinancialAccount;
"Debitor" (Sapera invariant - EntryKind = Debtor) - for account number is used CustomerIdentifier of entry’s Actor;
"Creditor" (Sapera invariant - EntryKind = Creditor) - for account number is used SupplierIdentifier of entry’s Actor;

Stock values syncrhonization

In integration with implemented in Sapera syncrhonization of stock levels is not implemented. But stock levels fo products can be easyly fetched using Sapera API.

To do this following API method need to be used:

Word: POST
URL: {host_url}/api/inventory/Product/GetProductPage

GetProductPage method is described in detail in following document:

Following approach could be implemented:
Periodically with help of GetProductPage need to be fetched page entries of products modified after specifc date (for that should be used ModifiedAfter filter in Sapera product is concidered to be modified in case if any stock movement is peformed with it so if there any stock movements were after ModifiedAfter date, product will be in page result.)

In GetProductPage request need to be configured OrganizationalUnitPropertiesRequest in which need to be defined OrganizationalUnitIds (ids of organziational units for that stock counts are needed) and in PropertiesToLoad property need to be included ProductOrganizationalUnitPropertiesToLoad.Availability. Then in returned ProductPageEntry structures will be filled OrganizationalUnitProperties property where for each requested organizational unit will be record with stock count in property named Availability.

Then these stock counts may be syncrhonized with Business Central.