JSON Schnittstelle

Bestellungen ("orders"):

Aufbau:

"orders": array of `OrderObject`

OrderObject:

Property nameDescriptionDefinition
idWebshop Order Numberstring, max 255 characters, unique
created_at_utcOrder creation dateformat utc with timezone
updated_at_utcOrder update datedatetime, format utc with timezone
statusWebshop Order Statusstring
shipping_methodShippingObjectVersandart
currencyCurrency Code (nur info wie der Kunde bezahlt, die Line items sind immer in Euro)3 characters
commentCustomer order commentstring, max. 255 characters, optional
taxmodelKennzeichen ob Brutto oder Netto verrechnet wurde: Preisangaben in Line items sind dann auch brutto od netto"GROSS" or "NET"
_paymentOrderPaymentObjectZahlungsinformation
_linesarray of OrderLineObjectRechnungszeilen (Produkt, Versandkosten, Rabatte, Gesamtsumme)
_shipping_addressOrderAddressObjectVersandadresse des Kunden (optional bei Bestellungen ohne materielle Güter)
_billing_addressOrderAddressObjectRechnungsadresse des Kunden

Beispiel:

{
  "orders": [
    {
      "id": "100000222",
      "created": "2019-05-22 07:30:50",
      "updated": "2019-05-22 07:31:25",
      "status": "processing",
      "shipping_method": {
        "type": "DHL",
        "description": "Versand über DHL"
      },
      "currency": "EUR",
      "comment": "Kommentar zur Bestellung vom Kunden",
      "taxmodel": "GROSS",
      "_payment": {
        "method": "CC",
        "cctype": "Visa"
      },
      "_lines": [
        {
          "type": "product",
          "is_line": true,
          "quantity": "1",
          "sku": "2113000016259",
          "name": "Product name",
          "unitprice": 19.99,
          "amount": 19.99,
          "discount_amount": 0,
          "tax_amount": 3.33,
          "taxclass": "REGULAR"
        },
        {
          "type": "shipping",
          "is_line": true,
          "amount": 4.9,
          "tax_amount": 0.82,
          "taxclass": "REGULAR"
        },
        {
          "type": "total",
          "is_line": false,
          "amount": 24.89,
          "tax_amount": 4.15
        }
      ],
      "_shipping": {
        "id": 2864,
        "salutation": "Herr",
        "firstname": "Stephan",
        "lastname": "Muster",
        "street": "Pottendorfer Straße 23",
        "zip": "1120",
        "city": "Wien",
        "country": "AT",
        "company": "ETRON",
        "email": "max.muster@muster.at",
        "phone": "+43 546 889797979",
        "vat_id": "ATU192853434"
      },
      "_billing": {
        "id": 2864,
        "salutation": "Herr",
        "firstname": "Stephan",
        "lastname": "Muster",
        "street": "Pottendorfer Straße 23",
        "zip": "1120",
        "city": "Wien",
        "country": "AT",
        "company": "ETRON",
        "email": "max.muster@muster.at",
        "phone": "+43 546 889797979",
        "vat_id": "ATU1928533434"
      }
    }
  ]
}

ShippingObject

Property nameDescriptionDefinition
typeWebshop Shipping Method Identifierstring, max 255 characters
descriptionDescription information for shipping method (like address if packup at store)string, max 255 characters, optional

OrderPaymentObject

Property nameDescriptionDefinition
methodWebshop Payment Method Identifierstring, max 255 characters One of cc, paypal, sofort, invoice, banktransfer, cod
cctypeType of credit card (various)string, max 255 characters, if method="cc" One of Visa, MC/MasterCard, Amex (exact values may vary)

OrderLineObject

Property nameDescriptionDefinition
typeType of line itemone of "product", "shipping", "discount", "total" (is special because all other lines sum up to equal total line)
is_lineFlag whether line should appear in billing documentstrue (if type=product or shipping) / false (if type=discount or total)
quantityLine item quantitynumeric, needed if type="product"
skuSKU of productneeded if type="product"
nameName of productneeded if type="product", string max 255 characters
unitpriceBase price of product (noch nicht rabattiert)needed if type="product", decimal, 2 decimals if order taxmodel="GROSS", 4 decimals precision of order taxmodel="NET"
discount_amountDiscount calculated on product lineoptional if type="product", decimal, 2 decimals if order taxmodel="GROSS", 4 decimals precision of order taxmodel="NET"
amountLine price of product(=unitprice * quantity - discount_amount) needed if type="product", decimal, 2 decimals if order taxmodel="GROSS", 4 decimals precision of order taxmodel="NET"
tax_amountTax amount of line price(tax of amount) needed if type="product", decimal, 2 decimals if order taxmodel="GROSS", 0 if order taxmodel="NET"
taxclassTax class identifier of productstring

OrderAddressObject

Property nameDescriptionDefinition
idWebshop Address Entry IDnumeric
salutationCustomer Prefix (Mr,Mrs,Herr,Frau)string, max 255 characters, optional
firstnameCustomer First Namestring, max 255 characters
lastnameCustomer Last Namestring, max 255 characters
streetCustomer Street Addressstring, max 255 characters. May contain "\n" for line breaks
zipCustomer ZIPstring, max 255 characters
cityCustomer Citystring, max 255 characters
countryCustomer Country Code2 characters ISO Country code
companyCustomer Company Name Codestring, max 255 characters, optional
emailCustomer eMail Addressstring, max 255 characters
phoneCustomer Phone Numberstring, max 255 characters, optional
vat_idCustomer VAT Numberstring, max 255 characters, optional

Mapping Tabelle, Anforderungen onRetail

OrderObject

JSON API FELDTransformationonRetail DatenzielAnpassungRelated US
id1:1-Neues Feld für die Webshop Order ID
createdUmwandlung zu Datetimesale.order.create_date-
updatedUmwandlung zu Datetimesale.order.write_date-
statusMapping Tabelle-sale.order Stati auf die des Webshops mappen
shipping_methodMapping Tabelledelivery.carrier-
currencyMapping Tabelleres.currency-
comment1:1-Neues Feld
taxmodel1:1-Neues Feld, Berechnung der Preise
_paymentOrderPaymentObject-
_linesarray of OrderLineObject
_shipping_addressOrderAddressObject
_billing_addressOrderAddressObject

OrderPaymentObject

JSON API FELDTransformationonRetail DatenzielAnpassungRelated US
methodMapping Table-Mapping Table
additional_informationMapping Table-Mapping Table. Bei Info success, Zahlung zur sale.order hinzufügen

OrderLineObject

JSON API FELDTransformationonRetail DatenzielAnpassungRelated US
type-sale.orderVersandkosten/Rabatt zuordnen
quantity1:1sale.order.line.product_uom_qty-
sku1:1sale.order.line.product_id-
name-sale.order.line.product_id.nameFeld verwerfen, Name ist abhängig von der gewählten Sprache
unitprice1:1sale.order.line.price...Berechnung/Datenziel abhängig vom Typ
amount1:1sale.order.line.price_subtotal-
tax_amount1:1-Neues Feld, Berechnung der Steuer durch onRetail muss möglicherweise umgangen werden
taxclass1:1product.product.tax_id.code-

OrderAddressObject

JSON API FELDTransformationonRetail DatenzielAnpassungRelated US
id1:1-Neues Feld für die Webshop Kunden ID
prefixMapping Tableres.partner.titleMapping
firstnameConcatres.partner.nameVor- und Nachname zuammenführen
lastnameConcatres.partner.nameVor- und Nachname zuammenführen
streetString Bereinigenres.partner.street-
zip1:1res.partner.zip-
city1:1res.partner.city-
country1:1res.partner.country_id.code-
companyNeuanlage Unternehmen bei Neukunden, ansonsten Feld verwerfenres.companyWeshop Kunden ID
email1:1res.partner.email-
phone1:1res.partner.phone-
vat1:1res.partner.vat-

Bestellstatus "orderstatus"

Aufbau

"orderstatus": array of `OrderStatusObject`

OrderStatusObject

Property nameDescriptionDefinition
idWebshop Order Numbernumeric
statusOrder Status (wird auf der Gateway gemappt)string, max 255 characters

Mögliche Order Stati:

  • processing: Bestellung in Bearbeitung
  • complete: Bestellung wurde versendet
  • cancelled: Bestellung wurde storniert

Beispiel:

{
  "orderstatus": [
    {
      "id": "10000111",
      "status": "complete"
    },
    {
      "id": "10000112",
      "status": "cancelled"
    }
  ]
}

Mapping Tabelle, Anforderungen onRetail

OrderStatusObject

JSON API FELDTransformationonRetail DatenquelleAnpassungRelated US
id1:1-Neues Feld für die Webshop Order ID
statusMapping Tablesale.order.statesale.order und Webshop Stati mappen

Kategorien („categories“):

Kategorien werden in allen konfigurierten Sprachen übertragen. Kategoriebilder liegen auf einem externen Bilderspeicher (SFTP oder Amazon S3). Als Bildangaben sind immer alle zum Basisordner relativen Pfadangaben anzugeben.

Beispiel für Kategorien in nur 1 Sprache (scopeId = "default"):

{
  "categories": {
    "default": [
      {
        "id": "1",
        "name": "Hauptkategorie",
        "parent_id": "0",
        "position": 1,
        "visible": true,
        "image": "http://cdnmax938.maxcdn.com/saalhsf/1.jpg",
        "description": "Beschreibung Hauptkategorie"
      },
      {
        "id": "2",
        "name": "Unterkategorie",
        "parent_id": "1",
        "position": 1,
        "visible": true
      },
      {
        "id": "3",
        "name": "Unterkategorie 2",
        "parent_id": "1",
        "position": 2,
        "visible": true
      }
    ]
  }
}

Beispiel für Kategorien in zwei Sprachen "de" (Deutsch) und "en" (Englisch) mit den gleichnamigen scopeIds:

{
  "categories": {
    "en": [
      {
        "id": "1",
        "name": "Main category",
        "parent_id": "0",
        "position": 1,
        "visible": true
      },
      {
        "id": "2",
        "name": "Sub category",
        "parent_id": "1",
        "position": 1,
        "visible": true
      },
      {
        "id": "3",
        "name": "Sub category 2",
        "parent_id": "1",
        "position": 2,
        "visible": true
      }
    ],
    "de": [
      {
        "id": "1",
        "name": "Hauptkategorie",
        "parent_id": "0",
        "position": 1,
        "visible": true
      },
      {
        "id": "2",
        "name": "Unterkategorie",
        "parent_id": "1",
        "position": 1,
        "visible": true
      },
      {
        "id": "3",
        "name": "Unterkategorie 2",
        "parent_id": "1",
        "position": 2,
        "visible": true
      }
    ]
  }
}

Aufbau:

"categories": {
  "scopeId": **array of** `CategoryObject`,
  "scopeId": **array of** `CategoryObject`,...
}

CategoryObject:

Property nameDescriptionDefinition
idEindeutiger Schlüssel für Kategoriealphanumeric string, unique, max 255 characters
nameKategorienamestring (utf8), max 255 characters
parent_idReferenz auf einen eindeutigen Schlüssel einer Kategoriealphanumeric string
positionPosition/Reihenfolge der Kategorie innerhalb der Hierarchie (Elemente mit gleichem parent_id)numeric, unsigned int
visibletrue=Kategorie ist sichtbar im Menü, false=Kategorie ist nicht sichtbar im Menüboolean
imagerelativer Pfad zum Kategorie-Bild am Bilderspeicherurl, optional

onRetail Anforderungen

Mapping Tabelle, Anforderungen onRetail

CategoryObject:

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
id1:1product.public.category.id-#0f0
name1:1product.public.category.nameBegrenzung auf 255 Zeichen, HTML Sonderzeichen filtern#0f0
parent_id1:1product.public.category.parent_id-#0f0
position1:1product.public.category.sequence-#0f0
visible1:1-visible Attribut zur Kategorie hinzufügen#ff0
image1:1product.public.category.image-#0f0

Produkte ("products"):

Produkte und beim Produkt definierte Kategoriezuweisungen werden gemeinsam exportiert.

Vom Datenaustauschformat unterstützt werden einfache und konfigurierbare Produkte in einer und mehreren Sprachen, sowie optionale Unterstützung für Multistore (Price per Store)/Multi-Inventory (Inventory per Store).

Attribute wie weight, sku und status sind globale Attribute (d.h. sprach/store-unabhängig). Die Attribute _categories (Kategoriezuordnungen) und _images (Bildzuordnungen) sind optional und immer global (also sprach/store-unabhängig).

Ein Scope (Geltungsbereich) ist der Abschnitt, der sprach- bzw. storebezogene Produktdaten definiert (Preise, Produkttexte)

Produktbilder liegen auf einem externen Bilderspeicher (SFTP oder Amazon S3). Als Bildangaben sind immer alle zum Basisordner relativen Pfadangaben anzugeben.

Aufbau:

"products": array of `ProductObject`

ProductObject:

Property nameDescriptionDefinition
skueindeutige Produktkennungalphanumeric string, unique, max 255 characters
weightProduktgewicht in kgdecimal
statusProdukt-Freigabe für Webshop: 1=freigegeben, 0=nicht freigegebennumeric
stockLagerstand für Webshopnumeric
barcodesMit Komma getrennte EAN Listestring (utf8) Zahlen, Komma und Leerzeichen erlaubt
new_date_fromDatum für "Neu ab"date, format YYYY-MM-DD, optional, new-to > new-from
new_date_toDatum für "Neu bis"date, format YYYY-MM-DD, optional, new-to > new-from
featuredMarkierungtrue/false
sale_steppingMengenangabe in der das Produkt verkauft werden darf. Verkaufte Menge muss ein Vielfaches der Mengenabgabe sein.numeric >=1, Standardwert 1
manufacturerManufacturer Namestring(utf8)
manufacturer_linkLink zur Produktseite des Herstellersstring(utf8)
_categoriesarray of CategoryObject(optional)
_imagesarray of ImageObjects, Pfade/Urls zu den Bildern
_pricePriceObject
_linked_skusarray of ProductLinkObjectProduktverknüpfungen für Up-, Cross-selling und Related Products
_scopesarray of ProductPropertiesÜbersetzungen von Produktfeldern
_variation_configVariationObjectnur bei konfigurierbaren Produkten
{
  "products": [
    {
      "sku": "SKU1",
      "weight": 0.1,
      "status": 1,
      "stock": 99,
      "manufacturer" : "Herstellername",
      "manufacturer_link": "www.hersteller.com/products/1"
      "_categories": [
        {
          "cat_id": 1
        },
        {
          "cat_id": 2
        },
        {
          "cat_id": 3
        }
      ],
      "_images": [
        {
          "url": "www.example.com/path/to/imagefile1.jpg" ,
          "position": 1
        },
        {
          "rel_path": "www.example.com/path/to/imagefile2.jpg",
          "position": 10
        }
      ],
      "_price": {
        "regular": 9.1583,
        "special": 8.325,
        "taxclass": "REGULAR",
        "_tiers": [
          {
            "pricelist_id": 1,
            "quantity": 10,
            "price": "8.99"
          },
          {
            "pricelist_id": 1,
            "quantity": 20,
            "price": "7.99"
          }
        ]
      },
      "_scopes": [
        {
          "scopeid": "de",
          "data": [
            {
              "field": "name",
              "data": "Produktname"
            },
            {
              "field": "short_description",
              "data": "Deutsche Kurzbeschreibung"
            },
            {
              "field": "description",
              "data": "Deutsche Langbeschreibung"
            }
          ]
        },
        {
          "socpeid": "en",
          "data": [
            {
              "field": "name",
              "data": "Product name"
            },
            {
              "field": "short_description",
              "data": "english short description"
            },
            {
              "field": "description",
              "data": "english description"
            }
          ]
        }
      ]
    }
  ]
}

ImageObject

Property nameDescriptionDefinition
urlurl zum Produktbildstring(utf8)
positionPosition/Reihung des Bildesnumeric, ganze Zahl

PriceObject

Property nameDescriptionDefinition
regularnormaler Webshop Verkaufspreis (netto)decimal, 4 decimals precision
specialreduzierter Webshop Sonderpreis (netto)decimal, 4 decimals precision, optional
special_date_fromDatum ab Gültigkeit Sonderpreisdate, format utc with timezone, optional
special_date_toDatum bis Gültigkeit Sonderpreisdate, format utc with timezone, optional
taxclassKennzeichen für Steuerklasse (wird auf Gateway gemappt)alphanumeric string, max 255 chars
_tiersarray of PriceTierObjectoptional

PriceTierObject

Property nameDescriptionDefinition
pricelist_idKundengruppen-Kennung (wird auf Gateway gemappt). "0" or "" (empty) = allgemeine Preisstaffel (nicht kundengruppenabhängig)alphanumeric string, optional
quantityAb Menge (bei Staffelpreis), sonst 1numeric, min. 1
pricePreis nettodecimal, 4 decimals precision

ProductProperties

Liste aller übersetzten Felder eines Produktes

Property nameDescriptionDefinition
nameProduktnamestring (utf8), max 255 chars
short_descriptionWebshop Kurzbeschreibungstring (utf8)
descriptionWebshop Langbeschreibungstring (utf8)
delivery-readyText für "Versandbereit in" Angabestring (utf8)

VariationObject

Property nameDescriptionDefinition
attributesarray of attribute namesListe der Attributnamen, welche die Konfiguration des Artikels bestimmen
childrenarray of product SKUsListe der Produkt-SKUs, aus denen das konfig. Produkt besteht

Beispiel: Konfigurierbares Produkt mit 2 Varianten (Farbe=Grün und Farbe=Blau). Farbvariante Blau kostet 13 € inkl. 20% MwSt, Farbvariante Grün kostet 12 € inkl. 20% MwSt..

{
  "products": [
    {
      "sku": "ConfigProduct1",
      "status": 1,
      "_categories": [
        {
          "cat_id": 1
        },
        {
          "cat_id": 2
        },
        {
          "cat_id": 3
        }
      ],
      "_variation_config": {
        "attributes": [
          "farbe"
        ],
        "children": [
          "child-sku-1",
          "child-sku-2"
        ]
      },
      "_images": [
        {
          "url": "www.example.com/path/to/imagefile1.jpg" ,
          "position": 1
        },
        {
          "rel_path": "www.example.com/path/to/imagefile2.jpg",
          "position": 10
        }
      ],
      "_scopes": [
        {
          "scopeid": "default",
          "data": [
            {
              "field": "name",
              "data": "Produktname"
            },
            {
              "field": "short_description",
              "data": "Kurzbeschreibung"
            },
            {
              "field": "description",
              "data": "Beschreibung"
            }
          ]
        }
      ]
    },
    {
      "sku": "child-sku-1",
      "weight": 1,
      "stock": 1,
      "status": 1,
      "_price": {
        "regular": 10.8333,
        "taxclass": "REGULAR"
      },
      "_scopes": [
        {
          "scopeid": "default",
          "data": [
            {
              "field": "name",
              "data": "Variante Blau"
            },
            {
              "field": "farbe",
              "data": "blau"
            }
          ]
        }
      ]
    },
    {
      "sku": "child-sku-2",
      "weight": 1,
      "stock": 1,
      "status": 1,
      "_price": {
        "regular": 10,
        "taxclass": "REGULAR"
      },
      "_scopes": [
        {
          "scopeid": "default",
          "data": [
            {
              "field": "name",
              "data": "Variante Grün"
            },
            {
              "field": "farbe",
              "data": "grün"
            }
          ]
        }
      ]
    }
  ]
}

ProductLinkObject

Property nameDescriptionDefinition
typeType of the listed SKUscan be "upsell", "crosssell" or "related" (Upselling, Crossselling oder Zubehoer Produkte)
skusarray of product SKUsListe der Upsell-Produkt-SKUs

Beispiel: Produkt mit Links

{
  "products": [
    {
      "sku": "SKU1",
      "weight": 0,
      "_categories": [
        {
          "cat_id": 1
        },
        {
          "cat_id": 2
        },
        {
          "cat_id": 3
        }
      ],
      "_images": [
        {
          "url": "www.example.com/path/to/imagefile1.jpg" ,
          "position": 1
        },
        {
          "rel_path": "www.example.com/path/to/imagefile2.jpg",
          "position": 10
        }
      ],
      "name": "Produktname",
      "short_description": ".....",
      "description": ".....",
      "status": 1,
      "stock": 1,
      "_price": {
        "regular": 9.1583,
        "special": 8.325,
        "taxclass": "REGULAR"
      },
      "_linked_skus": [
        {
            "type": "upsell",
            "skus": [
                "linked-upsell-sku-1",
                "linked-upsell-sku-2"
            ]
        },
        {
            "type": "crosssell",
            "skus": [
                "linked-upsell-sku-1",
                "linked-upsell-sku-2"
            ]
        },
        {
            "type": "related",
            "skus": [
                "linked-upsell-sku-1",
                "linked-upsell-sku-2"
            ]
        }
      }
    }
  ]
}

Mapping Tabelle, Anforderungen onRetail

ProductObject

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
sku1:1product.product.product_code-#0f0
weight1:1product.product.weight-#0f0
status1:1-Neues Feld product.template.webshop_active#ff0
stockSumme der Lagerstände der zu verwendeten Läger-Neue Einstellung welche Läger für den Webshop verwendet werden sollen. Neues computed Feld product.product.webshop_stock#ff0
barcodes1:1product.template.barcodesbarcodes Feld zu product.product hinzufügen#0f0
new_date_from1:1-Neues Datum Feld in product.template#0f0
new_date_to1:1-Neues Datum Feld in product.template#0f0
featured1:1-Neues bool Feld in product.template#0f0
sale_stepping1:1-Neues Feld#0f0
manufacturer1:1manufacturer.manufacturer.nameNeues Model für Hersteller
manufacturer_link1:1product.manufacturer_urlNeues Feld
_categoriesCategoryObjectproduct.template.public_categ_ids-
_images1:1product.template/product.image_idsMehrere Bilder im Template und der Variante hinterlegen#ff0
_pricePriceObject--
_linked_skusarray of ProductLinkObject--
_scopesarray of ProductProperties--
_variation_configarray of VariationObject-Auflösen der vorhandenen Attribute von product.template

ImageObject

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
urlurl generierenproduct.image, ir.attachment-#0f0
position1:1product.image.sequenceNeues Feld sequence#F00

PriceObject

Für die Preisverwaltung wird eine Preisliste für den Webshop bei der Installation angelegt die nicht gelöscht werden kann. Preislisteneinträge die eine Mengenangabe haben, werden als PriceTierObject exportiert. Einträge ohne Mengenangabe werden als special Preis exportiert. Bei mehrfachen anzuwendenden Preisen, wird der niedrigste Preis exportiert.
Prio:
Artikel > Kategorie > Global

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
regularBerechnung, Normaler Preis wenn kein Webshoppreisproduct.pricelist-#0f0
specialBerechnung der möglichen Preiseproduct.pricelist-#F00
special_date_from1:1product.pricelist-#ff0
special_date_to1:1product.pricelist-#ff0
taxclassMappingtabelleproduct.product.tax_id.codeMapping#ff0
tiersarray of PriceTierObject--

PriceTierObject

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
pricelist_id1:1product.pricelist.id-#ff0
quantity1:1product.pricelist.item.min_quantity-#ff0
priceBerechnung der möglichen Preiseproduct.pricelist#F00

ProductProperties (Üersetzungen)

Übersetzungen befinden sich im Model ir.translation
Im Feld source steht die englische Übersetzung, die der anderen installierten Sprachen im Feld value

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
name1:1-Neues Feld für den Webshop Produktnamen. Begrenzung auf 255 Zeichen. Produktname wenn Webshopproduktname nicht vorhanden ist#ff0
short_description1:1product.template.description_saleHTML Sonderzeichen filtern#ff0
description1:1-Neues Textfeld#ff0
delivery-ready1:1-Neues Char Feld für product.template#0f0

VariationObject

JSON API FELDTransformationonRetail DatenquelleAnpassungAufwand
attributes1:1array of product.template.attribute_line_ids-#0f0
children1:1array of product.template.product_variant_ids-#0f0

ProductLinkObject

JSON API FELDTransformationonRetail DatenquelleAnpassung
type1:1depending on what we export: (upsell, crosssell or related)-
skus (type="upsell")1:1array of product.template.alternative_product_ids-
skus (type="crosssell")1:1-array of Neues m2m Feld
skus (type="related")1:1array of product.template.accessory_product_ids-