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.
Wenn die Kontakt Person dieser Adresse nicht mit dem Benutzer übereinstimmt, kann dieser über title, firstName und surName übergeben werden.

Parameter	Typ	Beschreibung	Beispiel
aid	integer	ID der Adresse (optional)	269
title	string	Titel (optional)	Dr.
firstName	string	Vorname (optional)	Max
surName	string	Nachname (optional)	Mustermann
address1	string	Strasse und Hausnummer	Eichenstrasse 26
address2	string	Zusatz / CO	Max Mustermann
zip	string	Postleitzahl	82290
city	string	Stadt	Landsberied
company	string	Firma (optional)	schukai GmbH
country	string	Land ISO Code	DE

shipTo

Lieferadresse des Kunden (optional) Wird keine Lieferadresse wird diese gleich der Rechnungsadresse gesetzt. Wenn die Kontakt Person dieser Adresse nicht mit dem Benutzer übereinstimmt, kann dieser über title, firstName und surName übergeben werden.

Parameter	Typ	Beschreibung	Beispiel
aid	integer	ID der Adresse (optional)	269
title	string	Titel (optional)	Dr.
firstName	string	Vorname (optional)	Max
surName	string	Nachname (optional)	Mustermann
address1	string	Strasse und Hausnummer	Eichenstrasse 26
address2	string	Zusatz / CO	Max Mustermann
zip	string	Postleitzahl	82290
city	string	Stadt	Landsberied
company	string	Firma (optional)	schukai GmbH
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
sendOrderingConfirmationMail	boolean	soll eine Bestellbestätigung gesendet werden	true

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,
    "sendOrderingConfirmationMail": true
  }
}

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)';