Order

Über den Order-Endpunkt können sie einerseits Ihre Bestelldaten direkt aus Ihrem Online-Shop in unser System übertragen. Andererseits können sie sich auch einen Status dieser Bestellungen abrufen. Dieser Status beinhaltet zum Beispiel die Trackingnummer des Schweizer Versandunternehmens, welche Sie dann an Ihre Kunden zum Verfolgen der Lieferung weitergeben können.

Endpunkt URL

https://api.meineinkauf.ch/v1/order

POST

POST https://api.meineinkauf.ch/v1/order

Um eine Bestellung per POST über unsere API anzulegen, müssen die Daten im JSON-Format als Request-Data übermittelt werden. Im folgenden wird die Struktur des JSON-Objekts beschrieben.

Bestellung (Order-Object)

Name Typ Beispiel Pflichtfeld Hinweis
orderNumber String 1518180120 Ja Ihre Bestellnummer
orderDate String 2018-02-21 Ja Das Bestelldatum im Format "YYYY-MM-DD" ISO-8601 (MEZ/MESZ)
currency Enum[String] EUR Ja Die Währung der Bestellung

["eur", "chf"]
paymentType Enum[String] prepayment Ja Die Zahlart, z.B. Kreditkarte, Paypal, Vorkasse, Rechnung etc.

["mastercard", "visa", "amex", "creditcard", "paypal", "prepayment", "invoice", "other"]
grossSum Number 69.97 Ja Die Brutto Bestellsumme (inklusive Lieferkosten)
shippingCost ShippingCost-Object Nein Die Lieferkosten
customer Customer-Object Ja Die Kundendaten
invoiceAddress Address-Object Ja Die Rechnungsadresse
shippingAddress Address-Object Nein Die Lieferadresse, wenn leer, wird die Rechnungsadresse als Lieferadresse genutzt
consignments Array [Consignment-Object] Ja Für jede Sendung, die wir von Ihnen erhalten, muss ein Sendungs-Objekt in dem Array enthalten sein
discounts Array [Discount-Object] Nein Die möglichen Rabatte auf die Bestellung
donations Array [Donation-Object] Nein Die möglichen Spenden zusätlich zur Bestellung
invoiceInformation InvoiceInformation-Object Nein Informationen zur Rechnungsstellung

Lieferkosten (ShippingCost-Object)

Name Typ Beispiel Pflichtfeld Hinweis
grossPrice Number 10.0 Ja Die Lieferkosten, Pflicht wenn ShippingCost-Object vorhanden
vatRate Enum[String] standard Ja Der Mehrwertsteuerklassifizierung der Versandkosten

[ "standard", "reduced", "none" ]

Kunde (Customer-Object)

Name Typ Beispiel Pflichtfeld Hinweis
customerNumber String kunde1234 Ja Eine eindeutige Refernz auf Ihren Kunden, z.B. die Kundennummer
contactEmail String max@muster.de Nein Kontakt-Email-Adresse des Kunden z.B. für den Avisierungsservice der SwissPost

Adresse (Address-Object)

Name Typ Beispiel Pflichtfeld Hinweis
company String Muster GmbH Nein Die Firma des Kunden
salutation Enum[String] Frau Ja Die Anrede des Kunden

["Herr", "Frau"]
title String Dr. Nein Der Titel des Kunden
firstName String Erika Ja Der Vorname des Kunden
lastName String Musterfrau Ja Der Nachname des Kunden
street String Musterstrasse Ja* Die Straße des Kunden

* Pflicht, wenn Adresse in der Schweiz oder Liechtenstein
houseNumber String 28a Nein* Die Hausnummer des Kunden

* Nur zulässig, wenn Adresse in der Schweiz oder Liechtenstein
addressLine String 140 Av. des Champs-Élysées Nein* Die Adresszeile

* Pflicht, wenn Adresse nicht in der Schweiz oder Liechtenstein
additionalAddressLine String Im Hinterhof Nein Zusätzlicher Adresshinweis
zip String 8005 Ja Die Postleitzahl des Kunden
city String Zürich Ja Die Stadt des Kunden
state String Zürich Nein* Der Verwaltungsbereich des Kunden (z.B. Kanton, Gemeinde, Bezirk, Insel, etc)

* Pflicht, wenn die Adresse in dem entsprechenden Land dies erfordert
country String CH Nein Der Ländercode nach ISO-3166-1 Alpha-2 Standard

Default: CH

Hinweis: Sollte die Rechnungsadresse in der Schweiz oder Liechtenstein liegen, muss die Straße in der Eigenschaft "street" übergeben werden und die Hausnummer optional in der Eigenschaft "houseNumber". Falls die Rechnungsadresse nicht in der Schweiz oder Liechtenstein liegt, muss die Straßenanschrift entsprechend des Länderformats in der Eigenschaft "addressLine" übergeben werden. Die Lieferadresse muss zwangsläufig in der Schweiz oder Liechtenstein liegen.

Sendung (Consignment-Object)

Name Typ Beispiel Pflichtfeld Hinweis
grossWeight Number 1500.0 Nein Das Bruttogewicht der Sendung
tracking Tracking-Object Nein Die deutschen Tracking-Informationen
articles Array[Article-Object] Ja Für jeden Artikel in der Sendung, muss es ein Artikel-Objekt in dem Array enthalten sein

Tracking-Informationen (Tracking-Object)

Name Typ Beispiel Pflichtfeld Hinweis
carrier String dhl Nein Der deutsche Lieferdienst der Sendung von Ihnen zu uns.
trackingNumber String 67039131139123 Nein Die deutsche Trackingnummer der Sendung von Ihnen zu uns. Dies dient für uns zur Identifizierung der eingehenden Sendung zur Bestellung

Artikel (Article-Object)

Name Typ Beispiel Pflichtfeld Hinweis
articleNumber String 12345678 Ja Die Artikelnummer
name String Gelbes Hemd Ja Der Name des Arikels
quantity Integer 2 Ja Die Anzahl des Artikels in der Sendung
grossWeight Number 500.0 Nein Das Bruttogewicht eines Artikels
grossPrice Number 19.99 Ja Der Bruttopreis des Artikels
vatRate Enum[String] standard Ja Die Mehrwertsteuerklassifizierung des Artikels

[ "standard", "reduced", "none" ]
attributes Attributes-Object Nein Zusätzliche Attribute des Artikels

Artikel-Attribute (Attributes-Object)

Name Typ Beispiel Pflichtfeld Hinweis
color String rot Nein Die Farbe des Artikels
description String Lorem ipsum Nein Eine Beschreibung des Artikels
material String 70% Viskose, 30% Leinen Nein Das Material des Artikels
url String https://example.com/12345679/ Nein Die URL zur Shop-Seite des Artikels
ean String 590123412345 Nein Die EAN des Artikels
upc String 036000291452 Nein Der UPC des Artikels
asin String B005Z75C92 Nein Die ASIN des Artikels
customIdentCode String ABC1234 Nein Kundenspezifischer Identcode des Artikels
size String XL Nein Die Größe des Artikels

Rabatte (Discount-Object)

Name Typ Beispiel Pflichtfeld Hinweis
name String Ihr Rabatt Ja Der Name des Rabatts
grossPrice Number -10.00 Ja Der Bruttopreis des Rabatts, Achtung: negativer Wert
vatRate Enum[String] standard Ja Die Mehrwertsteuerklassifizierung des Rabatts

[ "standard", "reduced", "none" ]

Spenden (Donation-Object)

Name Typ Beispiel Pflichtfeld Hinweis
name String Ihre Spende Ja Der Name der Spende
grossPrice Number 10.00 Ja Der Bruttopreis der Spende
vatRate Enum[String] none Ja Die Mehrwertsteuerklassifizierung der Spende

[ "standard", "reduced", "none" ]

Rechnungsinformationen (InvoiceInformation-Object)

Name Typ Beispiel Pflichtfeld Hinweis
invoiceDate String 2018-02-21 Nein Das Rechnungsdatum der Rechnung für den Endkunden im Format "YYYY-MM-DD" ISO-8601 (MEZ/MESZ), falls nicht gesetzt, wird das Bestelldatum genommen
dueDate String 2018-03-21 Nein Das Fälligkeitsdatum der Rechnung für den Endkunden im Format "YYYY-MM-DD" ISO-8601 (MEZ/MESZ), falls nicht gesetzt, wird das Rechnungsdatum plus 20 Tage genommen
additionalInvoiceText String Vielen Dank! Nein Ein zusätzlicher Freitext auf der Rechnung
esrInformation EsrInformation-Object Nein* Die Informationen für den Einzahlungsschein

*Pflicht wenn Zahlart Rechnung

ESR Informationen (EsrInformation-Object)

Name Typ Beispiel Pflichtfeld Hinweis
referenceNumber String 12345678 Ja Die Referenznummer des Einzahlungsscheins, maximal 26 numerische Zeichen lang (abzüglich bankAccount Länge), ohne Prüfziffer, diese wird von uns erstellt.

Regex-Pattern: "/^[0-9]+$/"
bankName String Raiffeisenbank St. Gallen Nein* Der Name der Bank

*Pflicht wenn Konto nicht bei PostFinance
bankZip String 9001 Nein* Die Postleitzahl der Bank

*Pflicht wenn Konto nicht bei PostFinance
bankCity String St. Gallen Nein* Die Stadt der Bank

*Pflicht wenn Konto nicht bei PostFinance
bankAccount String 1234567890 Nein* Die Kontonummer bei der Bank

Regex-Pattern: "/^[0-9]+$/"

*Pflicht wenn Konto nicht bei PostFinance
postAccount String 01-12345-1 Ja Die Identifizierung der Bank der Postbank
recipientName String Musterfirma GmbH Ja Der Name des Empfängers
recipientStreet String Musterstrasse Ja Die Strasse des Empfängers
recipientHouseNumber String 1a Ja Die Hausnummer des Empfängers
recipientZip String D-12345 Ja Die Postleitzahl des Empfängers
recipientCity String Musterstadt Ja Die Stadt des Empfängers

Beispiel JSON

{
  "orderNumber": "1518180120",
  "orderDate": "2018-02-21",
  "currency": "eur",
  "paymentType": "prepayment",
  "grossSum": 69.97,
  "shippingCost": {
    "grossPrice": 10.0,
    "vatRate": "standard"
  },
  "customer": {
    "customerNumber": "kunde1234",
    "contactEmail": "max@muster.de"
  },
  "invoiceAddress": {
    "company": "Muster GmbH",
    "salutation": "Frau",
    "title": "Dr.",
    "firstName": "Erika",
    "lastName": "Musterfrau",
    "street": "Musterstrasse",
    "houseNumber": "28a",
    "zip": "8005",
    "city": "Zürich",
    "state": "Zürich"
  },
  "shippingAddress": {
    "company": "Muster GmbH",
    "salutation": "Frau",
    "title": "Dr.",
    "firstName": "Erika",
    "lastName": "Musterfrau",
    "street": "Musterstrasse",
    "houseNumber": "28a",
    "zip": "8005",
    "city": "Zürich",
    "state": "Zürich"
  },
  "consignments": [
    {
      "grossWeight": 1500.0,
      "tracking": {
        "carrier": "dhl",
        "trackingNumber": "67039131139123"
      },
      "articles": [
        {
          "articleNumber": "12345678",
          "name": "Gelbes Hemd",
          "quantity": 2,
          "grossWeight": 500.0,
          "grossPrice": 19.99,
          "vatRate": "standard",
          "attributes": {
            "color": "gelb",
            "description": "Ein gelbes Hemd lorem ipsum",
            "material": "100% Baumwolle",
            "url": "https://example.com/12345678/",
            "ean": "590123412345",
            "upc": "036000291452",
            "asin": "B005Z75C92",
            "size": "XL"
          }
        },
        {
          "articleNumber": "12345679",
          "name": "Rotes Hemd",
          "quantity": 1,
          "grossWeight": 500.0,
          "grossPrice": 19.99,
          "vatRate": "standard",
          "attributes": {
            "color": "rot",
            "description": "Ein rotes Hemd lorem ipsum",
            "material": "70% Viskose, 30% Leinen",
            "url": "https://example.com/12345679/",
            "ean": "590123412346",
            "upc": "036000291453",
            "asin": "B005Z75C93",
            "size": "M"
          }
        }
      ]
    }
  ],
  "discounts": [
    {
      "name": "Ihr Rabatt",
      "grossPrice": -10.00,
      "vatRate": "standard"
    }
  ],
  "donations": [
    {
      "name": "Ihre Spende",
      "grossPrice": 10.00,
      "vatRate": "none"
    }
  ],
  "invoiceInformation": {
    "invoiceDate": "2018-02-21",
    "dueDate": "2018-03-21",
    "additionalInvoiceText": "Vielen Dank für Ihre Bestellung",
    "esrInformation": {
      "referenceNumber": "123456789",
      "bankName": "Raiffeisenbank St. Gallen",
      "bankZip": "9001",
      "bankCity": "St. Gallen",
      "bankAccount": "1234567890",
      "postAccount": "01-12345-1",
      "recipientName": "Musterfirma GmbH",
      "recipientStreet": "Musterstrasse",
      "recipientHouseNumber": "1a",
      "recipientZip": "D-12345",
      "recipientCity": "Musterstadt"
    }
  }
}

Beispiel Aufruf

curl https://api.meineinkauf.ch/v1/order \
  -X POST \
  -u 'api:MEINEINKAUF_TEST_API_KEY' \
  -H 'content-type: application/json' \
  -d '{"orderNumber":"1518180120","orderDate":"2018-02-21","currency":"eur","paymentType":"prepayment","grossSum":69.97,"shippingCost":{"grossPrice":10.0,"vatRate":"standard"},"customer":{"customerNumber":"kunde1234","contactEmail":"max@muster.de"},"invoiceAddress":{"company":"Muster GmbH","salutation":"Frau","title":"Dr.","firstName":"Erika","lastName":"Musterfrau","street":"Musterstrasse","houseNumber":"28a","zip":"8005","city":"Zürich","state":"Zürich"},"consignments":[{"grossWeight":1500.0,"tracking":{"carrier":"dhl","trackingNumber":"67039131139123"},"articles":[{"articleNumber":"12345678","name":"Gelbes Hemd","quantity":2,"grossWeight":500.0,"grossPrice":19.99,"vatRate":"standard"},{"articleNumber":"12345679","name":"Rotes Hemd","quantity":1,"grossWeight":500.0,"grossPrice":19.99,"vatRate":"standard"}]}]}'

Antwort

{
    "errors": [],
    "success": true
}

GET - einzelne Bestellung

GET https://api.meineinkauf.ch/v1/order/<orderNumber>

Parameter

Name Beispiel Pflichtfeld Hinweis
orderNumber 1518180120 Ja Ihre Bestellnummer

Beispiel Aufruf

curl https://api.meineinkauf.ch/v1/order/1518180120 \
  -X GET \
  -u 'api:MEINEINKAUF_TEST_API_KEY'

Antwort

{
    "order": {
        "id": 1234,
        "created": "2019-02-28T14:50:28+01:00",
        "orderNumber": "1518180120",
        "orderDate": "2019-02-28",
        "processingState": "exported",
        "processingStateHistory" : [
            {
                "state": "open",
                "changed": "2019-02-28T14:50:28+01:00"
            },
            {
                "state": "arrival_assumed",
                "changed": "2019-02-28T16:25:21+01:00"
            },
            {
                "state": "arrived",
                "changed": "2019-03-02T09:36:12+01:00"
            },
            {
                "state": "exported",
                "changed": "2019-03-02T15:53:47+01:00"
            }
        ],
        "processingStateChanged": "2019-03-02T15:53:47+01:00",
        "consignments": [
            {
                "tracking": {
                    "carrier": "swisspost",
                    "trackingNumber": "996006631900000002"
                },
                "gas": {
                    "carrier": "swisspost",
                    "trackingNumber": "996006631900000425"
                }
            }
        ]
    },
    "errors": [],
    "success": true
}
Name Typ Hinweis
order Order-Object Alle Informationen bezüglich der abgefragten Bestellung befinden sich in diesem Objekt
errors Array Die eventuellen Fehler des Requests, eine Auflistung der möglichen Fehler finden Sie hier
success Boolean Dieses Flag beschreibt ob der Request erfolgreich war oder nicht

Order-Object

Name Typ Hinweis
id Integer Ein eindeutiger Identifizierer der Bestellung
created  String  Der Zeitpunkt der Bestellungsankündigung
orderNumber String Die Bestellnummer
orderDate  String Das Bestelldatum
processingState Enum[String] Der aktuelle Bearbeitungsstatus der Bestellung.

["open", "arrival_assumed", "arrived", "partial_delivery_arrived", "verified", "verified_partially", "exported", "exported_partially", "not_arrived"]

Eine detaillierte Beschreibung hierzu finden Sie hier.
processingStateHistory Array[processingStateHistory-Object] Der detaillierte Verlauf der Bearbeitungsstatus
processingStateChanged  String Der Zeitpunkt der letzten Verarbeitungs-Status Änderung
consignments Array[Consignment-Object] Eine Auflistung der einzelnen Sendungen der Bestellung mit zusätzlichen Informationen zu dieser Sendung, erst vorhanden, wenn processingState "exported" oder "exported_partially"

ProcessingStateHistory-Object

Name Typ Hinweis
state String Der entsprechende Bearbeitungsstatus
changed String Der Zeitpunkt wann die Bestellung in den entsprechenden Status ging (Format ISO-8601)

Consignment-Object

Name Typ Hinweis
tracking Tracking-Object Die Trackinginformationen zu dieser Sendung
gas Tracking-Object Die GAS-Trackinginformationen zu dieser Sendung

Tracking-Object

Name Typ Hinweis
carrier Enum[String] Das Versandunternehmenen mit welchem die Sendung in der Schweiz versendet wird.

["swisspost", "dpd", "spedition"]
trackingNumber String Die Trackingnummer

GET - mehrere Bestellungen

GET https://api.meineinkauf.ch/v1/order

Hinweise
Die Bestellungen werden absteigend nach Bestelldatum sortiert. Bitte beachten Sie, dass wir bei Abfrage von mehreren Bestellungen die Anzahl der Bestellungen aus technischen Gründen auf 50 limitieren.

Parameter

Name Beispiel Default Hinweis
limit 25 50 Das Limit der zurückgegebenen Bestellungen, maximal 50
offset 0 0 Das Offset der zurückgegebenen Bestellungen
sort id:asc,created:desc orderDate:desc Die Sortierung des Ergebnisses, kommaseparierte Liste aus "eigenschaft:richtung"-Tupeln

Mögliche Eigenschaften: ["id", "orderDate", "created", "processingStateChanged"]

Mögliche Richtungen: ["desc", "asc"]
processingStates open,arrival_assumed Eine Filterung des Ergebnisses anhand des Verarbeitungs-Status, kommaseparierte Liste aus möglichen Status

Mögliche Status: siehe hier

Beispiel Aufruf

curl https://api.meineinkauf.ch/v1/order?limit=25&offset=0&sort=id:asc,created:desc&processingStates=open,arrival_assumed \
  -X GET \
  -u 'api:MEINEINKAUF_TEST_API_KEY'

Antwort

{
    "orders": [
        {
            "id": 1234,
            "created": "2019-02-28T14:50:28+01:00",
            "orderNumber": "1518180121",
            "orderDate": "2019-02-28",
            "processingState": "arrival_assumed",
            "processingStateHistory" : [
                {
                    "state": "open",
                    "changed": "2019-02-28T14:50:28+01:00"
                },
                {
                    "state": "arrival_assumed",
                    "changed": "2019-02-28T16:25:21+01:00"
                }
            ],
            "processingStateChanged": "2019-02-28T16:25:21+01:00"
        },
        {
            "id": 1235,
            "created": "2019-02-28T14:50:28+01:00",
            "orderNumber": "1518180122",
            "orderDate": "2019-02-28",
            "processingState": "exported",
            "processingStateHistory" : [
                {
                    "state": "open",
                    "changed": "2019-02-28T14:50:28+01:00"
                },
                {
                    "state": "arrival_assumed",
                    "changed": "2019-02-28T16:25:21+01:00"
                },
                {
                    "state": "arrived",
                    "changed": "2019-03-02T09:36:12+01:00"
                },
                {
                    "state": "exported",
                    "changed": "2019-03-02T15:53:47+01:00"
                }
            ],
            "processingStateChanged": "2019-03-02T15:53:47+01:00",
            "consignments": [
                {
                    "tracking": {
                        "carrier": "swisspost",
                        "trackingNumber": "996006631900000003"
                    },
                    "gas": {
                        "carrier": "swisspost",
                        "trackingNumber": "996006631900000426"
                    }
                }
            ]
        }
    ],
    "count": 2102,
    "offset": 0,
    "limit": 2,
    "errors": [],
    "success": true
}
Name Typ Hinweis
orders Array[Order-Object] Eine Auflistung der einzelnen Bestellungs-Objekte mit den dazugehörigen Informationen
count Integer Die Gesamtanzahl der vorhandenen Bestellungen
offset Integer Das aktuelle Offset des Requests
limit Integer Das aktuelle Limit des Requests
errors Array Die eventuellen Fehler des Requests, eine Auflistung der möglichen Fehler finden Sie hier
success Boolean Dieses Flag beschreibt ob der Request erfolgreich war oder nicht

Verarbeitungs-Status

Name Beschreibung
open Die Bestellung wurde initial von Ihnen bei uns angekündigt
arrival_assumed Die Bestellung wurde von uns geprüft und die Ankunft wird erwartet
arrived Die Bestellung ist bei uns eingegangen und wird bearbeitet
partial_delivery_arrived Ein Teil der Bestellung ist bei uns eingegangen und wird bearbeitet (z.B. wenn eine Bestellung aus mehreren Sendungen besteht)
verified Die Bestellung wurde von uns geprüft und für den Versand vorbereitet
verified_partially Ein Teil der Bestellung wurde von uns geprüft und für den Versand vorbereitet
exported Die Bestellung wurde in die Schweiz exportiert
exported_partially Die Bestellung wurde teilweise in die Schweiz exportiert (z.B. wenn eine Bestellung aus mehreren Sendungen besteht)
not_arrived Die Bestellung ist nach einem gewissen Zeitraum nicht bei uns eingegangen