Geisenheim (Weinwirtschaftsportal) JSON API Dokumentation v1.2.0

Diese JSON API ist vorgesehen direkt mit dem Backend/der Datenbank von Geisenheim (Weinwirtschaftsportal) zu kommunizieren (geisenheim-portal.de).

Dies ist Version 1.2.0 der Dokumentation (zuletzt geändert: 2023-04-25).
Es beschreibt die API Version 1.
Jegliche Weiterentwicklung der API ist vollkommen abwärtskompatibel: Alle Dokumentationen der Version v1.x beschreiben die v1 API, während neuere Versionen der Dokumentation (so wie die, die Sie gerade lesen) nur zusätzliche inkrementelle Funktionen enthalten und dabei keine Änderung von bestehenden Funktionen beschreiben.

Inhaltsverzeichnis:

• (1.) API Grundlagen
• (1.1) Basis-URL
• (1.2) Test-API
• (2.) /erp/orders API-Routen
• (2.1) POST /erp/orders
• (2.2) DELETE /erp/orders/ID
• (3.) Definition möglicher Werte
• (4.) Änderungsprotokoll

Dieses Dokument beschreibt den aktuellen Entwicklungsstand der Geisenheim (Weinwirtschaftsportal)-API. Wir legen großen Wert darauf, so genau wie möglich zu sein. Sollten Sie dennoch einen Fehler in der Dokumentation finden, kontaktieren Sie uns direkt damit wir so schnell wie möglich eine Lösung finden können. Im Falle eines unerwarteten API-Verhaltens, unvollständiger Definitionen, zusätzlicher Vorschläge und aller anderen Anfragen bezüglich der API, bitte kontaktieren Sie uns, das Euvino GmbH-Entwicklerteam, unter 030 983 959 16 oder api@euvinopro.eu.

#

1. API Grundlagen

Die Geisenheim (Weinwirtschaftsportal) API ist eine HTTP-API die alle Eingabedaten im JSON-Format erwartet, alle Antwortdaten werden ebenfalls im JSON-Format ausgegeben.

Basis-URL für alle Requests: https://api.geisenheim-portal.de, siehe 1.1 Basis-URL.
(Die Test-API benutzt eine abweichende Basis-URL, siehe 1.2 Test-API.)

Zugang zur API: Um die jeweiligen Zugangsdaten zu generieren, besuchen Sie das Geisenheim (Weinwirtschaftsportal)-Backend (backend.euvinopro.eu/winery/geisenheim/api) loggen sich mit dem Account des jeweiligen Weinguts ein und aktivieren die API. Dadurch werden Zugangsdaten erstellt bzw. neu generiert, die aus einem Nutzernamen (üblicherweise die E-Mail-Adresse des Nutzers die auch für den Backend-Login genutzt wird) und einem Passwort (zufällig generiert) besteht.

Authentifizierung: Jeder API-Request muss einen Authorization HTTP Header mit den API Authentifizierungsdaten enthalten, im Standard HTTP Basic format:
Der Wert des Headers ist “Basic ” gefolgt durch die Base64 Repräsentierung des Nutzernamen gefolgt durch einen Doppeltpunkt und dem Passwort.
Um zum Beispiel die API mit dem Nutzernamen api@test.de und dem password pw141819 zu nutzen:

    $username = "api@test.de";
    $password = "pw141819";
    $header   = "Authorization: Basic " . base64_encode($username . ":" . $password);
 // $header  == "Authorization: Basic YXBpQHRlc3QuZGU6cHcxNDE4MTk=

Generische HTTP-Antworten: Das Resultat eines jeden Requests wird durch den HTTP-Status der Antwort mitgeteilt. Die Requests werden üblicherweise mit einem 200 Ok-Status beantwortet.
Zusätzlich gibt es folgende Stati im Fehlerfall:

• 400 Bad Request: fehlerhafte Eingabedaten
• 401 Unauthorized: Der Authorization-Header fehlt oder enthält ungültige Daten

JSON Definitionen: optionale JSON-Schlüssel können üblicherweise ausgelassen oder auf null gesetzt werden, ohne dass Fehler entstehen. Ein leerer String ("") ist damit nicht gleichwertig sondern wird als Eingabe verarbeitet.
Wie üblich ist die Reihenfolge der JSON-Objektschlüssel irrelevant. Jeglicher whitespace (außerhalb von Stringwerten) wird ignoriert. Alle Eingaben dürfen ausschließlich im UTF-8 Encoding gesendet werden. Alle JSON-Antworten entsprechen der JSON-Spezifikation (json.org, RFC 7159). Die API erwartet, dass alle Eingabedaten ebenfalls diesem Standard entsprechen.

Standard-Header: Alle Requests müssen den Content‑Type: application/json oder Content‑Type: application/json; encoding=utf-8-HTTP Header enthalten, um den Inhaltstyp des Requests zu beschreiben. Alle API-Antworten werden diesen Header ebenfalls beinhalten.

#

1.1 Basis-URL

Die Basis-URL für alle API-Requests ist https://api.geisenheim-portal.de.

Alle API-Routen in diesem Dokument beziehen sich auf diese URL. Wenn zum Beispiel von der Route “/orders” die Rede ist, lautet die vollständige URL https://api.geisenheim-portal.de/orders.

#

1.2 Test-API

Es existiert eine Testumgebung. Es bietet die gleiche API aber operiert auf einer separaten Datenbank um sicheres Testen zu ermöglichen.

Die Testumgebung nutzt eine abweichende Basis-URL: https://api.staging.geisenheim-portal.de.

Aus Sicherheitsgründen nutzt die Test-API nicht nur eine separate Datenbank sondern auch abweichende Zugangsdaten.

#

2. /erp/orders API-Routen

Über die /erp/orders-Routen können neue Rechnungen angelegt, aufgelistet und entfernt werden.

#

2.1 POST /erp/orders

Die POST /erp/orders-Route legt eine neue Bestellung / Rechnung an. Retouren bzw Negativbuchungen können hierüber ebenfalls eingebucht werden.

Diese Route erwartet ein JSON-Objekt im Request Body, das gewisse Pflichtfelder erfüllen muss. Alle Felder sind verpflichtend, wenn nicht anders vermerkt.

Die möglichen Ausprägungen der Felder finden Sie unter 3. Definition möglicher Werte bzw. neben den jeweiligen Feldern. Es folgt der Inhalt eines Beispiel-Requests:

{
    "date": "2020-09-22",  /* Rechnungsdatum im Format JJJJ-MM-TT, nicht das Datum der Übertragung */
    "id": 3459872, /* fortlaufende Datenbank-ID, nicht die Rechnungsnummer.
                      Wird zur späteren Erfassung von Stornierungen und zur Nachvollziehbarkeit von ggf. Übertragungsfehlern verwendet.
                      Daher sollten keine Lücken in der fortlaufenden Nummerierung bestehen. */

    "recipient": /* Informationen zum Rechnungsempfänger */ {
        "id": "OQU0-XUI3",  /* Interner eindeutiger anonymer Identifikator des Empfängers.
                               die Email-Adresse des Kunden sollte z.B. nicht verwendet werden, ein Hash der Email-Adresse wäre in Ordnung.
                               Alle Formate werden akzeptiert: Zahlen, Buchstaben, Sonderzeichen ... */
        "category": 1,  /* Art des Empfängers, für mögliche Werte siehe 3.1 Liste möglicher Kundentypen (“category”) */
        "source": "online",  /* Quelle der Buchung, "online" für Bestellungen im Onlineshop, "local" für Direktbuchungen/Hofverkauf. Bei abweichenden Werten frei Eingabe */
    
        // folgende Felder sind nur für Onlinebestellungen verpflichtend (source == "online")
        "delivery": "DHL",  /* Lieferweg - mögliche Werte: "DHL", "DPD", "GLS", "Zufuhr", "Abholung", oder bei abweichenden Werten freie Eingabe, z.B. "Spedition XYZ" */
        "postalCode": "124",  /* Die ersten drei Stellen der Postleitzahl des Empfängers */
        "country": "DE",  /* Land des Empfängers (nach ISO 3166-1 alpha-2) oder freie Eingabe */

        // folgende Felder sind nur für Endverbraucher anwendbar (category == 1)
        // alle dieser Felder sind optional

        "yearOfBirth": 1972,  /* Geburtsjahr im Format JJJJ */
        "agreesToMarketing": true,  /* Zustimmmung zum Onlinemarketing (true/false) */
        "gender": "m",  /* Geschlecht des Kunden: m für männlich, f für weiblich, x für divers */
        "paymentMethod": "paypal",  /* Zahlungsmethode, für mögliche Werte siehe 3.2 Liste möglicher Zahlungsmethoden (“paymentMethod”) */
    },

    "items": /* Liste der bestellten Produkte */ [
        {
            "id": "127/4",  /* Artikelnummer */
            "quantity": 6,  /* Anzahl der gekauften Flaschen dieses Weines */
            "category": 1,  /* Produktkategorie, für mögliche Werte siehe 3.3 Liste möglicher Produktkategorien (“category”) */
            "size": 750,  /* Flaschengröße in ml, akzeptierte Werte siehe 3.4 Liste von möglichen Flaschengrößen (“bottlesize”) */
            "price": 7.5,  /* Einzelpreis der Einzelflasche brutto inkl. eventueller Abzüge / Rabatte, in EUR */
            "tax": 1.2,  /* enthaltene Umsatzsteuer der Einzelflasche, in EUR */
            "discount": 0.0,  /* ggf. gewährter Rabatt bezogen auf die Einzelflasche, in EUR */

            "organic": true,  /* Handelt es sich um ein zertifiziertes Bio-Produkt? optional */

            // das folgende Feld ist nur für Wein und Schaumwein anwendbar (category == 1 bzw. category == 2)
            "quality": 2,  /* Qualitätsstufe, für mögliche Werte siehe 3.5 Liste möglicher Qualitätsstufen (“quality”) */

            // folgende Felder sind nur für Weine anwendbar (category == 1)

            "grapes": [2473, 2455],  /* Liste der Rebsorten des Weines, amtl. Rebsortennummer.
                                        Erlaubte Werte siehe 3.6 Liste von akzeptierten Rebsorten (“grapes”) */
            "wineType": "red",  /* Weinart, für mögliche Werte siehe 3.7 Liste möglicher Weintypen (“wineType”) */
            "taste": "dry",  /* Geschmack, für mögliche Werte siehe 3.8 Liste möglicher Geschmacksausprägungen (“taste”) */
            "vdp": null,  /* VDP-Klassifikation, optional, für mögliche Werte siehe 3.9 Liste möglicher VDP-Klassifikationen (“vdp”) */
        }
    ]
}

Antworten:

• Antwort wenn eine Bestellung erfolgreich erfasst wurde:
  

      201 Created    { "id": 3459872 }

• Antwort wenn Pflichtfelder fehlen oder Felder ungültige Daten enthalten:
  

      400 Bad Request    { /* Ein JSON-Objekt, das die Validierungsergebnisse enthält */ }

• Antwort wenn ID der Rechnung bereits verwendet wurde:
  

      409 Conflict

⚠ Im Fall einer 400 Bad Request-Antwort müssen die Daten anhand der Validierungsantwort angepasst und erneut übertragen werden.

Im Sonderfall einer 500 Internal Server Error-Antwort gibt es ein temporäres Serverproblem. In diesem Fall ist die Übertragung zu einem späteren Zeitpunkt zu wiederholen.

#

2.2 DELETE /erp/orders/ID

Die DELETE /erp/orders/ID Route ermöglicht es, die Erstattung / Stornierung einer Bestellung mitzuteilen.

Dieser Request benötigt keinen Request-Body. Beispiel:

DELETE https://api.geisenheim-portal.de/erp/orders/3459872

204 No Content

Die ID in der Route entspricht der id, die beim Anlegen der Bestellung - wie in 2.1 POST /erp/orders dargestellt - verwendet wird. Antworten:

• Bestellung gefunden und erfolgreich storniert: 204 No Content
• Bestellung nicht gefunden: 404 Not Found
• Bestellung gefunden aber sie wurde bereits storniert: 410 Gone

#

3. Definition möglicher Werte