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