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.
Update (2021/12/14): Using OAuth to connect Business Central APIs and Web Service in Postman
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/
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.
| Number | Name | Kind | url |
| 1 | entityDefinitions | EntitySet | entityDefinitions |
| 2 | companies | EntitySet | companies |
| 3 | subscriptions | EntitySet | subscriptions |
| 4 | items | EntitySet | items |
| 5 | unitsOfMeasure | EntitySet | unitsOfMeasure |
| 6 | pictures | EntitySet | pictures |
| 7 | defaultDimensions | EntitySet | defaultDimensions |
| 8 | itemVariants | EntitySet | itemVariants |
| 9 | customers | EntitySet | customers |
| 10 | customerFinancialDetails | EntitySet | customerFinancialDetails |
| 11 | agedAccountsReceivables | EntitySet | agedAccountsReceivables |
| 12 | vendors | EntitySet | vendors |
| 13 | agedAccountsPayables | EntitySet | agedAccountsPayables |
| 14 | companyInformation | EntitySet | companyInformation |
| 15 | salesInvoices | EntitySet | salesInvoices |
| 16 | salesInvoiceLines | EntitySet | salesInvoiceLines |
| 17 | dimensionSetLines | EntitySet | dimensionSetLines |
| 18 | pdfDocument | EntitySet | pdfDocument |
| 19 | attachments | EntitySet | attachments |
| 20 | customerPaymentJournals | EntitySet | customerPaymentJournals |
| 21 | customerPayments | EntitySet | customerPayments |
| 22 | accounts | EntitySet | accounts |
| 23 | taxGroups | EntitySet | taxGroups |
| 24 | journals | EntitySet | journals |
| 25 | journalLines | EntitySet | journalLines |
| 26 | employees | EntitySet | employees |
| 27 | timeRegistrationEntries | EntitySet | timeRegistrationEntries |
| 28 | generalLedgerEntries | EntitySet | generalLedgerEntries |
| 29 | currencies | EntitySet | currencies |
| 30 | paymentMethods | EntitySet | paymentMethods |
| 31 | dimensions | EntitySet | dimensions |
| 32 | dimensionValues | EntitySet | dimensionValues |
| 33 | paymentTerms | EntitySet | paymentTerms |
| 34 | shipmentMethods | EntitySet | shipmentMethods |
| 35 | itemCategories | EntitySet | itemCategories |
| 36 | cashFlowStatements | EntitySet | cashFlowStatements |
| 37 | countriesRegions | EntitySet | countriesRegions |
| 38 | salesOrders | EntitySet | salesOrders |
| 39 | salesOrderLines | EntitySet | salesOrderLines |
| 40 | retainedEarningsStatements | EntitySet | retainedEarningsStatements |
| 41 | balanceSheets | EntitySet | balanceSheets |
| 42 | trialBalances | EntitySet | trialBalances |
| 43 | incomeStatements | EntitySet | incomeStatements |
| 44 | taxAreas | EntitySet | taxAreas |
| 45 | salesQuotes | EntitySet | salesQuotes |
| 46 | salesQuoteLines | EntitySet | salesQuoteLines |
| 47 | salesCreditMemos | EntitySet | salesCreditMemos |
| 48 | salesCreditMemoLines | EntitySet | salesCreditMemoLines |
| 49 | purchaseInvoices | EntitySet | purchaseInvoices |
| 50 | purchaseInvoiceLines | EntitySet | purchaseInvoiceLines |
| 51 | projects | EntitySet | projects |
| 52 | bankAccounts | EntitySet | bankAccounts |
| 53 | customerSales | EntitySet | customerSales |
| 54 | vendorPurchases | EntitySet | vendorPurchases |
PS:
1. 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.
2. A simple way to view the list of all APIs
Basic operations
Verbs in API: GET, POST, PATCH, DELETE
| Method | Description | Example |
| GET | List collection | GET …/salesOrders |
| GET | Get member of the collection | GET …/salesOrders({id}) |
| POST | Create new sales order in the collection | POST …/salesOrders/ |
| PATCH | Update sales order | PATCH …/salesOrders({id}) |
| DELETE | Delete sales order | DELETE …/salesOrders({id}) |
| POST | Invoke operations/bound actions | POST …/salesInvoice({id})/Microsoft.NAV.post |
| POST | Execute multiple requests | POST …/$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 company from 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
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)
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
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrdersSales 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)
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): Please note that the single quotation marks below may be in Japanese font, please switch to English font when using.
| Operator | Description | Example |
| Comparison operators | ||
| eq | Equal | ?$filter=category eq ‘Expense’ |
| ne | Not equal | ?$filter=unitPrice ne 0 |
| gt | Greater than | ?$filter=unitPrice gt 1000 |
| ge | Greater than or equal | ?$filter=unitPrice ge 1000 |
| lt | Less than | ?$filter=unitPrice lt 1000 |
| le | Less than or equal | ?$filter=unitPrice le 1000 |
| Logical operators | ||
| and | Logical and | ?$filter=number ge ‘50000’ and number lt ‘60000’ |
| or | Logical or | ?$filter=category eq ‘Expense’ or category eq ‘Income’ |
| not | Logical negation | Not supported |
| Grouping | ||
| () | Precendence grouping | ?$filter=(category eq ‘Expense’ or category eq ‘Income’) and (number ge ‘40000’ and number lt ‘50000’) |
| Comparison operators | ||
| contains | Search for substring | ?$filter=contains(displayName, ‘red’) |
| endswith | Test if first string ends with second string | ?$filter=endswith(email,’contoso.com’) |
| startswith | Test if first string starts with second string | ?$filter=startswith(email,’aj’) |
| concat | Returns a string that appends the second paramter to the first | Not 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’
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
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
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
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
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
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
https://api.businesscentral.dynamics.com/v2.0/d8f36038-1f93-4543-affc-5dc92b6ee871/Sandbox03/api/v2.0/companies(6325c2d6-c92a-eb11-846e-000d3ac98e05)/salesOrders/$countPost
For example: Create a sales order object in Dynamics 365 Business Central.
1. Set Post request 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
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 Patch request 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)
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 Delete request 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)
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.
| OData | SOAP | |
| Sandbox | 300 req/min | 300 req/min |
| Production | 600 req/min | 600 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.
| OData | SOAP |
| 100 | 100 |
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.
| OData | SOAP |
| 00:08:00 | 00: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.
| OData | SOAP |
| 20,000 entities per page | 65,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
PS: Microsoft REST API Guidelines
Hope this will help.
Thanks for your reading.
ZHU
コメント