Geisenheim (TODO) JSON API Dokumentation v0.9.0

Diese JSON API ist vorgesehen direkt mit dem Backend/der Datenbank von Geisenheim (TODO) zu kommunizieren (TODO.eu).

Dies ist Version 0.9.0 der Dokumentation (zuletzt geändert: 2020-09-30).
Es beschreibt die API Version 0.
Jegliche Weiterentwicklung der API ist vollkommen abwärtskompatibel: Alle Dokumentationen der Version v0.x beschreiben die v0 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.) /orders API Routen
• (2.1) POST /orders
• (2.2) DELETE /orders/ID
• (3.) Definition möglicher Werte
• (3.5) Liste möglicher Qualitätsstufen (“quality”)
• (4.) Änderungsprotokoll

Dieses Dokument beschreibt den aktuellen Entwicklungsstand der Geisenheim (TODO) API. Wir 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ändige Definitionen, zusätzliche Vorschläge, und alle anderen Anfragen bezüglich der API, Bitte kontaktieren Sie uns, das Euvino GmbH Entwicklerteam, at 030 983 959 16 or api@euvinopro.eu.

1. API Grundlagen

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

Basis-URL für alle Requests: https://rest.TODO.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 (TODO) Backend (app.euvinopro.eu/winegrower/interfaces) 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 OkStatus 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 das 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 beinthalten.

1.1 Basis-URL

Die Basis-URL für alle API-Requests ist https://rest.TODO.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://rest.TODO.de/orders.

1.2 Test-API

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

Die Testumgebung nutzt eine abweichende Basis-URL: https://rest.test.TODO.de.

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

2. /orders API Routen

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

2.1 POST /orders

Die POST /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 */

    "recipient": /* Informationen zum Rechnungsempfänger */ {
        "id": "OQU0-XUI3",  /* Interner eindeutiger Identifikator des Empfängers.
            Alle Formate werden akzeptiert: Zahlen, Buchstaben, ... */
        "type": 1,  /* Art des Empfängers, für mögliche Werte siehe 3.1 Liste möglicher Kundentypen (“type”) */
        "source": "online",  /* Quelle der Buchung, "online" für Bestellungen im Onlineshop, "local" für Direktbuchungen, Hofverkauf, etc. */
        "delivery": "DHL",  /* Lieferweg - mögliche Werte: "DHL", "DPD", "GLS", "Zufuhr", und für Speditionen den Namen der Spedition, 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) */

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

        "yearOfBirth": 1972,  /* Geburtsjar 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 */ [
        {
            "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 inkl. eventueller Abzüge / Rabatte */
            "tax": 1.2,  /* enthaltene Umsatzsteuer der Einzelflasche */
            "discount": 0.0,  /* ggf. gewährter Rabatt bezogen auf die Einzelflasche */

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

            // 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 akzeptieren Rebsorten “grapes” */
            "taste": 1,  /* Geschmack, für mögliche Werte siehe   */
            "vdp": null,  /* VDP-Klassifikation, optional, für mögliche Werte siehe 3.8 Liste möglicher VDP-Klassifikationen (“vdp”) */
        }
    ]
}

Antworten:

• Antwort wenn eine Bestellung erfolgreich erfasst wurde: 201 Created { "id": "64a774c0-a2df-4b12-bc7a-34176f759957" }
• Antwort wenn Pflichtfelder fehlen oder Felder ungültige Daten enthalten: 400 Bad Request { /* Ein Json Objekt, das die Validierungsergebnisse enthält */ }

⚠ 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 /orders/ID

Die DELETE /orders/ID Route ermöglicht es, die Erstattung / Stornierung einer Bestellung vorzunehmen.
Dieser Request benötigt keinen Request-Body.

Die ID in der Route entspricht der id, die beim Anlegen der Bestellung - wie in 2.1 POST /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