Standard API for Dynamics 365 Business Central SaaS (Get, Post, Patch, Delete and Basic query parameters – filter, orderby, select…)

Dynamics 365 Business Central

Hi, readers. Happy Thanksgiving to you and your family.
In today’s post we will discuss about API’s in Business Central.
With Dynamics 365 you can create Connect apps. Connect apps establishes a point-to-point connection between Dynamics 365 Business Central and a 3rd party solution or service and is typically created using standard REST API to interchange data. Any coding language capable of calling REST APIs can be used to develop your Connect app. For Example: You can use the API to get access to Items, Customers, Sales Orders and other information in Business Central, update sales orders, or view ledger entries etc.
So this time, I’ll just do some demos about sales orders, such as Get, Post, Patch and so on to make it easier to understand.
Let’s start.

Pre-requisites

1. Endpoints for the APIs: Direct tenant
With multiple environments (v2.0):
https://api.businesscentral.dynamics.com/v2.0/user domain name/environment name/api/v2.0

For Example: My test environment
Tenant ID (user domain name): d8f36038-1f93-4543-affc-5dc92b6ee871
Environment name: Sandbox03
Endpoints: https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/

2. Authentication: Basic authentication
Username and web service access key as password.
You can get web service access key from User Card.

Find out more about Endpoints for the APIs for Dynamics 365 Business Central On-Premises and Online from Microsoft Docs.

3. Test Tool: Postman
The Collaboration Platform for API Development
Download: https://www.postman.com/

Standard API and Basic operations

Standard API

The standard APIs are provided by Microsoft and we can use them out-of-box.

1. Set GET request and enter your Endpoint URL.
For Example:
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/

2. In Authorization tab, set type to Basic Auth, and enter your Username and web service access key as password.

3. Choose Send.

Then you can get the list of standard APIs.

Up to now, BC17.1 2020/11/27, there are a total of 54 standard APIs in Business Central.
Note: The upper and lower case letters in the URL must match exactly.

NumberNameKindurl
1entityDefinitionsEntitySetentityDefinitions
2companiesEntitySetcompanies
3subscriptionsEntitySetsubscriptions
4itemsEntitySetitems
5unitsOfMeasureEntitySetunitsOfMeasure
6picturesEntitySetpictures
7defaultDimensionsEntitySetdefaultDimensions
8itemVariantsEntitySetitemVariants
9customersEntitySetcustomers
10customerFinancialDetailsEntitySetcustomerFinancialDetails
11agedAccountsReceivablesEntitySetagedAccountsReceivables
12vendorsEntitySetvendors
13agedAccountsPayablesEntitySetagedAccountsPayables
14companyInformationEntitySetcompanyInformation
15salesInvoicesEntitySetsalesInvoices
16salesInvoiceLinesEntitySetsalesInvoiceLines
17dimensionSetLinesEntitySetdimensionSetLines
18pdfDocumentEntitySetpdfDocument
19attachmentsEntitySetattachments
20customerPaymentJournalsEntitySetcustomerPaymentJournals
21customerPaymentsEntitySetcustomerPayments
22accountsEntitySetaccounts
23taxGroupsEntitySettaxGroups
24journalsEntitySetjournals
25journalLinesEntitySetjournalLines
26employeesEntitySetemployees
27timeRegistrationEntriesEntitySettimeRegistrationEntries
28generalLedgerEntriesEntitySetgeneralLedgerEntries
29currenciesEntitySetcurrencies
30paymentMethodsEntitySetpaymentMethods
31dimensionsEntitySetdimensions
32dimensionValuesEntitySetdimensionValues
33paymentTermsEntitySetpaymentTerms
34shipmentMethodsEntitySetshipmentMethods
35itemCategoriesEntitySetitemCategories
36cashFlowStatementsEntitySetcashFlowStatements
37countriesRegionsEntitySetcountriesRegions
38salesOrdersEntitySetsalesOrders
39salesOrderLinesEntitySetsalesOrderLines
40retainedEarningsStatementsEntitySetretainedEarningsStatements
41balanceSheetsEntitySetbalanceSheets
42trialBalancesEntitySettrialBalances
43incomeStatementsEntitySetincomeStatements
44taxAreasEntitySettaxAreas
45salesQuotesEntitySetsalesQuotes
46salesQuoteLinesEntitySetsalesQuoteLines
47salesCreditMemosEntitySetsalesCreditMemos
48salesCreditMemoLinesEntitySetsalesCreditMemoLines
49purchaseInvoicesEntitySetpurchaseInvoices
50purchaseInvoiceLinesEntitySetpurchaseInvoiceLines
51projectsEntitySetprojects
52bankAccountsEntitySetbankAccounts
53customerSalesEntitySetcustomerSales
54vendorPurchasesEntitySetvendorPurchases

PS: You can find the list from Microsoft Docs Welcome to the API(v2.0) for Dynamics 365 Business Central

You can also search for pagetype = API in the standard source code to find them.

Basic operations

Verbs in API: GET, POST, PATCH, DELETE

MethodDescriptionExample
GETList collectionGET …/salesOrders
GETGet member of the collectionGET …/salesOrders({id})
POSTCreate new sales order in the collectionPOST …/salesOrders/
PATCHUpdate sales orderPATCH …/salesOrders({id})
DELETEDelete sales orderDELETE …/salesOrders({id})
POSTInvoke operations/bound actionsPOST …/salesInvoice({id})/Microsoft.NAV.post
POSTExecute multiple requestsPOST …/$batch

Get

Retrieve the properties and relationships of object for Dynamics 365 Business Central.

Get List collection

1. Get company list.
Find the API URL of companyfrom the table above. (You must specify which company you want to get the order from)

Enter your companies API URL.
For example: Your Endpoint + API URL
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies

Choose send, then you can get the company list.

In Business Central:

Get member of the collection

Enter your companies API URL with ID.
For example: Your Endpoint + API URL +(ID)
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)

PS:
1. Get Sales Order list in My Company 02:
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders

Sales Order list in Business Central.

2. Get only one Sales Order in My Company 02.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders(90ef32e7-262e-eb11-846e-000d3ac98e05)

$filter

Filters results (rows):

OperatorDescriptionExample
Comparison operators  
eq Equal?$filter=category eq ‘Expense’ 
ne Not equal?$filter=unitPrice ne 0
gtGreater than?$filter=unitPrice gt 1000
geGreater than or equal?$filter=unitPrice ge 1000
ltLess than?$filter=unitPrice lt 1000
leLess than or equal?$filter=unitPrice le 1000
Logical operators  
andLogical and?$filter=number ge ‘50000’ and number lt ‘60000’
orLogical or?$filter=category eq ‘Expense’ or category eq ‘Income’
notLogical negationNot supported
Grouping  
()Precendence grouping?$filter=(category eq ‘Expense’ or category eq ‘Income’) and (number ge ‘40000’ and number lt ‘50000’)
Comparison operators  
containsSearch for substring?$filter=contains(displayName, ‘red’)
endswithTest if first string ends with second string?$filter=endswith(email,’contoso.com’)
startswithTest if first string starts with second string?$filter=startswith(email,’aj’)
concatReturns a string that appends the second paramter to the firstNot supported

For example:
Get Sales Order list: Customer No. = 10000.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$filter=customerNumber eq ‘10000’

Note: The field name needs to refer to the name output below, not the name on the page.

$select

Filters properties (columns):

For example:
Get Sales Order list: only have fields, number, postingDate, customerNumber, customerName
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$select=number,postingDate,customerNumber,customerName

$orderby

Orders results:

For Example:
Get Sales Order list: sorting by customerNumber desc
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$orderby=customerNumber desc

$top

Sets the tops of results:

For example:
Get Sales Order list: top three orders.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$top=3

$skip

Skip a number of rows:

For example:
Get Sales Order list: skip 9 rows.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$skip=9

$expand

Retrieves related resources.

For example:
Get Sales Order list: with sales lines.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders?$expand=salesOrderLines

$count

Retrieves the total count of matching resources.

For example:
Get the total count of Sales Orders
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders/$count

Post

For example: Create a sales order object in Dynamics 365 Business Central.

1. Set Postrequest and enter your URL.
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03//api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders

2. Set key (Content-type) and value (application/json) in Headers.

3. Set order information in Body -> raw.

4. Choose Send. New sales order will be created.

Patch

For example: Update the properties of a sales orders object for Dynamics 365 Business Central.

1. Set Patchrequest and enter your URL. (You must specify which sales order you want update)
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03//api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders(2755a583-7830-eb11-846e-000d3ac98bc6)

2. Set key (Content-type) and value (application/json) like post, then add secomd key (If-Match) and value (*) in Headers.

3. Set the update information of the order in Body -> raw.

4. Choose Send. Then sales order will be updated.

Delete

For example: Delete a sales order object from Dynamics 365 Business Central.

1. Set Deleterequest and enter your URL. (You must specify which sales order you want delete)
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03//api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders(2755a583-7830-eb11-846e-000d3ac98bc6)

2. Choose Send. Then sales order will be deleted.

Note:
1. You can convert the request to the code of other languages in postman.

2. Current API Limits
API Rate limits: HTTP response code 429 – Too Many Requests is returned if limits are exceeded.

 ODataSOAP
Sandbox300 req/min300 req/min
Production600 req/min600 req/min

Request time out: HTTP response code 504 – Gateway Timeout is returned when a request exceeds 10-minutes execution time.

Maximum Connections: The maximum number of simultaneous OData or SOAP requests. HTTP response code 429 – Too Many Requests is returned if limits are exceeded.

ODataSOAP
100100

Operation Timeout: The maximum amount of time that allocated to a single OData or SOAP request. HTTP response code 408 – Request Timeout is returned if limits are exceeded.

ODataSOAP
00:08:0000:10:00

Request Size: The maximum size of the OData or SOAP request. HTTP response code 413: Request Entity Too Large is returned if limits are exceeded.

ODataSOAP
20,000 entities per page65,536 kilobytes

3. Error Codes

END

In this blog, I demonstrated the basic operation of the standard APIs.
You can find out more from Microsoft Docs: Welcome to the API(v2.0) for Dynamics 365 Business Central

Hope this will help.

Thanks for your reading.

ZHU

コメント

タイトルとURLをコピーしました