Zum Inhalt

Bestellungen anlegen

Die Bestellungen können über einen POST-Request über die URL /api/legacy/order angelegt werden. Das Ergebnis wird als Dataset zurückgeliefert.

Struktur

Parameter pflicht Beschreibung
companyOrderID ja Bestellnummer Mandant
shid ja Mandanten ID
user ja Kunde
sellTo ja Rechnungsadresse
shipTo nein Lieferadresse
positions ja Produkte
transactions nein Transaktionsdaten
notice nein Kunden Notiz
dcid nein ID der Lieferkonfition
sys nein Steuern der Verarbeitung nach dem anlegen der Bestellung

User

Hier werden die Kundendaten übergeben

Parameter Typ Beschreibung Beispiel
userName string Benutzername b2c@example.com
title string Titel Dr.
formOfAddress string Anrede Herr
letterFormOfAddress string Briefanrede Sehr geehrter Herr
firstName string Vorname Max
surName string Nachname Mustermann
birthday string Geburtstag 04.01.1977
custom1 string
custom2 string
company string Firma schukai GmbH
E-Mail string E-Mail-Adresse b2c@example.com
phone string Telefonnummer 12345-678910

sellTo

Adresse des Kunden. Diese wird als Rechnungsadresse verwendet.

Alternativ kann eine aid übergeben, es wird geprüft ob diese dem Kunden gehört, wenn diese nicht existiert oder nicht passt, kann die Bestellung nicht angelegt werden.

Parameter Typ Beschreibung Beispiel
aid integer ID der Adresse (optional) 269
address1 string Strasse und Hausnummer Eichenstrasse 26
address2 string Zusatz / CO Max Mustermann
zip string Postleitzahl 82290
city string Stadt Landsberied
country string Land ISO Code DE

shipTo

Lieferadresse des Kunden (optional) Wird keine Lieferadresse wird diese gleich der Rechnungsadresse gesetzt.

Parameter Typ Beschreibung Beispiel
aid integer ID der Adresse (optional) 269
address1 string Strasse und Hausnummer Eichenstrasse 26
address2 string Zusatz / CO Max Mustermann
zip string Postleitzahl 82290
city string Stadt Landsberied
country string Land ISO Code DE

positions

Die Parameter iid, optional und ean sind wie folgt zu betrachten: Wenn die Position über EAN referenziert wird , kann IID und optional leer gelassen werden.

Wenn die Position über IID referenziert wird, kann die ean oder optional leer gelassen werden.

Parameter Pflicht Typ Beschreibung Beispiel
iid nein, wenn ean übergeben integer Produkt ID 10026
optional nein, wenn ean übergeben string Größe / Variante S
ean nein, wenn ean optional integer EAN 4484442168293
count ja integer Menge 1
gross ja integer Brutto Preis 999
net ja integer Netto Preis 839
currency ja string Währung EUR
vat ja integer Steuersatz 1900
priceType nein
custom1 nein
custom2 nein
custom3 nein
name ja string Produkt Name T-Shirt - Baumwolle
itemNumber ja string Artikelnummer 10026
clientItemNumber nein string Artikelnummer des Mandanten 9465-8451-6
salesman nein integer Verkäufer UID 1
properties nein object Eigenschaften
voucherSOID nein integer Gutschein ID 1234
voucherPasswords nein array Passwörter werden als Array übergeben, denn beim anlegen bei Kaufgutscheinen müssen auch mehrere übergeben werden können ["9e526b4b-86ed-4c51"]
voucherSendMail nein string Um den gekauften Gutschein perE-Mailzu versenden, kann hier eineE-Mailübergeben werden mail@example.com
turnoverInfo nein object Informationen für eine Retoure

positions turnoverInfo

Informationen für eine Retoure

Parameter Typ Beschreibung Beispiel
orderReference string Rechnungsnummer der Bestellung 0001/02/1251
reason integer Grund 1

sys

Steuern der Verarbeitung nach dem anlegen der Bestellung

Parameter Typ Beschreibung Default Wert
reserverStockPositions boolean Reservieren der Bestände true
createDelivery boolean soll eine Lieferung erstellt werden false
setDelivered boolean soll die Lieferung gleich als ausgeliefert gesetzt werden false
setBillNumber boolean soll die Rechnungsnummer gestezt werden false
createEdiOrder boolean soll eine EDI Order erstellt werden false

transactions

Payment Transaktionen

Parameter Typ Beschreibung Beispiel
type integer authorize Code (shop_payment_authorize_response_reason_codes)
id string Transaction ID des Payment Providers
token string Feld zur identifizierung beim Payment Provider
amount integer Betrag der Transaktion 1995
currency string Währung EUR
authcode string Status der Autorisierung (Max 10 Zeichen) CAPTURED
authmsg string Max 100 Zeichen
result integer
captureState string Status der Buchung CAPTURED
captureAmount integer Gebuchter Betrag 1995
resultData array Ergebnis Daten / Rückanwort des Providers die für die spätere Verarbeitung benötigt werden []
resultText string
erpID string
paymentPTID integer Payment Type ID

Über die paymentPTID wird geprüft ob der Kunde diese Bezahlart schon verwendet hat, wenn nicht wird eine neue Bezahlart angelegt. Die so ermittelte PID aus der sh_payment Tabelle wird in den Transaktionen gespeichert.

Mögliche Status der Autorisierung

authcode Beschreibung
ACCEPTED Transaktion wurde autorisiert
CAPTURED Transaktion wurde eingezogen
CANCELED Transaktion wurde storniert

Mögliche Status der Buchung

captureState Beschreibung
CAPTURED Buchung wurde durchgeführt
CANCELED Buchung wurde storniert

Beispiele für Transaktionen

In diesen Beispielen gehen wir davon aus, das die Bezahlarten mit diesen PTIDs angelegt wurden.
Die Buchungen wurden bereits eingezogen, alle Transaktionen haben einen finalen Status.

PTID Bezahlart
1 Kreditkarte
2 Nachnahme
3 Vorauskasse
5 Rechnung
11 PayPal
21 Amazon Pay
41 Ideal

Kreditkarte

{
"transactions": [
    {
      "id" : "CECfQ...",
      "authcode" : "CAPTURED",
      "captureState" : "CAPTURED",
      "amount" : "999",
      "currency" : "EUR",
      "paymentPTID": 1
    }
  ]
}

Nachnahme

{
"transactions": [
    {
      "paymentPTID": 2
    }
  ]
}

Vorauskasse

{
"transactions": [
    {
      "paymentPTID": 3
    }
  ]
}

Rechung

{
"transactions": [
    {
      "paymentPTID": 5
    }
  ]
}

PayPal

{
"transactions": [
    {
      "id": "CECfQ...",
      "token": "EC-6F664............",
      "amount": "999",
      "currency": "EUR",
      "authcode": "CAPTURED",
      "captureState": "CAPTURED",
      "captureAmount": "999",
      "paymentPTID": 11
    }
  ]
}

Amazon Pay

{
"transactions": [
    {
      "id": "CECfQ...",
      "amount": "999",
      "currency": "EUR",
      "authcode": "CAPTURED",
      "captureState": "CAPTURED",
      "captureAmount": "999",
      "paymentPTID": 21
    }
  ]
}

Ideal

{
"transactions": [
    {
      "paymentPTID": 41
    }
  ]
}

Beispiel

Ein komplettes Beispiel um eine Bestellung anzulegen mit der Bezahlart Rechnung

{
  "companyOrderID": "0001/01/0f001",
  "billNumber": "0001/01/00001",
  "notice": "Das ist eine Kassen Bestellung",
  "shid": 1,
  "transactions": [
    {
      "paymentPTID": 5
    }
  ],
  "user": {
    "userName": "[email protected]",
    "formOfAddress": "Herr",
    "title": "Dr.",
    "firstName": "Max",
    "surName": "Mustermann",
    "letterFormOfAddress": "Sehr geehrter Herr",
    "birthday": "04.01.1977",
    "custom1": "",
    "custom2": "",
    "company": "schukai GmbH",
    "email":"[email protected]",
    "phone":"12345-678910"
  },
  "sellTo": {
    "address1": "Eichenstrasse 26",
    "address2": "",
    "zip": "82290",
    "city": "Landsberied",
    "country": "de"
  },
  "shipTo":{
    "address1": "Eichenstrasse 26",
    "address2": "",
    "zip": "82290",
    "city": "Landsberied",
    "country": "de"
  },
  "positions": [
    {
      "iid": "10026",
      "optional": "S",
      "ean": "4484442168293",
      "count": 1,
      "gross": 999,
      "net": 839,
      "currency": "EUR",
      "vat": 1900,
      "priceType": "",
      "custom1": "",
      "custom2": "",
      "custom3": "",
      "name": "T-Shirt - Baumwolle",
      "itemNumber": "10026",
      "salesman": 1,
      "properties":[
        {
            "name":"shoppingcard.erp.discounttype",
            "value":"3"
        },
        {
            "name":"my.property",
            "value":"myValue"
        }
        ]
    },
    {
      "iid": "502",
      "count": 1,
      "gross": 395,
      "net": 332,
      "currency": "EUR",
      "vat": 1900,
      "name": "Versand",
      "itemNumber": "Versand",
    }
  ],
  "sys": {
    "reserverStockPositions": true,
    "createDelivery": true,
    "setDelivered":true,
    "setBillNumber": true,
    "createEdiOrder": false
  }
}

Rückgabe

{
    "dataset": [
        {
            "dataset": {
                "oid": 1028,
                "uid": 249,
                "errorCode": null,
                "error": [],
                "createDelivery": true,
                "orderStatus": "51",
                "setBillNumber": true,
                "createEdiOrder": false,
                "reserverStockPositions": true,
                "setDelivered": true
            },
            "sys": {
                "message": "201 Created",
                "code": 201
            }
        }
    ],
    "sys": {
        "message": "201 Created",
        "code": 201
    }
}

Mehrere Bestellungen anlegen

Mehere Bestellungen können über ein Dataset übergeben werden

{
  "dataset": {
    "0": {
      "companyOrderID": "0001/01/00001",
      "billNumber": "0001/01/00001",
      "notice": "",
      "shid": 1,
      "user": {},
      "sellTo": {},
      "shipTo": null,
      "positions": [],
      "sys": {}
    },
    "1": {
      "companyOrderID": "0001/01/00002",
      "billNumber": "0001/01/00002",
      "notice": "",
      "shid": 1,
      "user": {},
      "sellTo": {},
      "shipTo": null,
      "positions": [],
      "sys": {}
    },
  }
}

Fehlermeldungen

Werte fehlen

Wenn Werte nicht übergeben wurden wir der Stautscode 400 gesendet

{
    "dataset": [
        {
            "sys": {
                "error": {
                    "code": 400,
                    "message": "400 Bad Request"
                }
            }
        }
    ],
    "sys": {
        "error": {
            "code": 400,
            "message": "400 Bad Request"
        }
    }
}

Bestellung gibt es schon

Bestellung wurde schon angelegt, hier wird der Statuscode 409 gesendet

{
    "dataset": [
        {
            "sys": {
                "error": {
                    "code": 409,
                    "message": "409 Conflict"
                }
            }
        }
    ],
    "sys": {
        "error": {
            "code": 409,
            "message": "409 Conflict"
        }
    }
}

Fehler Prodkt wurde nicht gefunden

Die Bestellung wird auf fehlerhaft gesetzt, wenn Positionen nicht gefunden wurden

{
    "dataset": [
        {
            "dataset": {
                "OID": 1033,
                "errorCode": null,
                "error": [
                    "IID 2 wurde nicht gefunden."
                ],
                "createDelivery": false,
                "orderStatus": "11",
                "setBillNumber": false,
                "createEdiOrder": false,
                "reserverStockPositions": true,
                "setDelivered": false
            },
            "sys": {
                "message": "201 Created",
                "code": 201
            }
        }
    ],
    "sys": {
        "message": "201 Created",
        "code": 201
    }
}

Fehler bei mehreren Bestellungen

Es können auch mehrere Bestellungen in einem Request angelegt werden, wenn es bei einigen zu Fehlern kommt wird im Dataset an der entsprechenden Stelle der exakte Fehlerstatus gesendet. Im sys Teil wird der Statuscode 400 gesendet, wenn nicht alle Statuscodes im Dataset identisch sind.

{
    "dataset": [
        {
            "sys": {
                "error": {
                    "code": 409,
                    "message": "409 Conflict"
                }
            }
        },
        {
            "dataset": {
                "OID": 1029,
                "errorCode": null,
                "error": [],
                "createDelivery": true,
                "orderStatus": "51",
                "setBillNumber": true,
                "createEdiOrder": false,
                "reserverStockPositions": true,
                "setDelivered": true
            },
            "sys": {
                "message": "201 Created",
                "code": 201
            }
        }
    ],
    "sys": {
        "error": {
            "code": 400,
            "message": "400 Bad Request"
        }
    }
}

Bestellbestätigung

Nach dem die Bestellung angelegt wurde, wird das Event orderMail aus dem Interface shop_addon_order_send_message angelegt, um die Bestellbestätigung zu versenden.
Das Land in das versendet wird, definiert die Sprache der eMail.
Es wird in den angelegten Ländern nachgeschlagen, wie dort die Sprache definiert ist.

Listen

In der Liste shop_addon_order_confirmationmail_mapping wird definiert bei welcher Bezahlart (PTID) welche Nachricht versendet wird. 

<?php
/**
 * Payment Type IDs
 * Angelegte Bezahlungen > Name der Nachichtenvorlage
 */
$list['1']='Bestellbestätigung (Kreditkarte)';
$list['2']='Bestellbestätigung (Nachnahme)';
$list['3']='Bestellbestätigung (Vorauskasse)';
$list['5']='Bestellbestätigung (Rechnung)';
$list['11']='Bestellbestätigung (PayPal)';