Grüezi!

Auf den folgenden Seiten finden Sie alle nötigen Informationen um mit Hilfe der MeinEinkauf.ch Partner API Bestelldaten direkt aus Ihrem Online-Shop in unser System übermitteln zu können.

Das Partnerangebot von MeinEinkauf.ch

MeinEinkauf.ch fungiert als Schnittstelle zwischen deutschen Online Händlern und Schweizer Kunden.

Wir bieten deutschen Händlern die Gelegenheit, ihre Waren zu Inlandsversandbedingungen an Kunden in der Schweiz zu senden. Ihren Schweizer Kunden ermöglichen wir eine Lieferung aus Deutschland mit folgenden Vorteilen:

  • Keine Nachzahlung des Schweizer Kunden bei Empfang Ihrer Sendung ("all duties paid").
  • Geringe Laufzeiten (i.d.R. Laufzeit in Deutschland +1 Werktag).
  • Nationale statt internationale Versandkosten (damit Sendungen bis 30kg Gewicht zu sinnvollen Kosten möglich).
  • Retouren ohne nachträgliche Verzollung bei Ihrem zuständigen Binnenzollamt.

Als unser Partner erhalten Sie vereinfachten Zugang zu Schweizer Kunden.

Partner werden

Falls Sie Interesse haben Partner von MeinEinkauf.ch zu werden, wenden Sie sich bitte an partner@meineinkauf.ch oder besuchen Sie uns auf meineinkauf.ch.

Erste Schritte

Die MeinEinkauf.ch Partner API richtet sich an Online Händler und Entwickler, welche vertraut damit sind, eine RESTful API in Eigenentwicklung an den eigenen Online Shop anzubinden.

SSL

Da unter anderem sensible Kundendaten über die API gesendet werden, ist es erforderlich, dass sämtliche Requests per SSL verschlüsselt sind. Meineinkauf.ch bietet ein gültiges und signiertes SSL-Zertifikat. Jegliche API-Requests, die nicht per SSL an uns übermittelt werden, werden von unserer API nicht entgegengenommen.

REST

Die MeinEinkauf.ch Partner API ist nach dem REST-Paradigma aufgebaut. Auch wenn es keinen definierten REST-Standard gibt, gibt es Ansätze und Best-Practises welche genutzt werden um den Umgang mit RESTful APIs zu vereinheitlichen und zu vereinfachen. Um mit den einzelnen API-Endpunkten zu interagieren, werden die Standard HTTP Methoden POST, GET, PUT und DELETE genutzt. Für diese Operationen wird auch das Akronym CRUD (Create, Read, Update, Delete) verwendet. Mehr Informationen zum Thema REST finden sie hier.

JSON

Die MeinEinkauf.ch Partner API unterstützt einzig JSON als Format zum Austausch von Daten. Übermittelte Daten müssen validem JSON entsprechen. Die Antworten der API erfolgen ebenfalls im JSON-Format.

Verfügbarkeit

MeinEinkauf.ch legt sehr großen Wert auf eine höchstmögliche Verfügbarkeit der API. Unsere IT-Systeme sind mit modernsten Techniken aufgesetzt, welche eine hohe Verfügbarkeit garantieren. Allerdings müssen auch planmäßige Wartungsarbeiten am System durchgeführt werden. Wir sind stets bemüht die Wartungsarbeiten möglichst kurz zu halten. Wärend der Wartungsarbeiten ist die API nicht erreichbar. In dem Fall wird der HTTP-Status-Code 503 Service Unavailable zurückgegeben. Ihr System muss den Request dann zu einem späteren Zeitpunkt nochmal ausführen. Mehr Informationen zu den möglichen HTTP Status Codes finden Sie hier.

Überblick

API URL

Die MeinEinkauf.ch Partner API ist unter folgender URL erreichbar:

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

Authentifizierung

Jeder Request an die MeinEinkauf.ch Partner API muss authentifiziert werden. Hierfür nutzen wir die HTTP Basic authentication. Der Benutzername lautet immer api und das Passwort ist der von uns für Sie bereitgestellte API-Schlüssel.

Testen

Test API Key

Um die Requests bei der Implementierung der API in Ihren Online-Shop zu testen, können Sie als API-Schlüssel den Wert MEINEINKAUF_TEST_API_KEY nutzen. Ihre übermittelten Daten werden dann unter realen Bedingungen validiert. Die Antworten (inklusive eventueller Fehlermeldungen) der API sind ebenfalls identisch zu realen Aufrufen. Die übermittelten Test-Daten werden von uns allerdings nicht gespeichert.

Test System

Zusätzlich zum Testen mittels Test API Key stellen wir ein Test-System bereit. Nachdem wir Ihnen einen Zugang auf dem Test-System eingerichtet haben, werden die übermittelten Daten gespeichert. Dieses ist unter folgender URL erreichbar:

https://api-test.meineinkauf.ch/v1/

Dieses System ist ein Klon des Produktiv-Systems, welches als Sandbox dient. Die Verarbeitung der Bestellungen wird auf dem Test System simuliert. Die Routinen laufen alle 15 Minuten und sorgen dafür, dass jede Bestellung die verschiedenen Status durchläuft und Sie so den kompletten Prozess durchtesten können.

Der erste Request

Für einen einfachen Einstieg haben wir einen simplen Echo-Endpunkt implementiert. Dieser Endpunkt liefert einen übermittelten Parameter wieder zurück, hierüber kann z.B. die Authentifizierung getestet werden.

Aufruf:

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

Antwort:

{
    "echo": "HelloWorld",
    "errors": [],
    "success": true,
    "testMode": true
}

HTTP Status Codes

  • 200 OK - Der Request war erfolgreich.
  • 201 Created - Die übermittelten Daten wurden erfolgreich verarbeitet und es wurde zum Beispiel eine Bestellung erstellt.
  • 400 Bad Request - Der Endpunkt existiert nicht oder wurde mit einer falschen HTTP-Methode aufgerufen.
  • 401 Unauthorized - Der Request konnte nicht authentifiziert werden.
  • 422 Unprocessable Entity - Die übermittelten Daten waren nicht valide.
  • 500 Internal Server Error - Es gab ein Problem auf unserer Seite und wir arbeiten schnellstmöglich an einer Lösung. Die übermittelten Daten wurden in der Regel nicht verarbeitet und ihr System muss den Request zu einem späteren Zeitpunkt erneut senden.
  • 503 Service Unavailable - Während planmäßiger Wartungsarbeiten wird dieser Status zurückgegeben. Die übermittelten Daten wurden nicht verarbeitet und ihr System muss den Request zu einem späteren Zeitpunkt erneut senden.

API Error Codes

  • E0000 ApiKey is missing - Sie haben keinen ApiKey angegeben.
  • E0001 Unknown ApiKey - Der angegebene ApiKey ist unbekannt.
  • E1000 Invalid JSON - Die übermittelten Daten sind nicht valide. Eine detaillierte Fehlermeldung wird ebenfalls zurückgegeben.
  • E1001 No order found for given ordernumber - Die angegebene Bestellung existiert nicht.
  • E1002 No return consignment found for given reference - Die angegebene Retoure existiert nicht.

Echo

Der Echo-Endpunkt ist zum Testen der Verbindung von Ihrem System zu unserer API gedacht. Außer dem Wiedergeben eines von Ihnen übermittelten Paramters bietet der Endpunkt keine weitere Funktion.

Post echo

post /echo
https://api.meineinkauf.ch/v1/echo
https://api-test.meineinkauf.ch/v1/echo
Authorizations:
Request Body schema: application/json
echo
required
string [ 1 .. 255 ] characters

Responses

201

Created

Response Schema: application/json
echo
string (EchoResponse)
success
boolean (Success)
errors
Array of objects (Errors)
401

Unauthorized

422

Unprocessable Entity

500

Internal Server Error

503

Service Unavailable

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "echo": "Hello World!"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "echo": "Hello World!",
  • "success": true,
  • "errors":
    [
    • {
      • "code": "string",
      • "message": "string",
      • "property": "string"
      }
    ]
}

Get echo

get /echo/{echo}
https://api.meineinkauf.ch/v1/echo/{echo}
https://api-test.meineinkauf.ch/v1/echo/{echo}
Authorizations:
path Parameters
echo
required
string
Example: Hello%20World%21

Der String, welcher als Echo zurückgegeben wird

Responses

200

OK

Response Schema: application/json
echo
string (EchoResponse)
success
boolean (Success)
401

Unauthorized

500

Internal Server Error

503

Service Unavailable

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "echo": "Hello World!",
  • "success": true
}

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.

Post order

post /order
https://api.meineinkauf.ch/v1/order
https://api-test.meineinkauf.ch/v1/order
Authorizations:
Request Body schema: application/json
orderNumber
required
string [ 1 .. 255 ] characters

Ihre Bestellnummer

externalId
string [ 1 .. 255 ] characters

Eindeutiger Identifier im Kundensystem

orderDate
required
string^20\d{2}-\d{2}-\d{2}$

Das Bestelldatum im Format "YYYY-MM-DD" ISO-8601 (MEZ/MESZ)

currency
required
string
Enum: "eur" "chf"

Die Währung der Bestellung

paymentType
required
string
Enum: "mastercard" "visa" "amex" "creditcard" "paypal" "prepayment" "invoice" "other"

Die Zahlart

grossSum
required
number [ 0.01 .. 100000 ]

Die Brutto Bestellsumme (inklusive Lieferkosten / Spenden abzgl. Rabatte)

customer
required
object (CustomerRequest)

Die Kundendaten

invoiceAddress
required
object

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.

shippingAddress
object

Die Lieferadresse muss zwangsläufig in der Schweiz oder Liechtenstein liegen. Wenn leer, wird die Rechnungsadresse als Lieferadresse genutzt.

consignments
required
Array of objects (ConsignmentRequest) non-empty

Für jede Sendung, die wir von Ihnen erhalten, muss ein ConsignmentRequest-Objekt in dem Array enthalten sein.

shippingCost
object (ShippingCostRequest)

Die Lieferkosten

discounts
Array of objects (DiscountRequest)

Die möglichen Rabatte auf die Bestellung

donations
Array of objects (DonationRequest)

Die möglichen Spenden zusätlich zur Bestellung

invoiceInformation
object (InvoiceInformationRequest)

Informationen zur Rechnungsstellung

Responses

201

Created

Response Schema: application/json
success
boolean (Success)
errors
Array of objects (Errors)
401

Unauthorized

422

Unprocessable Entity

500

Internal Server Error

503

Service Unavailable

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "orderNumber": "1518180120",
  • "externalId": "9876",
  • "orderDate": "2018-02-21",
  • "currency": "chf",
  • "paymentType": "prepayment",
  • "grossSum": 80,
  • "customer":
    {
    • "customerNumber": "kunde1234",
    • "contactEmail": "max@muster.de"
    },
  • "invoiceAddress":
    {
    • "company": "Muster GmbH",
    • "salutation": "Frau",
    • "title": "Dr.",
    • "firstName": "Erika",
    • "lastName": "Musterfrau",
    • "street": "Musterstrasse",
    • "houseNumber": "28a",
    • "addressLine": "140 Av. des Champs-Élysées",
    • "additionalAddressLine": "Im Hinterhof",
    • "zip": "8005",
    • "city": "Zürich",
    • "country": "CH",
    • "state": "Zürich"
    },
  • "shippingAddress":
    {
    • "company": "Muster GmbH",
    • "salutation": "Frau",
    • "title": "Dr.",
    • "firstName": "Erika",
    • "lastName": "Musterfrau",
    • "street": "Musterstrasse",
    • "houseNumber": "28a",
    • "addressLine": "140 Av. des Champs-Élysées",
    • "additionalAddressLine": "Im Hinterhof",
    • "zip": "8005",
    • "city": "Zürich",
    • "country": "CH",
    • "state": "Zürich"
    },
  • "consignments":
    [
    • {
      • "externalId": "9876",
      • "identificationBarcode": "123456789",
      • "grossWeight": 1200,
      • "dimensions":
        {
        • "width": 1,
        • "height": 1,
        • "length": 1
        },
      • "tracking":
        {
        • "carrier": "dhl",
        • "trackingNumber": "1234567890"
        },
      • "articles":
        [
        • {
          • "articleNumber": "12345678",
          • "externalId": "9876",
          • "name": "Gelbes Hemd",
          • "quantity": 2,
          • "grossWeight": 500,
          • "grossPrice": 35,
          • "vatRate": "standard",
          • "attributes":
            {
            • "color": "gelb",
            • "description": "Ein gelbes Hemd.",
            • "material": "100% Baumwolle",
            • "ean": "590123412345",
            • "upc": "036000291452",
            • "asin": "B005Z75C92",
            • "size": "XL",
            • "customIdentCode": "ABC1234"
            }
          }
        ]
      }
    ],
  • "shippingCost":
    {
    • "grossPrice": 10,
    • "vatRate": "standard"
    },
  • "discounts":
    [
    • {
      • "name": "Ihr Rabatt",
      • "grossPrice": -10,
      • "vatRate": "standard"
      }
    ],
  • "donations":
    [
    • {
      • "name": "Ihre Spende",
      • "grossPrice": 10,
      • "vatRate": "standard"
      }
    ],
  • "invoiceInformation":
    {
    • "invoiceDate": "2018-02-21",
    • "dueDate": "2018-03-21",
    • "additionalInvoiceText": "Vielen Dank!",
    • "esrInformation":
      {
      • "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",
      • "referenceNumber": "12345678"
      }
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "success": true,
  • "errors":
    [
    • {
      • "code": "string",
      • "message": "string",
      • "property": "string"
      }
    ]
}

Get multiple orders

get /order
https://api.meineinkauf.ch/v1/order
https://api-test.meineinkauf.ch/v1/order
Authorizations:
query Parameters
limit
integer [ 1 .. 50 ]
Default: 50

The numbers of items to return.

offset
integer >= 0
Default: 0

The number of items to skip before starting to collect the result set.

sort
string
Default: "orderDate:desc"
Enum: "id:desc" "id:asc" "orderDate:desc" "orderDate:asc" "created:desc" "created:asc" "processingStateChanged:desc" "processingStateChanged:asc"

The sorting of orders

processingStates
string
Example: processingStates=arrived%2Cexported

Returns a subset of orders in certain processing states. Multiple states can be requested comma separated. Possible states: [open, arrival_assumed, arrived, partial_delivery_arrived, verified, verified_partially, exported, exported_partially, not_arrived]

Responses

200

OK

Response Schema: application/json
orders
Array of objects (Orders)
success
boolean (Success)
count
integer (Count)
limit
integer (Limit)
offset
integer (Offset)
errors
Array of objects (Errors)
401

Unauthorized

500

Internal Server Error

503

Service Unavailable

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "orders":
    [
    • {
      • "id": 1234,
      • "externalId": "9876",
      • "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"
          }
        ],
      • "processingStateChanged": "2019-02-28T14:50:28+01:00",
      • "consignments":
        [
        • {
          • "externalId": "9876",
          • "tracking":
            {
            • "carrier": "swisspost",
            • "trackingNumber": "1234567890"
            },
          • "gas":
            {
            • "carrier": "swisspost",
            • "trackingNumber": "1234567890"
            },
          • "gasLabels":
            [
            • {
              • "carrier": "swisspost",
              • "trackingNumber": "1234567890"
              }
            ]
          }
        ]
      }
    ],
  • "success": true,
  • "count": 42,
  • "limit": 50,
  • "offset": 0,
  • "errors":
    [
    • {
      • "code": "string",
      • "message": "string",
      • "property": "string"
      }
    ]
}

Get single order

get /order/{orderNumber}
https://api.meineinkauf.ch/v1/order/{orderNumber}
https://api-test.meineinkauf.ch/v1/order/{orderNumber}
Authorizations:
path Parameters
orderNumber
required
string
Example: 1518180120

Ihre Bestellnummer

Responses

200

OK

Response Schema: application/json
order
object (OrderResponse)
success
boolean (Success)
errors
Array of objects (Errors)
401

Unauthorized

404

Not Found

500

Internal Server Error

503

Service Unavailable

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "order":
    {
    • "id": 1234,
    • "externalId": "9876",
    • "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"
        }
      ],
    • "processingStateChanged": "2019-02-28T14:50:28+01:00",
    • "consignments":
      [
      • {
        • "externalId": "9876",
        • "tracking":
          {
          • "carrier": "swisspost",
          • "trackingNumber": "1234567890"
          },
        • "gas":
          {
          • "carrier": "swisspost",
          • "trackingNumber": "1234567890"
          },
        • "gasLabels":
          [
          • {
            • "carrier": "swisspost",
            • "trackingNumber": "1234567890"
            }
          ]
        }
      ]
    },
  • "success": true,