JSON-REST on Product Documentation

JSON-REST Schnittstellen

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Diese Seite bietet den Einstieg in die JSON-REST Schnittstellen des BE-Commerce Moduls.

Inhaltlicher Fokus

Export-Endpunkte für Stammdaten, Preise, Bestände und Statusinformationen
Import-Endpunkte für Aufträge, Kontakte, Retouren und Reservierungen
Einheitliche Konventionen für Filter, Request-Strukturen und Antworten

Leitplanken

Slugs und Endpunktnamen bleiben ASCII und konsistent.
Pflichtfilter (z. B. Webshop-Kanalcode) sind pro Endpunkt verbindlich.
Änderungen an Payload-Feldern müssen mit Shop-Integration und Folgeprozessen abgestimmt werden.

Export Artikel

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Artikeldaten eines Webshop-Kanals inklusive optionaler Erweiterungen wie Beschreibungen, Kategorien, Attribute, Cross-Selling und Varianten.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/items?$filter=webshopChannelCode eq '<webshop-channel-code>' and no eq '<item-no>'&$expand=itemDescriptions($expand=descriptions),categories,itemDynamicAttributes,itemFreeTextAttributes($expand=freeTextLanguages),crossSellingItems,itemSelectionVariants($expand=crossSellingVariants)

Pflichtparameter

webshopChannelCode im Filter
no (Artikelnummer) im Filter

Optionale Erweiterungen

itemDescriptions
categories
itemDynamicAttributes
itemFreeTextAttributes
crossSellingItems
itemSelectionVariants

Zentrale Rückgabefelder

Artikelkopf: systemId, webshopChannelCode, no, released, firstReleasedDate, vendorNo, itemDescription
Beschreibungen: Sprache, Metatitel, Beschreibungstypen
Kategoriezuordnung: Code und Hauptkategorie
Attribute: dynamische und Freitextattribute mit Sprachwerten
Varianten und Cross-Selling-Bezüge

Ergebnis

Der Webshop erhält einen konsolidierten Artikel-JSON-Datensatz im definierten Kanal- und Artikelfilter.

Export Preis

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Preisdaten je Webshop-Kanal, optional gefiltert auf einen einzelnen Artikel.

Endpunkt

Methode: GET
URL-Muster (kanalweit): http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/itemPrices?$filter=webshopChannelCode eq '<webshop-channel-code>'&$expand=itemVariantPrices($expand=prices)
URL-Muster (ein Artikel): http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/itemPrices?$filter=webshopChannelCode eq '<webshop-channel-code>' and itemNo eq '<item-no>'&$expand=itemVariantPrices($expand=prices)

Pflichtparameter

webshopChannelCode im Filter

Zentrale Rückgabefelder

Kopf: systemId, webshopChannelCode, itemNo, salesPricesSentToWebshop, lastSalesPriceChangeAt
Varianten: code
Preiszeilen: currency, unitPrice, customerPriceGroup, priceIncludesVAT

Ergebnis

Der Webshop erhält die aktuellen Preisstrukturen je Kanal und optional je Artikel.

Import Auftrag

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt übernimmt Auftragsdaten aus dem Webshop in den Importcontainer von Business Central.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Import/v2.0/companies(<company-system-id>)/orders?$filter=webshopChannelCode eq '<webshop-channel-code>'

Pflichtparameter

Filter webshopChannelCode
JSON-Body mit Auftragskopf und mindestens einer orderLines-Zeile

Kernbereiche der Payload

Auftragskopf: Kanal, Auftrags-ID, Datum, Summen, Währung, Kunden- und Kontaktreferenzen
Adressen: Sell-to, Bill-to und Ship-to
Zahlungs- und Versandinformationen
Positionen (orderLines) inkl. Typ, Artikel, Preis, Menge und optionalen Zusatzinformationen

Verarbeitungshinweis

Beim API-Aufruf erfolgt primär die syntaktische Übernahme in den Container.
Die semantische Prüfung und Belegerzeugung laufen im nachgelagerten Verarbeitungsprozess.

Ergebnis

Der Auftrag liegt als importierter Datensatz zur weiteren Verarbeitung in BC vor.

Siehe auch

Order Import API - Gutscheinverarbeitung

Import Kontakt

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt übernimmt Kontaktdaten aus dem Webshop in den Kontakt-Importcontainer von Business Central.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Import/v2.0/companies(<company-system-id>)/webshopContacts

Pflichtparameter

webshopChannel im Payload
JSON-Body mit Kontaktkopf

Kernbereiche der Payload

Kontaktkopf: Kanal, Kontaktnummer, Name, Adresse, Sprache, Land, Kommunikationsdaten
Optionale Zusatzfelder wie Anrede, Vor-/Nachname, Firmenname
Kontaktzeilen (webshopcontactLines) für Ship-to-bezogene Informationen

Antwortverhalten

Die API liefert den übernommenen Datensatz als JSON zurück.
Mit $expand=webshopcontactLines können die Kontaktzeilen in der Response mitgeliefert werden.

Ergebnis

Der Webshop-Kontakt ist für die weitere Verarbeitung in BC bereitgestellt.

Export Artikelliste

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert eine Artikelliste pro Webshop-Kanal inklusive Versandstatus und Aenderungszeitpunkt.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/itemsList?$filter=webshopChannelCode eq '<webshop-channel-code>' and sentToWebshop eq <true|false> and changedForWebshopAt eq <datetime>

Pflichtparameter

webshopChannelCode im Filter

Optionale Filter

sentToWebshop
changedForWebshopAt

Zentrale Rueckgabefelder

systemId, itemNo, webshopChannelCode, changedForWebshopAt, sentToWebshop

Ergebnis

Der Webshop erhaelt die Artikelliste fuer Delta- oder Vollabgleiche.

Export Bestand

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Bestandsdaten fuer einen Artikel inklusive optionaler Variantendaten.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/inventories?$filter=webshopChannelCode eq '<webshop-channel-code>' and itemNo eq '<item-no>'&$expand=itemVariants

Pflichtparameter

webshopChannelCode im Filter
itemNo im Filter

Zentrale Rueckgabefelder

Kopf: systemId, webshopChannelCode, itemNo
Varianten: code, inventory

Ergebnis

Der Webshop erhaelt den aktuellen Bestand je Artikel und Variante.

Export Bestand Artikelliste

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert je Kanal die Bestandsliste aller relevanten Artikel mit Delta-Hinweisen.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/inventoriesItemsList?$filter=webshopChannelCode eq '<webshop-channel-code>'

Pflichtparameter

webshopChannelCode im Filter

Zentrale Rueckgabefelder

systemId, webshopChannelCode, itemNo, inventorySentToWebshop, lastStockChangeAt

Ergebnis

Der Webshop erhaelt den Bestandsabgleich fuer alle Artikel eines Kanals.

Export Kontakt

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Kontaktdaten und zugehoerige Lieferadressen fuer die Shop-Synchronisierung.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/contacts?$expand=contactsShipTo

Filter und Erweiterungen

Kontaktfilter erfolgt ueber die Kontaktnummer
Lieferadressen werden ueber $expand=contactsShipTo mitgegeben

Zentrale Rueckgabefelder

Kontakt: no, name, address, postCode, city, country, email
Lieferadresse: shipToCode, shipToName, shipToAddress, shipToPostCode, shipToCity

Ergebnis

Der Webshop erhaelt Kontaktstammdaten inklusive Lieferadressstruktur.

Export Kontaktstatus

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert den Status einer Kontaktverarbeitung inklusive Fehlertext.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/ODataV4/<serviceName>_ContactStatusExportOData?company=<companyName|companyId>

Payload-Pflichtfelder

webshopChannel_P
contactNo_P oder eMail_P

Antwort

Die Rueckgabe enthaelt ein JSON-Objekt im Feld value mit contactNo und errorText.

Ergebnis

Der Shop kann den Verarbeitungsstatus zu einem Kontakt asynchron pruefen.

Export Lagerorte

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert alle Lagerorte, die einem Webshop-Kanal zugeordnet sind.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/channels('<webshop-channel-code>')?$expand=locations

Pflichtparameter

webshop-channel-code in der Channel-URL

Zentrale Rueckgabefelder

Kanal: code
Lagerort: code, name, address, postCode, city, countryRegion, phoneNo, eMail

Ergebnis

Der Shop erhaelt die verknuepften Lagerorte fuer Versand- und Verfuegbarkeitslogik.

Export Kreditor

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Kreditorstammdaten fuer Integrationsszenarien mit Lieferantenbezug.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/vendors

Zentrale Rueckgabefelder

systemId, no, name, address, postCode, city, countryRegionCode
eMail, currencyCode, languageCode, paymentTermsCode, shipmentMethodCode, blocked

Ergebnis

Externe Systeme erhalten den aktuellen Lieferantenstamm aus BC.

Export Webshop Kategorie

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert die Kategorien eines Kanals inklusive Hierarchieattributen und optionaler Sprachtexte.

Endpunkt

Methode: GET
URL-Muster Kategorien: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/webshopCategories?$filter=webshopChannelCode eq '<webshop-channel-code>'
URL-Muster Kategorienbeschreibungen: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/webshopCategoryDescriptions?$filter=webshopChannelCode eq '<webshop-channel-code>' and webshopCategorySystemId eq <category-system-id>

Pflichtparameter

webshopChannelCode
Fuer Beschreibungen zusaetzlich webshopCategorySystemId

Zentrale Rueckgabefelder

Kategorie: systemId, webshopCategoryCode, parentCategoryCode, active, hidden
Texte: language, text, webshopCategorySystemId

Ergebnis

Der Shop erhaelt Kategoriebaum und mehrsprachige Kategoriebezeichnungen.

Import Reklamation

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt uebernimmt Retourenauftraege aus dem Webshop in den BC-Importcontainer.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Import/v2.0/companies(<company-system-id>)/returnOrders

Pflichtfelder im Payload

Kopf: webshopChannelCode, orderId, orderType, orderDate, currency, customerNo, contactNo
Zeilen (returnOrderLines): mindestens eine Zeile mit id, type, amount sowie Belegreferenz (orderNo, orderLineNo)

Antwortverhalten

Rueckgabe als JSON mit importiertem Kopf.
Optional mit $expand=returnOrderLines inklusive importierter Zeilen.

Ergebnis

Der Retourenauftrag ist fuer die Folgeprozesse in BC uebernommen.

Import Reservierung

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt uebernimmt Reservierungsauftraege aus dem Webshop.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Import/v2.0/companies(<company-system-id>)/webshopReservations?$expand=webshopReservationLines

Pflichtfelder im Payload

Kopf: webshopChannelCode, reservationOrderId, orderType, orderDate, currency
Zeilen (webshopReservationLines): mindestens eine Zeile mit id, type, itemNumber, amount

Zentrale Hinweise

Leere Felder koennen im Payload ausgelassen werden.
Bei Bedarf werden Adress- und Kontaktdaten mit uebergeben.

Ergebnis

Die Reservierung ist fuer die weitere Verarbeitung im BC-System vorhanden.

Export Artikelbeschreibung

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Diese Seite beschreibt den Export von Artikelbeschreibungen (Meta Title, Short Description, Long Description) je Sprache.

Endpunkte

Via Artikelausgabe mit Expand: http://<server>:<port>/<service-tier>/api/beTerna/export/v2.0/companies(<company-system-id>)/items?$filter=webshopChannelCode eq '<webshop-channel-code>' and no eq '<item-no>'&$expand=wsItemDescriptions
Direkte Beschreibungsabfrage: http://<server>:<port>/<service-tier>/api/beTerna/export/v2.0/companies(<company-system-id>)/wsItemDescriptions?$filter=webshopChannel eq '<webshop-channel-code>'

Pflichtparameter

webshopChannelCode bzw. webshopChannel
Bei Artikelausgabe zusaetzlich no

Zentrale Rueckgabefelder

itemNo, language, descriptionType, descriptionText

Ergebnis

Der Webshop erhaelt sprachabhaengige Artikeltexte fuer SEO- und Produktdarstellungen.

Export Auftragsstatus

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert den Statusverlauf eines Auftrags auf Kopf- und Positionsebene.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/orderStatusCodes?$filter=webshopChannelCode eq '<webshop-channel-code>' and externalDocumentNo eq '<external-document-no>'

Pflichtparameter

webshopChannelCode
externalDocumentNo

Zentrale Rueckgabefelder

statusCode, documentType, documentNo, externalDocumentNo, lineNo, itemNo, systemCreatedAt

Ergebnis

Der Shop kann den aktuellen Bearbeitungsstand pro Auftrag und Zeile nachvollziehen.

Order Import API - Gutscheinverarbeitung

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Diese Seite beschreibt die korrekte Uebermittlung von Gutscheinzeilen im JSON-REST Auftragsimport.

Relevanter Endpunkt

POST /api/BEterna/Import/v2.0/companies(<company-system-id>)/orders

Zeilentypen fuer Gutscheine

type = 2: Gutscheinkauf
type = 5: Gutscheineinloesung

Kernregeln

voucherCode ist fuer beide Gutscheintypen Pflicht.
Bei type = 5 muss singlePrice negativ oder 0 sein.
subtotal wird ohne type = 5 berechnet.
totalAmount wird mit allen Zeilen inklusive type = 5 berechnet.
Betrag der Einloesungen darf die Zwischensumme nicht uebersteigen.

Ergebnis

Gutscheine werden valide importiert und in der weiteren BC-Verarbeitung korrekt beruecksichtigt.

Export Auftragshistorie

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert Historiedaten zu Auftraegen inklusive Positionen.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/orderHistoryHeaders?$filter=webshopChannelCode eq '<webshop-channel-code>'&$expand=orderHistoryLines

Pflichtparameter

webshopChannelCode im Filter

Zentrale Rueckgabefelder

Kopf: webshopOrderNo, salesOrderNo, createdAt, type, postedDocumentNo, trackingNo
Zeilen: orderLineNo, itemNo, variantCode, quantity, lineAmount, postedDocumentLineNo

Ergebnis

Der Webshop erhaelt die Auftragshistorie fuer Statusanzeige und Nachverfolgung.

Export Dokumentenstatus

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert den Verarbeitungsstatus eines Dokuments inklusive Fehlertext.

Endpunkt

Methode: POST
URL-Muster: http://<server>:<odata-port>/<service-tier>/ODataV4/<serviceName>_DocumentStatusExportOData?company=<companyName|companyId>

Pflichtfelder im Payload

webshopChannelCode
orderType
orderNo

Antwort

Die Rueckgabe enthaelt im Feld value ein JSON mit documentCreated und errorText.

Ergebnis

Integrationen koennen pruefen, ob ein Beleg erstellt wurde oder ein Fehler vorliegt.

Export Dynamische Attribute

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Diese Seite beschreibt den Export dynamischer Attribute inklusive Werte- und Sprachdaten.

Endpunkte

Attribute: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/dynamicAttributes
Attributbeschreibungen: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/dynamicAttributeDescriptions?$filter=webshopChannelCode eq '<webshop-channel-code>' and dynamicAttributeSystemId eq <dynamic-attribute-system-id>
Attributwerte: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/dynamicAttributeValues?$filter=dynamicAttributeCode eq '<dynamic-attribute-code>'
Wertbeschreibungen: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/dynamicAttributeValueDescriptions?$filter=webshopChannelCode eq '<webshop-channel-code>' and dynamicAttributeValueSystemId eq <dynamic-attribute-value-system-id>

Zentrale Rueckgabefelder

Attribute: dynamicAttributeCode, filter, show
Werte: dynamicAttributeValueCode
Beschreibungen: language, text

Ergebnis

Der Shop erhaelt strukturierte Attribut- und Uebersetzungsdaten fuer die Produktdarstellung.

Export Filialbestand Artikelvarianten Liste

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert alle Artikelvarianten mit Filialbestandsaenderung seit dem letzten Abgleich.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<port>/<service-tier>/api/beTerna/export/v2.0/companies(<company-system-id>)/branchinventoriesItemVariantsList?$filter=webshopChannelCode eq '<webshop-channel-code>' and branchinvSentToWebshop eq false

Pflichtparameter

webshopChannelCode im Filter

Zentrale Rueckgabefelder

itemNo, variantCode, branchInvSentToWebshop, lastBranchStockChangeAt

Ergebnis

Diese Liste dient als performanter Trigger fuer nachgelagerte Filialbestandsabfragen.

Export Filialbestand

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Der Endpunkt liefert verfuegbare Bestaende pro Filiale fuer einen Artikel inklusive Varianten.

Endpunkt

Methode: GET
URL-Muster: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/branchInventories?$filter=webshopChannelCode eq '<webshop-channel-code>' and no eq '<item-no>'&$expand=branchItemVariants($expand=branchLocations)

Pflichtparameter

webshopChannelCode im Filter
no (Artikelnummer) im Filter

Zentrale Rueckgabefelder

Kopf: webshopChannelCode, no
Varianten: code
Filialdaten: code, inventory, calculationTimeStamp

Ergebnis

Der Webshop erhaelt filialgenaue Bestandsdaten fuer Verfuegbarkeitslogik.

Export Freitextattribute

Mon, 01 Jan 0001 00:00:00 +0000

Zweck

Diese Seite beschreibt den Export von Freitextattributen inklusive Uebersetzungen.

Endpunkte

Freitextattribute: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/freeTextAttributes
Freitextattribut-Beschreibungen: http://<server>:<odata-port>/<service-tier>/api/BEterna/Export/v2.0/companies(<company-system-id>)/freeTextAttributeDescriptions?$filter=webshopChannelCode eq '<webshop-channel-code>' and freeTextAttributeSystemId eq '<free-text-attribute-system-id>'

Pflichtparameter

Bei Beschreibungen: webshopChannelCode und freeTextAttributeSystemId

Zentrale Rueckgabefelder

Attribute: code
Beschreibungen: language, text

Ergebnis

Der Shop erhaelt Freitextattribute fuer Produktcontent und sprachspezifische Ausgabe.

JSON-REST on Product Documentation

JSON-REST Schnittstellen

Zweck

Inhaltlicher Fokus

Leitplanken

Erste Endpunkte

Export Artikel

Zweck

Endpunkt

Pflichtparameter

Optionale Erweiterungen

Zentrale Rückgabefelder

Ergebnis

Export Preis

Zweck

Endpunkt

Pflichtparameter

Zentrale Rückgabefelder

Ergebnis

Import Auftrag

Zweck

Endpunkt

Pflichtparameter

Kernbereiche der Payload

Verarbeitungshinweis

Ergebnis

Siehe auch

Import Kontakt

Zweck

Endpunkt

Pflichtparameter

Kernbereiche der Payload

Antwortverhalten

Ergebnis

Export Artikelliste

Zweck

Endpunkt

Pflichtparameter

Optionale Filter

Zentrale Rueckgabefelder

Ergebnis

Export Bestand

Zweck

Endpunkt

Pflichtparameter

Zentrale Rueckgabefelder

Ergebnis

Export Bestand Artikelliste

Zweck

Endpunkt

Pflichtparameter

Zentrale Rueckgabefelder

Ergebnis

Export Kontakt

Zweck

Endpunkt

Filter und Erweiterungen

Zentrale Rueckgabefelder

Ergebnis

Export Kontaktstatus

Zweck

Endpunkt

Payload-Pflichtfelder

Antwort

Ergebnis

Export Lagerorte

Zweck

Endpunkt

Pflichtparameter

Zentrale Rueckgabefelder

Ergebnis

Export Kreditor

Zweck

Endpunkt

Zentrale Rueckgabefelder

Ergebnis

Export Webshop Kategorie

Zweck

Endpunkt

Pflichtparameter