JSON Schnittstelle

Bestellungen ("orders"):

Aufbau:

"orders": array of `OrderObject`

OrderObject:

Property name

Description

Definition

id

Webshop Order Number

string, max 255 characters, unique

created_at_utc

Order creation date

format utc with timezone

updated_at_utc

Order update date

datetime, format utc with timezone

status

Webshop Order Status

string

shipping_method

ShippingObject

Versandart

currency

Currency Code (nur info wie der Kunde bezahlt, die Line items sind immer in Euro)

3 characters

comment

Customer order comment

string, max. 255 characters, optional

taxmodel

Kennzeichen ob Brutto oder Netto verrechnet wurde: Preisangaben in Line items sind dann auch brutto od netto

"GROSS" or "NET"

_payment

OrderPaymentObject

Zahlungsinformation

_lines

array of OrderLineObject

Rechnungszeilen (Produkt, Versandkosten, Rabatte, Gesamtsumme)

_shipping_address

OrderAddressObject

Versandadresse des Kunden (optional bei Bestellungen ohne materielle Güter)

_billing_address

OrderAddressObject

Rechnungsadresse 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 name

Description

Definition

type

Webshop Shipping Method Identifier

string, max 255 characters

description

Description information for shipping method (like address if packup at store)

string, max 255 characters, optional

OrderPaymentObject

Property name

Description

Definition

method

Webshop Payment Method Identifier

string, max 255 characters One of cc, paypal, sofort, invoice, banktransfer, cod

cctype

Type of credit card (various)

string, max 255 characters, if method="cc" One of Visa, MC/MasterCard, Amex (exact values may vary)

OrderLineObject

Property name

Description

Definition

type

Type of line item

one of "product", "shipping", "discount", "total" (is special because all other lines sum up to equal total line)

is_line

Flag whether line should appear in billing documents

true (if type=product or shipping) / false (if type=discount or total)

quantity

Line item quantity

numeric, needed if type="product"

sku

SKU of product

needed if type="product"

name

Name of product

needed if type="product", string max 255 characters

unitprice

Base 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_amount

Discount calculated on product line

optional if type="product", decimal, 2 decimals if order taxmodel="GROSS", 4 decimals precision of order taxmodel="NET"

amount

Line 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_amount

Tax amount of line price

(tax of amount) needed if type="product", decimal, 2 decimals if order taxmodel="GROSS", 0 if order taxmodel="NET"

taxclass

Tax class identifier of product

string

OrderAddressObject

Property name

Description

Definition

id

Webshop Address Entry ID

numeric

salutation

Customer Prefix (Mr,Mrs,Herr,Frau)

string, max 255 characters, optional

firstname

Customer First Name

string, max 255 characters

lastname

Customer Last Name

string, max 255 characters

street

Customer Street Address

string, max 255 characters. May contain "\n" for line breaks

zip

Customer ZIP

string, max 255 characters

city

Customer City

string, max 255 characters

country

Customer Country Code

2 characters ISO Country code

company

Customer Company Name Code

string, max 255 characters, optional

email

Customer eMail Address

string, max 255 characters

phone

Customer Phone Number

string, max 255 characters, optional

vat_id

Customer VAT Number

string, max 255 characters, optional

Mapping Tabelle, Anforderungen onRetail

OrderObject

JSON API FELD

Transformation

onRetail Datenziel

Anpassung

Related US

id

1:1

-

Neues Feld für die Webshop Order ID

created

Umwandlung zu Datetime

sale.order.create_date

-

updated

Umwandlung zu Datetime

sale.order.write_date

-

status

Mapping Tabelle

-

sale.order Stati auf die des Webshops mappen

shipping_method

Mapping Tabelle

delivery.carrier

-

currency

Mapping Tabelle

res.currency

-

comment

1:1

-

Neues Feld

taxmodel

1:1

-

Neues Feld, Berechnung der Preise

_payment

OrderPaymentObject

-

_lines

array of OrderLineObject

_shipping_address

OrderAddressObject

_billing_address

OrderAddressObject

OrderPaymentObject

JSON API FELD

Transformation

onRetail Datenziel

Anpassung

Related US

method

Mapping Table

-

Mapping Table

additional_information

Mapping Table

-

Mapping Table. Bei Info success, Zahlung zur sale.order hinzufügen

OrderLineObject

JSON API FELD

Transformation

onRetail Datenziel

Anpassung

Related US

type

-

sale.order

Versandkosten/Rabatt zuordnen

quantity

1:1

sale.order.line.product_uom_qty

-

sku

1:1

sale.order.line.product_id

-

name

-

sale.order.line.product_id.name

Feld verwerfen, Name ist abhängig von der gewählten Sprache

unitprice

1:1

sale.order.line.price...

Berechnung/Datenziel abhängig vom Typ

amount

1:1

sale.order.line.price_subtotal

-

tax_amount

1:1

-

Neues Feld, Berechnung der Steuer durch onRetail muss möglicherweise umgangen werden

taxclass

1:1

product.product.tax_id.code

-

OrderAddressObject

JSON API FELD

Transformation

onRetail Datenziel

Anpassung

Related US

id

1:1

-

Neues Feld für die Webshop Kunden ID

prefix

Mapping Table

res.partner.title

Mapping

firstname

Concat

res.partner.name

Vor- und Nachname zuammenführen

lastname

Concat

res.partner.name

Vor- und Nachname zuammenführen

street

String Bereinigen

res.partner.street

-

zip

1:1

res.partner.zip

-

city

1:1

res.partner.city

-

country

1:1

res.partner.country_id.code

-

company

Neuanlage Unternehmen bei Neukunden, ansonsten Feld verwerfen

res.company

Weshop Kunden ID

email

1:1

res.partner.email

-

phone

1:1

res.partner.phone

-

vat

1:1

res.partner.vat

-

Bestellstatus "orderstatus"

Aufbau

"orderstatus": array of `OrderStatusObject`

OrderStatusObject

Property name

Description

Definition

id

Webshop Order Number

numeric

status

Order 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 FELD

Transformation

onRetail Datenquelle

Anpassung

Related US

id

1:1

-

Neues Feld für die Webshop Order ID

status

Mapping Table

sale.order.state

sale.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 name

Description

Definition

id

Eindeutiger Schlüssel für Kategorie

alphanumeric string, unique, max 255 characters

name

Kategoriename

string (utf8), max 255 characters

parent_id

Referenz auf einen eindeutigen Schlüssel einer Kategorie

alphanumeric string

position

Position/Reihenfolge der Kategorie innerhalb der Hierarchie (Elemente mit gleichem parent_id)

numeric, unsigned int

visible

true=Kategorie ist sichtbar im Menü, false=Kategorie ist nicht sichtbar im Menü

boolean

image

relativer Pfad zum Kategorie-Bild am Bilderspeicher

url, optional

onRetail Anforderungen

Mapping Tabelle, Anforderungen onRetail

CategoryObject:

JSON API FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

id

1:1

product.public.category.id

-

#0f0

name

1:1

product.public.category.name

Begrenzung auf 255 Zeichen, HTML Sonderzeichen filtern

#0f0

parent_id

1:1

product.public.category.parent_id

-

#0f0

position

1:1

product.public.category.sequence

-

#0f0

visible

1:1

-

visible Attribut zur Kategorie hinzufügen

#ff0

image

1:1

product.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 name

Description

Definition

sku

eindeutige Produktkennung

alphanumeric string, unique, max 255 characters

weight

Produktgewicht in kg

decimal

status

Produkt-Freigabe für Webshop: 1=freigegeben, 0=nicht freigegeben

numeric

stock

Lagerstand für Webshop

numeric

barcodes

Mit Komma getrennte EAN Liste

string (utf8) Zahlen, Komma und Leerzeichen erlaubt

new_date_from

Datum für "Neu ab"

date, format YYYY-MM-DD, optional, new-to > new-from

new_date_to

Datum für "Neu bis"

date, format YYYY-MM-DD, optional, new-to > new-from

featured

Markierung

true/false

sale_stepping

Mengenangabe in der das Produkt verkauft werden darf. Verkaufte Menge muss ein Vielfaches der Mengenabgabe sein.

numeric >=1, Standardwert 1

manufacturer

Manufacturer Name

string(utf8)

manufacturer_link

Link zur Produktseite des Herstellers

string(utf8)

_categories

array of CategoryObject

(optional)

_images

array of ImageObjects, Pfade/Urls zu den Bildern

_price

PriceObject

_linked_skus

array of ProductLinkObject

Produktverknüpfungen für Up-, Cross-selling und Related Products

_scopes

array of ProductProperties

Übersetzungen von Produktfeldern

_variation_config

VariationObject

nur 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 name

Description

Definition

url

url zum Produktbild

string(utf8)

position

Position/Reihung des Bildes

numeric, ganze Zahl

PriceObject

Property name

Description

Definition

regular

normaler Webshop Verkaufspreis (netto)

decimal, 4 decimals precision

special

reduzierter Webshop Sonderpreis (netto)

decimal, 4 decimals precision, optional

special_date_from

Datum ab Gültigkeit Sonderpreis

date, format utc with timezone, optional

special_date_to

Datum bis Gültigkeit Sonderpreis

date, format utc with timezone, optional

taxclass

Kennzeichen für Steuerklasse (wird auf Gateway gemappt)

alphanumeric string, max 255 chars

_tiers

array of PriceTierObject

optional

PriceTierObject

Property name

Description

Definition

pricelist_id

Kundengruppen-Kennung (wird auf Gateway gemappt). "0" or "" (empty) = allgemeine Preisstaffel (nicht kundengruppenabhängig)

alphanumeric string, optional

quantity

Ab Menge (bei Staffelpreis), sonst 1

numeric, min. 1

price

Preis netto

decimal, 4 decimals precision

ProductProperties

Liste aller übersetzten Felder eines Produktes

Property name

Description

Definition

name

Produktname

string (utf8), max 255 chars

short_description

Webshop Kurzbeschreibung

string (utf8)

description

Webshop Langbeschreibung

string (utf8)

delivery-ready

Text für "Versandbereit in" Angabe

string (utf8)

VariationObject

Property name

Description

Definition

attributes

array of attribute names

Liste der Attributnamen, welche die Konfiguration des Artikels bestimmen

children

array of product SKUs

Liste 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 name

Description

Definition

type

Type of the listed SKUs

can be "upsell", "crosssell" or "related" (Upselling, Crossselling oder Zubehoer Produkte)

skus

array of product SKUs

Liste 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 FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

sku

1:1

product.product.default_code

-

#0f0

weight

1:1

product.product.weight

-

#0f0

status

1:1

-

Neues Feld product.template.webshop_active

#ff0

stock

Summe 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

barcodes

1:1

product.template.barcodes

barcodes Feld zu product.product hinzufügen

#0f0

new_date_from

1:1

-

Neues Datum Feld in product.template

#0f0

new_date_to

1:1

-

Neues Datum Feld in product.template

#0f0

featured

1:1

-

Neues bool Feld in product.template

#0f0

sale_stepping

1:1

-

Neues Feld

#0f0

manufacturer

1:1

manufacturer.manufacturer.name

Neues Model für Hersteller

manufacturer_link

1:1

product.manufacturer_url

Neues Feld

_categories

CategoryObject

product.template.public_categ_ids

-

_images

1:1

product.template/product.image_ids

Mehrere Bilder im Template und der Variante hinterlegen

#ff0

_price

PriceObject

-

-

_linked_skus

array of ProductLinkObject

-

-

_scopes

array of ProductProperties

-

-

_variation_config

array of VariationObject

-

Auflösen der vorhandenen Attribute von product.template

ImageObject

JSON API FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

url

url generieren

product.image, ir.attachment

-

#0f0

position

1:1

product.image.sequence

Neues 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 FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

regular

Berechnung, Normaler Preis wenn kein Webshoppreis

product.pricelist

-

#0f0

special

Berechnung der möglichen Preise

product.pricelist

-

#F00

special_date_from

1:1

product.pricelist

-

#ff0

special_date_to

1:1

product.pricelist

-

#ff0

taxclass

Mappingtabelle

product.product.tax_id.code

Mapping

#ff0

tiers

array of PriceTierObject

-

-

PriceTierObject

JSON API FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

pricelist_id

1:1

product.pricelist.id

-

#ff0

quantity

1:1

product.pricelist.item.min_quantity

-

#ff0

price

Berechnung der möglichen Preise

product.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 FELD

Transformation

onRetail Datenquelle

Anpassung

Aufwand

name

1:1

-

Neues Feld für den Webshop Produktnamen. Begrenzung auf 255 Zeichen. Produktname wenn Webshopproduktname nicht vorhanden ist

#ff0

short_description

1:1

product.template.description_sale

HTML Sonderzeichen filtern

#ff0

description

1:1