Business Central API (REST / ODATA Übersicht)

Das Tolle an Business Central ist die hochgradige Flexibilität, die man mit Business Central APIs erreichen kann. Ohne zu stark ins Detail zu gehen, möchte ich Ihnen einen Kurzüberblick geben. Man könnte ganz gewiss ein ganzes Buch über die API von Business Central schreiben – das wurde auch schon getan. Ich verrate Ihnen welches Buch ein umfassendes Kompendium für die API von BC ist am Ende des Artikels.

💡

APIs, kurz für Application Programming Interface, sind Mechanismen, die die Kommunikation zwischen zwei Softwarekomponenten über definierte Protokolle und Definitionen ermöglichen. Zum Beispiel bezieht die Wetter-App auf deinem Smartphone tägliche Wetterdaten von einem Software-System des Wetterdienstes. Diese App kommuniziert über APIs mit dem System, um dir die aktuellen Wetterinformationen auf deinem Gerät anzuzeigen.

Standard Business Central API

Microsoft hat bereits im Standard einige Business Cases abgedeckt und liefert eine Vielzahl an APIs mit seiner Software aus, die von Entwicklern genutzt werden können.

Zu den insgesamt 92 Standard Endpunkten der Schnittstelle zählen:

Liste der Standard APIs (ausklappbar)

1. Accounting Period
2. Account
3. Aged Accounts Payable
4. Aged Accounts Receivable
5. Apply Vendor Entry
6. Attachment
7. Automation Company
8. Tenant Config. Package File
9. Configuration Package
10. Extension Deployment Status
11. Extension Upload
12. Extension
13. Permission Set
14. Profile
15. Scheduled Job
16. Security Group Member
17. Security Group
18. User Permission
19. User
20. Balance Sheet
21. Bank Account
22. Cash Flow Statement
23. Company Information
24. Contact
25. Contact Information
26. Countries Region
27. Currency
28. Currency Exchange Rate
29. Customer Contact
30. Customer Financial Detail
31. Customer Payment Journal
32. Customer Return Reason
33. Customer Payment
34. Customer Sale
35. Customer
36. Default Dimension
37. Dimension Set Line
38. Dimension Value
39. Dimension
40. Dispute Status
41. Document Attachment
42. Employee
43. Fixed Asset Location
44. Fixed Asset
45. General Ledger Entry
46. General Ledger Setup
47. General Product Posting Group
48. Income Statement
49. Inventory Posting Group
50. Item Category
51. Item Ledger Entry
52. Item Variant
53. Item
54. Project
55. Journal Line
56. Journal
57. Location
58. Opportunity
59. PDF Document
60. Payment Method
61. Payment Term
62. Picture
63. Report Label
64. Purchase Credit Memo Line
65. Purchase Receipt Line
66. Purchase Credit Memo
67. Purchase Invoice Line
68. Purchase Invoice
69. Purchase Order Line
70. Purchase Order
71. Purchase Receipt
72. Retained Earnings Statement
73. Sales Credit Memo Line
74. Sales Credit Memo
75. Sales Invoice Line
76. Sales Invoice
77. Sales Order Line
78. Sales Order
79. Sales Quote Line
80. Sales Quote
81. Sales Shipment Line
82. Sales Shipment
83. Shipment Method
84. Tax Area
85. Tax Group
86. Time Registration Entry
87. Trial Balance
88. Unit Of Measure
89. Vendor Payment Journal
90. Vendor Payment
91. Vendor Purchase
92. Vendor

Alleine mit den Standard-APIs würden sich annähernd 100% der Tätigkeiten eines Endanwenders in BC über Schnittstellen automatisieren lassen (inklusive Buchen von Aufträgen, Rechnungen, Eingangsrechnungen, Anlegen von Kunden und Lieferanten, …). Das ist sehr beachtlich – vor allem im Vergleich zu anderen ERP-Systemen.

Was ist GET, DELETE, POST und PATCH?

Es gibt 4 Methoden die erlaubt sind: GET, DELETE, POST und PATCH. Die REST-Schnittstelle von Business Central folgt damit dem fundamentalen CRUD-Prinzip (Create Read Update Delete).
Die Schnittstellen arbeiten mit JSON-Nachrichten. JSON kann man als Nachfolger von XML betrachten. Die Struktur ist jedoch weniger komplex. Mittlerweile gibt es so gut wie keine Schnittstellen mehr, die XML unterstützen – und wenn, dann ist es eine Frage der Zeit bis diese durch JSON ersetzt wird.

Beispiel JSON für die Item (deutsch: Artikel) Schnittstelle in Business Central:

{
    "id": "GUID",
    "number": "string",
    "displayName": "string",
    "displayName2": "string",
    "type": "NAV.itemType",
    "itemCategoryId": "GUID",
    "itemCategoryCode": "string",
    "blocked": "boolean",
    "gtin": "string",
    "inventory": "decimal",
    "unitPrice": "decimal",
    "priceIncludesTax": "boolean",
    "unitCost": "decimal",
    "taxGroupId": "GUID",
    "taxGroupCode": "string",
    "baseUnitOfMeasureId": "GUID",
    "baseUnitOfMeasureCode": "string",
    "generalProductPostingGroupId": "GUID",
    "generalProductPostingGroupCode": "string",
    "inventoryPostingGroupId": "GUID",
    "inventoryPostingGroupCode": "string",
    "lastModifiedDateTime": "datetime"
}

Die Endpunkte – also die URL – für den Zugriff auf eine Standard-Schnittstelle ist hier definiert: Endpoints for the APIs for Microsoft Dynamics 365 Business Central – Business Central | Microsoft Learn

Und für interessierte findet sich hier der Code der API: ALAppExtensions/Apps/W1/APIV2/app/src/pages at main · microsoft/ALAppExtensions · GitHub

Webdienste (Eigene Business Central API erstellen)

Sollte bei den 92 Standard-Schnittstellen nicht die richtige dabei sein, besteht noch die Möglichkeit eine eigene API über die Benutzeroberfläche von Business Central zu erstellen. Wie das funktioniert, erfährst du im nachfolgenden Abschnitt.

Für unser Beispiel habe ich mir überlegt eine Schnittstelle über die angelegten Mitarbeiter (z.B. für ein externe Personalbuchhaltungssoftware) einzurichten. Hierzu habe ich mir im Vorfeld die Page Id der Mitarbeiter-Liste herausgesucht. Das ist ganz einfach: Die Page Id steht in der URL (also in der Adresszeile) von Business Central.

Suche in der Adresszeile einfach nach &page= oder ?page=. Die Zahl, die hinter dem Gleichheitszeichen kommt, ist die Page Id. In unserem Beispiel also die Page Id 5201.

Probier‘ es einfach mal aus – du wirst sehen, dass du auf der Mitarbeiter-Liste landest, wenn Du auf folgenden Link klickst: https://businesscentral.dynamics.com/?page=5201

Webdienst anlegen

1. Zuerst musst du dich in Business Central einloggen.
2. Klicke nun auf das Lupen-Symbol oben rechts in Business Central:

3. Gebe nun den Begriff „Webdienste“ in das Suchfeld ein:

4. Es öffnet sich nun eine Übersicht über alle verfügbaren Webdienste. Nicht enthalten in dieser Liste sind die 92 Schnittstellen-Endpunkte. Bei den Webdiensten handelt es sich um ODATA und nicht REST Schnittstellen. Inhaltlich arbeiten beide mit JSON; ODATA ist allerdings neuer – dafür aber noch nicht so weit verbreitet.

5. Mit dem Klick auf den Button „Neu“ legen wir einen neuen Eintrag an.

Videoanleitung

In der Spalte Objektart wählen wir Seite aus.
In der Spalte Objekt-ID geben wir die Page Id ein. In unserem Beispiel also 5201.
Im Hintergrund wird Business Central nun den Webdienst anlegen. Das kann einige Minuten dauern – verlasse die Seite nicht!
In der Spalte Servicename geben wir nun einen Namen ein, z.B. employee.
In der Spalte Veröffentlicht muss der Haken aktiviert werden, andernfalls ist die Schnittstelle nicht erreichbar.
Den Endpunkt für die soeben angelegte Schnittstelle findest Du in der Spalte OData V4-URL.

Der Haken beim Webdienst..

Toll gemacht! Du hast soeben eigenständig einen eigenen API Endpunkt in Business Central angelegt. Du kannst nun Mitarbeiter Erstellen (Create), Anzeigen (Read) und Löschen (Delete). Moment hier fehlt ein U 🤔. Business Central APIs sollen doch angeblich CRUD, also Create Read Update Delete können.
Grundsätzlich ist das auch richtig. Bei den Webdiensten gibt es aber einen kleinen Haken: Man ist grundsätzlich daran gebunden, was Microsoft – oder der Extension-Entwickler für diese Page (in unserem Fall Page 5201) vorgesehen hat.
Dann werfen wir doch mal einen Blick in den Code dieser Page:

Hier stellen wir fest, dass Microsoft für diese Liste die Eigenschaft Editable auf false gesetzt hat, also bearbeitbar = nein. Das ist der Tatsache geschuldet, dass die Bearbeitung auf der Page vom Typ Liste generell eher unpraktikabel ist.
Es gibt aber über einen Umweg eine Lösung dazu. Wir können exakt so wie oben beschrieben einen Weiteren Webdienst anlegen. Dieses Mal benutzen wir aber nicht die Page Id 5201, sondern 5200. Die Page Id 5200 ist die Seite für die Mitarbeiter-Karte. Hier ist auch eine Bearbeitung (also Update) möglich.

Custom Business Central API

Zu guter Letzt gibt es noch eine dritte Möglichkeit eine Business Central API zu nutzen: Die Custom API. Wie der Name schon verrät handelt es sich hierbei nicht um etwas standardmäßiges. Ganz im Gegenteil: Eine Custom API ist der von Microsoft offiziell vorgeschriebene Weg eine eigene API in Business Central zu programmieren, sofern weder Standard-API oder Webdienst (siehe oben) funktionieren oder inhaltlich nicht ausreichend Felder oder Funktionen mit sich bringen.

Die Custom-API ist auf Seiten des Codes so aufgebaut, wie eine Standard-API. Entwickler halten sich hier an die Microsoft Vorgaben für Schnittstellenentwicklung um eine Interoperabilität auch mit Drittanbieter-Erweiterungen von Business Central sicherzustellen. „Look and Feel“ sind hierbei also wie bei einer Standard-API. Auf Microsoft’s Lernplattform gibt es einen Artikel, der beschreibt, wie man eine Custom API programmiert: Developing a custom API – Business Central | Microsoft Learn

Buchempfehlung

Sehr zu empfehlen ist das über 400 Seiten starke eBook Microsoft Dynamics 365 Business Central API Reference, welches über folgenden Link zu kaufen ist (kein Sponsored-Link!): Microsoft Dynamics 365 Business Central API Reference – Spare Brained Ideas. Das eBook ist sowohl für fortgeschrittene Anwender und primär für Entwickler (auch Business Central-fremde) geeignet.

Categorized in:

BC APIs,