Mit diesem Formular können Sie fehlende, unklare oder fehlerhafte Inhalte in der Dokumentation melden und Verbesserungsvorschläge machen. Ihr Feedback hilft uns, die Qualität und Vollständigkeit kontinuierlich zu verbessern.
Funktionsweise der Web Portal Connection aus Sicht des Partnersystems
Lesen geänderter Datensätze
Sobald Sie eine Änderungsnachricht erhalten und den zugehörigen Link zum betroffenen Datensatz gelesen oder konstruiert haben, rufen Sie den Datensatz in der aktuellen in Business Central vorhandenen Version neu ab. Die Adressierung des einzelnen Datensatzes erfolgt dabei anhand seiner SystemId:
[GET] https://api.company.com:7048/BC/api/gob/unitopWpc/v2.1/items(065b490d-e592-ec11-93b4-002245736866)?tenant=default
Als Header geben Sie dabei zusätzlich Informationen zu Company und Accept-Language an. Die Authentifizierung erfolgt je nach Installation mittels Basic Authentication oder OAuth2. Als Ergebnis erhalten Sie sämtliche vereinbarten Felder des Datensatzes sowie weitere verknüpfte Informationen, falls Sie diese mittels Parameter $expand im Request angefordert haben. Der Parameter $expand kann dabei auch geschachtelt eingesetzt werden, sodass Sie bspw. zu einem Artikel auch dessen Preise sowie zu den Preisen wiederum deren Währungssymbole in nur einer Abfrage erhalten können. Mittels Parameter $select bestimmen Sie optional einzelne Felder, die Sie auslesen möchten.
Debitorenpreis in Echtzeit
Der Endpunkt "items" bietet auch eine Funktion "calculateItemSalesPrice", die auf Basis übergebener Parameter einen debitorenspezifischen Artikelpreis in Echtzeit ermittelt und zurückgibt. Vergleichbare Funktionen gibt es auch für Varianten ("calculateItemVariantSalesPrice") und Ressourcen ("calculateResourceSalesPrice").
Der Einsatz dieser Echtzeitaufrufe ist aus verschiedenen Gründen (darunter Lastentkopplung, Verfügbarkeit, Performance, Skalierbarkeit etc.) nur in Ausnahmefällen zu empfehlen. Die reguläre Preisfindung sollte immer im Partnersystem auf Basis der synchronisierten Einrichtungswerte stattfinden. Artikelverfügbarkeiten
Sofern in Business Central eingerichtet kann sich ein Webportal auch mittels Änderungsnachrichten über veränderte Artikelverfügbarkeiten informieren lassen. Zusätzlich stellt Business Central einen Endpunkt zur gezielten Echtzeitermittlung einer Verfügbarkeit bereit.
Datenabgleich
Sollte sich zu einem bestimmten Zeitpunkt oder periodisch der Bedarf ergeben, Daten aus Business Central auch ohne Änderungsnachricht abzurufen, dann steht Ihnen die API auch für Massenabrufe wie bspw. für eine Erstbefüllung zur Verfügung. Hierfür nutzen Sie die im Projekt vereinbarten Endpunkte ohne Adressierung eines einzelnen Datensatzes, ggf. aber mit Filterung ($filter), Paging ($top, $skip) und/oder Erweiterung ($expand):
[GET] https://api.company.com:7048/BC/api/gob/unitopWpc/v2.1/items?tenant=default&$top=100&$skip=200&$filter=itemCategoryCode eq 'SMARTHOME'&$expand=itemVariants
Datenmanipulation
Sofern im Projekt vorgesehen, können Datensätze über die API auch angelegt oder geändert werden. Anwendungsfälle z. B. im Kontext eines Webportals sind die Anlage eines Kontaktes oder die Änderung der Anschrift eines Endkunden. Die Erstellung eines Datensatzes erfolgt dann mittels http-Verb "POST", die Änderung eines bestehenden – und anhand seiner SystemId adressierten Datensatzes – mittels http-Verb "PUT". Dabei werden die Feldinhalte im JSON-formatierten Body übermittelt.
Hinweis
In der in unitop enthaltenen API-Vorlage sind die Endpunkte für Debitoren und Kontakte schreibgeschützt.
Auftragsübermittlung
Hat ein Kunde im Webportal einen Auftrag platziert, dann übermittelt das Portal diesen asynchron an Business Central. Hierfür steht ein separater Endpunkt zur Verfügung:
[POST] https://api.company.com:7048/BC/api/gob/unitopWpc/v2.1/wpcInboundSalesDocuments/?tenant=default&$expand=inboundSalesLines
Sämtliche vereinbarten Inhalte werden im JSON-formatierten Body übermittelt. Diese gelangen dann in Business Central zunächst in einen Auftragspuffer. Dazu gehört auch die Angabe des gewünschten Belegprozessors, der die Bestellung in einen Auftrag bzw. eine andere Belegart überführen soll. Dies ermöglicht es, bereits im Webportal die unterschiedliche Behandlung zwischen bspw. B2B- und B2C- oder Inlands-/Auslands-Aufträgen festzulegen. Die Web Portal Connection bietet exemplarisch die Unterscheidung zwischen Angebots- und Auftragserstellung an. Sie übermitteln diese Information im Feld "documentProcessor". Ebenso übermitteln Sie eine Beleg-ID, unter der der Vorgang im Webportal eindeutig identifizierbar ist. Sie wird in Business Central gespeichert. Eine erneute Übermittlung eines Auftrages mit derselben Beleg-ID ("documentIdWeb") wird abgewiesen.
Anhand des im Body übermittelten Feldes "processingPreference" bestimmen Sie, ob die Überführung in einen tatsächlichen Verkaufsbeleg dann innerhalb von Business Central durch eine periodische Routine vorgenommen wird ("processingPreference": "asynchronous") oder ob Sie sie anschließend selbst anstoßen und dann auch ein Ergebnis erhalten ("processingPreference": "synchronous"). Der Endpunkt für die synchrone Ausführung lautet dann:
[POST] https://api.company.com:7048/BC/api/gob/unitopWpc/v2.1/wpcInboundSalesDocuments(d235f1ce-a522-ec11-878c-a1df74c26fde)/Microsoft.NAV.processInboundSalesDocument?tenant=default
Im JSON-formatierten Body senden Sie zur Plausibilitätsprüfung die Felder "sellToCustomerNumber" und "documentIdWeb" mit. Sollten sie nicht zum in der URL adressierten gepufferten Beleg passen, dann wird die Anfrage abgewiesen.