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 Integration Setup]

Behavior with this function activated

The API Collection is available and can be used.

Steps

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


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.


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	Yes, optional using attribute noSeries (if not then default noSeries). Also possible in Batch requests, including the optional Expand	Yes, only for header and if Status = Open. Add the following key-field to the URL: “No”	Optional, with customSalesOrderLines
SalesOrderLines (page 11295763)	Yes	No	Yes, only for header and if Status = Open and if there are no conflicts with reservations. Add the following key-fields to the URL: “Document No.", "Document Type", "Line No."	No
ReturnOrders (page 11295764)	Yes	Yes, optional using attribute noSeries (if not then default noSeries). Different ShipToAddresses are currently not supported.	Yes, only for header and if Status = Open. Add the following key-field to the URL: No”	Optional, with customReturnOrderLines
ReturnOrderLines (page 11295765)	Yes	No	Yes, only for header and if Status = Open and if there are no conflicts with reservations. Add the following key-fields to the URL: “Document No.", "Document Type", "Line No."	No
Customers (page 11295766)	Yes	Yes, optional using attribute noSeries (if not then default noSeries). Also possible in Batch requests, including the optional Expand	Yes, Add the following key-field to the URL: “No”	Optional, with ShipToAddresses, Contacts, CustomerGroupPrices
ShipToAddresses (page 11295767)	Yes	Yes	Yes, Add the following key-fields to the URL “CustomerNo”, “Code”	No
Items (page 11295768)	Yes	Yes	Yes, Add the following key-field to the URL: “No”	No
StockItem (page 11295769)	Yes	No	No	No
PriceListLine (using the New Sales Price experience) (page 11295770)	Yes	No	No	Optional, with CustomerPrices, CustomerGroupPrices
CustomerCreditLimit (page 11295771)	Yes	No	No	No
VatBusinessPostingGroups (page 11295772)	Yes	No	No	No
VatProdPostingGroups (page 11295773)	Yes	No	No	No
VatPostSetup (page 11295774)	Yes	No	No	No
Contacts (page 11295775)	Yes	Ja	Yes, Add the following key-fields to the URL: “No”	No
CustomerPrices (using the New Sales Price experience) (page 11295776)	Yes	No	No	No
CustomerGroupPrices (using the New Sales Price experience) (page 11295777)	Yes	No	No	No
Vendors (page 11295778)	Yes	Yes	Yes , Add the following key-fields to the URL: “No”	No
CountryRegions (page 11295579)	Yes	Yes	Yes, Add the following key-fields to the URL “Code”	No
SalespersonPurchasers (page 11295780)	Yes	Yes	Yes, Add the following key-fields to the URL: “Code”	No
ItemCategories (page 11295781)	Yes	Yes	Yes,, Add the following key-fields to the URL: “Code”	No
PostedSalesInvoices (page 11295782)	Yes	No	No	No
PostedSalesInvoiceLines (page 11295783)	Yes	No	No	No
PostedSalesCreditMemos (page 11295784)	Yes	No	No	No
PostedSalesCreditMemoLines (page 11295785)	Yes	No	No	No
PurchaseOrders (page 11295786)	Yes	Yes	Yes, only for header and if Status = Open. Add the following key-field to the URL: “No”	Optional, with customPurchaseOrderLines
PurchaseOrderLines (page 11295787)	Yes	No	Yes, only for header and if Status = Open and if there are no conflicts with reservations. Add the following key-fields to the URL: “Document No.", "Document Type", "Line No."	No

Points of Attention

When using the API, please take the following points into account

Info

Updates (“PATCH requests”) require the inclusion of 1 or more key fields in the URL, so that BC can find the correct record to update. See the Postman project for examples;
When performing an Update (Patch), an extra Header should always be added. See also the examples in the Postman project;
- Key: “If-Match”
- Value: *
Sales price list lines are based on the tables used by BC’s “New sales pricing experience” More information at 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

View file

name	BriteBlue Wholesale365 Integration API Collection.postman_collection.json

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

Open Postman and Import the downloaded Postman collection


Import the example Postman collection

Select the top level of the Postman collection, name BriteBlue Wholesale365 Integration API Collection
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 ID (not the Name)
  1. Use the BC Page “Companies” to find the ID of your Company)


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.


Retrieve Access Token

Click Use token


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!


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 Integration 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
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, indien Status = Open en indien dit geen conflicten oplevert met reserveringen. 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) Afwijkende ShipToAddresses worden niet ondersteund	Ja, alleen voor header en indien Status = Open en indien dit geen conflicten oplevert met reserveringen. Voorzie de URL van het volgende key-field: “No”	Optioneel, met customReturnOrderLines
ReturnOrderLines (page 11295765) Verkoopretourorderregels	Ja	Nee	Ja, 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 dit geen conflicten oplevert met reserveringen 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-

Testen van API’s met behulp van Postman

Info
Postman is een API platform voor het bouwen en gebruiken van API's. Je kunt gratis aan de slag met Postman. BriteBlue is niet gelieerd aan Postman of een van haar merken.

Postman instellen en een OData GET-verzoek uitvoeren

Aan de slag met Postman
1. Dit kan de desktopapplicatie van Postman zijn: https://www.postman.com/downloads/
2. Of de browserinterface van Postman: https://go.postman.co/
Maak een account aan bij Postman: https://identity.getpostman.com/signup

Note
Hoewel het niet noodzakelijk is om een account aan te maken om Postman te gebruiken, raden we dit aan, zodat er automatisch een back-up van je Postman Project gemaakt wordt in de Postman Cloud.

Download dit voorbeeld van een Postman-collectie:

Panel

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

View file

name	BriteBlue Wholesale365 Integration API Collection.postman_collection.json

Tip
Deze Postman-collectie bevat voorbeelden voor alle geïmplementeerde request typen!

Open Postman en importeer de gedownloade Postman-collectie


Importeer de voorbeeld-Postman-collectie

Selecteer het hoogste niveau van de Postman-collectie: BriteBlue Wholesale365 Integration API Collection.
Selecteer tabblad Variables en bewerk de variabelen in de kolommen “Initial value” en “Current value”
1. Entra_Tenant_ID = Uw Microsoft Entra Tenant-ID (hint: deze kan worden gekopieerd van uw BC-URL)
2. Client_ID = De Client-ID zoals gemaakt tijdens Register a Dynamics 365 Business Central Application in Azure
3. Client_Secret = Het Client Secret zoals gemaakt tijdens Register a Dynamics 365 Business Central Application in Azure
4. BC_Environment = De naam van de BC-omgeving (hint: deze kan worden gekopieerd van uw BC-URL)
5. BC_Company = De ID van het bedrijf binnen de BC-omgeving (niet de naam)
  1. Gebruik de pagina “Bedrijven” om de ID te vinden van je BC Bedrijf


Gebruik de pagina “Bedrijven” om de ID te vinden van je BC Bedrijf


Pas de variabelen aan naar die van je BC-omgeving

Selecteer tab Authorization
Scroll naar beneden en selecteer Get New Access Token

Info
Business Central Tokens vervallen na 60 minuten / 1 uur. Activeer Auto-refresh Token om de Token automatisch te vernieuwen.


Opvragen van een Access Token

Klik op Use token


Zorg ervoor dat je Use Token selecteert om het token toe te passen

Open het request GetItems
Klik Send. Het kan een aantal seconden duren totdat Business Central reageert en Postman het ontvangen resultaat “Pretty printed” heeft gemaakt.

Tip
Gefeliciteerd, je hebt zojuist succesvol gegevens opgehaald uit je Business Central-omgeving!


Resultaat van het GET-request GetItems

Page Comparison

Versions Compared

Old Version 16

New Version 17

Key

How to Activate and configure

Behavior with this function activated

Steps

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)

(using the New Sales Price experience)

(page 11295770)

(page 11295771)

(page 11295772)

(page 11295773)

(page 11295774)

(page 11295775)

(using the New Sales Price experience) (page 11295776)

(using the New Sales Price experience) (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

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)

(page 11295786)