Page Comparison

English

(#6372) The Wholesale365 API Collection makes it easy to integrate other SaaS applications with Business Central. For example, for the integration with a webshop, carriers or fulfillment partners.

The API Collection consists of rich JSON APIs for, among other things, retrieving ("GET") data from BC. Not only master data such as customers, items and vendors, but also price lists and sales orders. It is also possible to update ("PATCH") existing BC data, such as customers and contacts. and to enter new data ("POST"). Think for example of "posting" sales orders.

Panel

panelIconId	atlassian-note
panelIcon	:note:
bgColor	#4C9AFF

Part of the Wholesale365 App “Integration”

How to Activate and configure

Activate this function using the page [Wholesale365 Setup]

Behavior with this function activated

The API Collection is available and can be used.

Stappen

This article describes the following steps to help you get started using the API Collection:

Preparations

Create an App registration on https://portal.azure.com
Add a Microsoft Entra application in Business Central

Info
For a step-by-step guide on how to create an App registration, add an Entra application and test it, please visit Integrate Dynamics 365 Business Central using OAuth 2.0

Add at least the following User Permission Sets to the Microsoft Entra application card:
1. BBS_LICMNGUSERPERM
2. BBS_PROPACKPERMUSER
3. BBS_WHOLESALE_USER

Image Added
Adding User Permission Sets to the Microsoft Entra Application Map

Next step is to create User Settings for the Microsoft Entra application:
1. Open the User Settings page.
2. Add a new row for the Entra user. Enter the name of the Entra user manually (BC does not let you search the list of Entra users by default).
3. If necessary, choose a “Booking allowed from” and “Booking allowed until” date, if you do not want the API to book outside that date.
4. Link the User ID to a “Salesperson/Purchaser”. This makes it easier to recognize within BC which documents are created/changed by the API user.

Image Added
User settings for the Entra user

Description of available APIs

The table below shows the capabilities for each of the available APIs.

Info

Advice:

Get requests support oData filter expressions on almost all fields returned by a Get request. For more information on using oData filter expressions, see https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/use-filter-expressions-in-odata-uris
A number of APIs can be “expanded” so that a complete document can be created in BC with a single GET request.
- This is implemented in the APIs for SalesOrders, ReturnOrders, Customers, PriceListLines and PurchaseOrders

API	Get	Post	Update (Patch)	Expand
SalesOrders (page 11295762)	Yes	Ja, optioneel met attribuut noSeries (anders default noSeries). Ook mogelijk in Batch, incl. optionele Expand	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customSalesOrderLines
SalesOrderLines (page 11295763)	Yes	Nee	Ja, indien Status = Open. Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee
ReturnOrders (page 11295764)	Yes	Ja, optioneel met attribuut noSeries (anders default noSeries)	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customReturnOrderLines
ReturnOrderLines (page 11295765)	Yes	Nee	Ja, indien Status = Open. Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee
Customers (page 11295766)	Yes	Ja, optioneel met Expand. Ook mogelijk in Batch, incl. optionele Expand	Ja, voorzie de URL van het volgende key-field: “No”	Optioneel, met ShipToAddresses, Contacts, CustomerGroupPrices
ShipToAddresses (page 11295767)	Yes	Yes	Ja, voorzie de URL van de volgende key-fields: “CustomerNo”, “Code”	Nee
Items (page 11295768)	Yes	Yes	Ja, voorzie de URL van het volgende key-field: “No”	Nee
StockItem (page 11295769)	Yes	Nee	Nee	Nee
PriceListLine (o.b.v. nieuwe verkoopprijservaring) (page 11295770)	Yes	Nee	Nee	Optioneel, met CustomerPrices, CustomerGroupPrices
CustomerCreditLimit (page 11295771)	Yes	Nee	Nee	Nee
VatBusinessPostingGroups (page 11295772)	Yes	Nee	Nee	Nee
VatProdPostingGroups (page 11295773)	Yes	Nee	Nee	Nee
VatPostSetup (page 11295774)	Yes	Nee	Nee	Nee
Contacts (page 11295775)	Yes	Ja	Ja, voorzie de URL van het volgende key-field: “No”	Nee
CustomerPrices (o.b.v. nieuwe verkoopprijservaring) (page 11295776)	Yes	Nee	Nee	Nee
CustomerGroupPrices (o.b.v. nieuwe verkoopprijservaring) (page 11295777)	Ja	Nee	Nee	Nee
Vendors (page 11295778)	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “No”	Nee
CountryRegions (page 11295579)	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
SalespersonPurchasers (page 11295780)	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
ItemCategories (page 11295781)	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
PostedSalesInvoices (page 11295782)	Ja	Nee	Nee	Nee
PostedSalesInvoiceLines (page 11295783)	Ja	Nee	Nee	Nee
PostedSalesCreditMemos (page 11295784)	Ja	Nee	Nee	Nee
PostedSalesCreditMemoLines (page 11295785)	Ja	Nee	Nee	Nee
PurchaseOrders (page 11295786)	Ja	Ja	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customPurchaseOrderLines
PurchaseOrderLines (page 11295787)	Ja	Nee	Ja, indien Status = Open en indien reserveringen dit toelaten Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee

Points of Attention

Example requests

xHoudt bij gebruik van de API rekening met de volgende aandachtspunten

Info

Updates (“PATCH-requests”) verlangen het meegeven van 1 of meerdere key-fields in de URL, zodat BC het juiste record kan vinden om te updaten. Kijk voor voorbeelden in het Postman project;
Bij het uitvoeren van een Update (Patch), dient er altijd een extra Header toegevoegd te worden. Zie ook de voorbeelden in het Postman-project;
- Key: “If-Match”
- Value: *
Verkoopprijslijstregels zijn gebaseerd op de tabellen die gebruikt worden door BC’s “Nieuwe verkoopprijservaring” Meer informatie op https://learn.microsoft.com/en-us/dynamics365-release-plan/2020wave2/smb/dynamics365-business-central/use-new-sales-pricing-experience-

Test the API’s using Postman

Info
Postman is an API platform for building and using APIs. You can get started for free with Postman. BriteBlue is not affiliated with Postman or any of its brands.

Set up Postman and perform an OData GET request

Get started with Postman
1. This can either be the desktop application of Postman: https://www.postman.com/downloads/
2. Or the browser interface of Postman: https://go.postman.co/
Create an account with Postman: https://identity.getpostman.com/signup

Note
While it's not necessary to create an account to use Postman, we encourage it so you can backup your work automatically to the Postman Cloud.

Download this example Postman collection:

Panel

panelIconId	1f4c1
panelIcon	:file_folder:
panelIconText	📁
bgColor	#F4F5F7

Tip
This Postman collection contains examples for all implemented request types!

Open Postman and Import the downloaded Postman collection

Image Added
Import the example Postman collection

Select the top level of the Postman collection, name BriteBlue Postman Example
Select tab Variables and edit the Variables in columns “Initial value” and “Current value”
1. Entra_Tenant_ID = Your Microsoft Entra Tenant ID (hint: this can be copied from your BC URL)
2. Client_ID = The Client ID as created during Register a Dynamics 365 Business Central Application in Azure
3. Client_Secret = The Client Secret as created during Register a Dynamics 365 Business Central Application in Azure
4. BC_Environment = The name of the BC Environment in which you’ve added the webservice earlier (hint: this can be copied from your BC URL)
5. BC_Company = Your BC Company name (hint: this can be copied from your BC URL)

Image Added
Adjust the variables to those of your BC environment

Select tab Authorization
Scroll down and select Get New Access Token

Info
Business Central Tokens expire after 60 minutes / 1 hour. Image Added

Image Added
Retrieve Access Token

Click Use token

Image Added
Make sure to select Use Token to apply the token

Open request GetItems
Click Send. It may take a couple of seconds before Business Central responds and Postman has “Pretty printed” the result

Tip
Congratulations, you’ve just succesfully retrieved data from your Business Central environment!

Image Added
Result from the GET-request GetItems

Dutch

(#6372) Door middel van de Wholesale365 API Collection wordt het eenvoudig om andere SaaS applicaties te integreren met Business Central. Bijvoorbeeld voor de integratie met een webshop, vervoerders of fullfilment partners.

De API Collection bestaat uit JSON API’s voor onder andere het ophalen (“GET”) van data uit BC. Niet alleen stamgegevens als klanten, artikelen en leveranciers maar bijvoorbeeld ook prijslijsten en verkooporders. Ook is het mogelijk om bestaande BC data bij te werken (“PATCH”), zoals klanten en contacten. en om nieuwe data in te voeren (“POST”). Denk bijvoorbeeld aan het “inschieten” van verkooporders.

Panel

panelIconId	atlassian-note
panelIcon	:note:
bgColor	#4C9AFF

Onderdeel van de Wholesale365 App “Integration”

Activeren en Configureren

Activeer deze functie via de pagina [Wholesale 365 Setup]. Meer informatie: Wholesale365 Setup - Order To Cash

Gedrag met deze functie geactiveerd

De API Collection is beschikbaar en kan gebruikt worden.

Stappen

In dit artikel worden de volgende stappen beschreven om je op weg te helpen met het gebruiken van de API Collection:

Voorbereiding

Creëer een App registratie op https://portal.azure.com
Voeg een Microsoft Entra-toepassing toe in Business Central

Info
Kijk voor een stap-voor-stap handleiding voor het creëren van een App registratie, het toevoegen van een Entra-toepassing én het testen hiervan op Integrate Dynamics 365 Business Central using OAuth 2.0

Voeg minimaal de volgende Gebruikersmachtigingensets toe aan de Microsoft Entra-toepassingskaart:
1. BBS_LICMNGUSERPERM
2. BBS_PROPACKPERMUSER
3. BBS_WHOLESALE_USER


Gebruikersmachtigingensets toevoegen aan de Microsoft Entra-toepassingskaart

Volgende stap is het aanmaken van Gebruikersinstellingen voor de Microsoft Entra-toepassing:
1. Open de pagina Gebruikersinstellingen.
2. Voeg een nieuwe rij toe voor de Entra-gebruiker. Type hierbij de naam van de Entra-gebruiker handmatig in (BC laat je standaard niet zoeken in de lijst met Entra-gebruikers).
3. Kies eventueel een “Boeken toegest. vanaf” en “Boeken toegest. tot” datum, wanneer het niet wenselijk is om de API buiten die datum te laten boeken.
4. Koppel de Gebruikers-ID aan een “Verkoper/Inkoper”. Hierdoor is het makkelijker te herkennen binnen BC wat de door de API-gebruiker aangemaakte / gewijzigde documenten zijn.


Gebruikersinstellingen voor de Entra-gebruiker

Beschrijving beschikbare API’s

In onderstaande tabel worden de mogelijkheden voor elk van de beschikbare API’s weergegeven.

Info

Tips:

Get-requests ondersteunen oData filter expressies op vrijwel alle velden die geretourneerd worden door een Get-request. Kijk voor meer informatie over het gebruik van oData filter expressies op https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/webservices/use-filter-expressions-in-odata-uris

Patch requests: Gebruik No in de URL

If-Match toevoegen bij Patch

patch doen met welk veld? (welke key-fields)

expand mogelijk op

Een aantal API’s kunnen “expand” worden, zodat er met één GET-request een compleet document aangemaakt kan worden in BC.
- Dit is geïmplementeerd in de API’s voor SalesOrders, ReturnOrders, Customers, PriceListLines en PurchaseOrders

API	Get	Post	Update (Patch)	Expand
SalesOrders (page 11295762) Verkooporders	Ja	Ja, optioneel met attribuut noSeries (anders default noSeries). Ook mogelijk in Batch, incl. optionele Expand	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customSalesOrderLines
SalesOrderLines (page 11295763) Verkoopregels	Ja	Nee	Ja, voorzie indien Status = Open. Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee
ReturnOrders (page 11295764) Verkoopretourorders	Ja	Ja, optioneel met attribuut noSeries (anders default noSeries)	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customReturnOrderLines
ReturnOrderLines (page 11295765) Verkoopretourorderregels	Ja	Nee	Ja, voorzie indien Status = Open. Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee
Customers (page 11295766) Klanten	Ja	Ja, optioneel met Expand. Ook mogelijk in Batch, incl. optionele Expand	Ja, voorzie de URL van het volgende key-field: “No”	Optioneel, met ShipToAddresses, Contacts, CustomerGroupPrices
ShipToAddresses (page 11295767) Verzendadressen	Ja	Ja	Ja, voorzie de URL van de volgende key-fields: “CustomerNo”, “Code”	Nee
Items (page 11295768) Artikelen	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “No”	Nee
StockItem (page 11295769) Voorraad Artikelen	Ja	Nee	Nee	Nee
PriceListLine (o.b.v. nieuwe verkoopprijservaring) (page 11295770) Verkoopprijslijstregels	Ja	Nee	Nee	Optioneel, met CustomerPrices, CustomerGroupPrices
CustomerCreditLimit (page 11295771) Klant kredietlimieten	Ja	Nee	Nee	Nee
VatBusinessPostingGroups (page 11295772) Btw-bedrijfsboekingsgroepen	Ja	Nee	Nee	Nee
VatProdPostingGroups (page 11295773) Btw-productboekingsgroepen	Ja	Nee	Nee	Nee
VatPostSetup (page 11295774) Btw-boekingsinstellingen	Ja	Nee	Nee	Nee
Contacts (page 11295775) Contacten	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “No”	Nee
CustomerPrices (o.b.v. nieuwe verkoopprijservaring) (page 11295776) Klantprijzen	Ja	Nee	Nee	Nee
CustomerGroupPrices (o.b.v. nieuwe verkoopprijservaring) (page 11295777) Klantengroepprijzen	Ja	Nee	Nee	Nee
Vendors (page 11295778) Leveranciers	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “No”	Nee
CountryRegions (page 11295579) Landen / Regio’s	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
SalespersonPurchasers (page 11295780) Verkopers / Inkopers	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
ItemCategories (page 11295781) Artikelcategorieën	Ja	Ja	Ja, voorzie de URL van het volgende key-field: “Code”	Nee
PostedSalesInvoices (page 11295782) Geboekte Verkoopfacturen	Ja	Nee	Nee	Nee
PostedSalesInvoiceLines (page 11295783) Geboekte Verkoopfactuurregels	Ja	Nee	Nee	Nee
PostedSalesCreditMemos (page 11295784) Geboekte Verkoopcreditnotas	Ja	Nee	Nee	Nee
PostedSalesCreditMemoLines (page 11295785) Geboekte Verkoopcreditnotaregels	Ja	Nee	Nee	Nee
PurchaseOrders (page 11295786) Inkooporders	Ja	Ja	Ja, alleen voor header en indien Status = Open. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customPurchaseOrderLines
PurchaseOrderLines (page 11295787) Inkooporderregels	Ja	Nee	Ja, indien Status = Open en indien reserveringen dit toelaten Voorzie de URL van de volgende key-fields: “Document No.", "Document Type", "Line No."	Nee

Aandachtspunten

Houdt bij gebruik van de API rekening met de volgende aandachtspunten

Info

Updates (“PATCH-requests”) verlangen het meegeven van 1 of meerdere key-fields in de URL, zodat BC het juiste record kan vinden om te updaten. Kijk voor voorbeelden in het Postman project;
Bij het uitvoeren van een Update (Patch), dient er altijd een extra Header toegevoegd te worden. Zie ook de voorbeelden in het Postman-project;
- Key: “If-Match”
- Value: *
Verkoopprijslijstregels zijn gebaseerd op de tabellen die gebruikt worden door BC’s “Nieuwe verkoopprijservaring” Meer informatie op https://learn.microsoft.com/en-us/dynamics365-release-plan/2020wave2/smb/dynamics365-business-central/use-new-sales-pricing-experience-

Page Comparison

Versions Compared

Old Version 12

New Version 13

Key

How to Activate and configure

Behavior with this function activated

Stappen

Preparations

Adding User Permission Sets to the Microsoft Entra Application Map

User settings for the Entra user

Description of available APIs

(page 11295762)

(page 11295763)

(page 11295764)

(page 11295765)

(page 11295766)

(page 11295767)

(page 11295768)

(page 11295769)

(o.b.v. nieuwe verkoopprijservaring)

(page 11295770)

(page 11295771)

(page 11295772)

(page 11295773)

(page 11295774)

(page 11295775)

(o.b.v. nieuwe verkoopprijservaring) (page 11295776)

(o.b.v. nieuwe verkoopprijservaring) (page 11295777)

(page 11295778)

(page 11295579)

(page 11295780)

(page 11295781)

(page 11295782)

(page 11295783)

(page 11295784)

(page 11295785)

(page 11295786)

(page 11295787)

Points of Attention

Example requests

Test the API’s using Postman

Set up Postman and perform an OData GET request

Import the example Postman collection

Adjust the variables to those of your BC environment

Retrieve Access Token

Make sure to select Use Token to apply the token

Result from the GET-request GetItems

Activeren en Configureren

Gedrag met deze functie geactiveerd

Stappen

Voorbereiding

Gebruikersmachtigingensets toevoegen aan de Microsoft Entra-toepassingskaart

Gebruikersinstellingen voor de Entra-gebruiker

Beschrijving beschikbare API’s

(page 11295762)

(page 11295763)

(page 11295764)

(page 11295765)

(page 11295766)

(page 11295767)

(page 11295768)

(page 11295769)

(o.b.v. nieuwe verkoopprijservaring)

(page 11295770)

(page 11295771)

(page 11295772)

(page 11295773)

(page 11295774)

(page 11295775)

(o.b.v. nieuwe verkoopprijservaring) (page 11295776)

(o.b.v. nieuwe verkoopprijservaring) (page 11295777)

(page 11295778)

(page 11295579)

(page 11295780)

(page 11295781)

(page 11295782)

(page 11295783)

(page 11295784)

(page 11295785)