Zum Hauptinhalt springen

Benutzerdefinierte API-Integration

Dieser Leitfaden bietet technische Details zur Integration von Eaternity Forecast mit Ihrem individuellen POS-, ERP- oder Kuechenmanagementsystem ueber unsere REST-API.

API-Ueberblick

Basis-URL

Produktion: https://api.eaternity.org/v1/forecast
Sandbox: https://sandbox-api.eaternity.org/v1/forecast

Empfehlung: Entwickeln und testen Sie in der Sandbox-Umgebung vor dem Produktionseinsatz.

Authentifizierung

Unterstuetzte Methoden:

  1. OAuth 2.0 (empfohlen fuer benutzerorientierte Anwendungen)
  2. API-Schluessel (empfohlen fuer Server-zu-Server-Integration)

Sicherheitsanforderungen:

  • Alle Anfragen muessen HTTPS verwenden
  • TLS 1.2 oder hoeher erforderlich
  • API-Schluessel muessen sicher gespeichert werden (Umgebungsvariablen, Secret-Manager)

Siehe Eaternity API-Dokumentation →

Ratenbegrenzungen

Standardlimits:

  • 100 Anfragen pro Minute
  • 10.000 Anfragen pro Tag
  • Burst-Toleranz: 150 Anfragen in 60 Sekunden

Individuelle Limits:

  • Verfuegbar fuer Hochvolumen-Integrationen
  • Support kontaktieren fuer Limiterhoehanfragen

Ratenlimit-Header:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705752000

Schnellstart

1. API-Zugangsdaten erhalten

Schritt 1: Eaternity fuer API-Zugang kontaktieren

Schritt 2: API-Zugangsdaten erhalten

  • API-Schluessel fuer Authentifizierung
  • Kitchen-ID fuer Ihren Standort
  • Sandbox-Umgebungszugang

Schritt 3: Authentifizierung testen

curl -X GET "https://sandbox-api.eaternity.org/v1/forecast/ping" \
-H "Authorization: Bearer your_api_key_here"

# Erfolgsantwort:
{
"status": "success",
"message": "Authentication successful",
"kitchen_id": "your_kitchen_id"
}

2. Historische Daten einreichen

Endpunkt: POST /v1/forecast/sales/bulk

Anfrage-Beispiel:

curl -X POST "https://api.eaternity.org/v1/forecast/sales/bulk" \
-H "Authorization: Bearer your_api_key" \
-H "Content-Type: application/json" \
-d '{
"kitchen_id": "your_kitchen_id",
"start_date": "2023-10-01",
"end_date": "2024-01-15",
"sales": [
{
"date": "2023-10-01",
"service_period": "lunch",
"items": [
{
"item_id": "pasta_carbonara",
"name": "Pasta Carbonara",
"quantity_sold": 52,
"price": 14.50,
"category": "Main Course"
},
{
"item_id": "caesar_salad",
"name": "Caesar Salad",
"quantity_sold": 31,
"price": 9.00,
"category": "Starter"
}
]
}
]
}'

Antwort:

{
"status": "success",
"message": "Historical data import queued",
"import_id": "imp_1234567890",
"total_records": 92,
"estimated_processing_time": "15 minutes",
"status_url": "/v1/forecast/imports/imp_1234567890/status"
}

3. Importstatus pruefen

Endpunkt: GET /v1/forecast/imports/{import_id}/status

curl -X GET "https://api.eaternity.org/v1/forecast/imports/imp_1234567890/status" \
-H "Authorization: Bearer your_api_key"

Antwort:

{
"import_id": "imp_1234567890",
"status": "processing",
"progress": 65,
"records_processed": 60,
"records_total": 92,
"records_failed": 0,
"errors": [],
"estimated_completion": "2024-01-20T10:35:00Z"
}

Statuswerte:

  • queued — Wartet auf Verarbeitung
  • processing — Wird gerade importiert
  • validating — Prueft Datenqualitaet
  • completed — Import erfolgreich
  • failed — Import mit Fehlern

4. Prognosen abrufen

Endpunkt: GET /v1/forecast/predictions

curl -X GET "https://api.eaternity.org/v1/forecast/predictions?date=2024-01-20" \
-H "Authorization: Bearer your_api_key"

Antwort:

{
"kitchen_id": "your_kitchen_id",
"generated_at": "2024-01-20T03:15:42Z",
"predictions": [
{
"date": "2024-01-20",
"day_of_week": "Saturday",
"items": [
{
"item_id": "pasta_carbonara",
"name": "Pasta Carbonara",
"predicted_quantity": 52,
"confidence_interval": {
"lower": 48,
"upper": 56
},
"confidence_score": 0.92,
"accuracy_last_30_days": 94.2,
"factors": {
"day_of_week_effect": 1.05,
"weather_effect": 1.02,
"trend": "stable"
}
}
]
}
]
}

API-Endpunkte

Verkaufsdaten-Endpunkte

Taegliche Verkaeufe einreichen

POST /v1/forecast/sales

Verkaufsdaten fuer einen einzelnen Tag einreichen.

Anfrage-Body:

{
"kitchen_id": "your_kitchen_id",
"date": "2024-01-19",
"service_periods": [
{
"period": "lunch",
"items": [
{
"item_id": "pasta_carbonara",
"name": "Pasta Carbonara",
"quantity_sold": 52,
"price": 14.50,
"category": "Main Course"
}
]
},
{
"period": "dinner",
"items": [
{
"item_id": "grilled_salmon",
"name": "Grilled Salmon",
"quantity_sold": 38,
"price": 18.50,
"category": "Main Course"
}
]
}
]
}

Antwort:

{
"status": "success",
"date": "2024-01-19",
"items_processed": 12,
"next_prediction_update": "2024-01-20T03:00:00Z"
}

Statuscodes:

  • 200 — Erfolg
  • 400 — Ungueltige Anfragedaten
  • 401 — Authentifizierung fehlgeschlagen
  • 422 — Datenvalidierung fehlgeschlagen
  • 429 — Ratenlimit ueberschritten

Massen-Historikimport

POST /v1/forecast/sales/bulk

Grosse Mengen historischer Daten importieren.

Anfrage-Body:

{
"kitchen_id": "your_kitchen_id",
"start_date": "2023-10-01",
"end_date": "2024-01-15",
"sales": [
{
"date": "2023-10-01",
"service_period": "lunch",
"items": [...]
}
]
}

Antwort:

{
"status": "success",
"import_id": "imp_1234567890",
"total_records": 92,
"status_url": "/v1/forecast/imports/imp_1234567890/status"
}

Bewaehrte Methoden:

  • Maximum 365 Tage pro Massenimport
  • Maximum 10.000 Datensaetze pro Anfrage
  • Bei groesseren Datensaetzen in mehrere Anfragen aufteilen
  • Importstatus ueber Status-Endpunkt ueberwachen

Verkaufsdaten aktualisieren

PATCH /v1/forecast/sales/{date}

Zuvor eingereichte Verkaufsdaten korrigieren.

Anfrage-Body:

{
"kitchen_id": "your_kitchen_id",
"items": [
{
"item_id": "pasta_carbonara",
"quantity_sold": 54
}
]
}

Anwendungsfaelle:

  • Dateneingabefehler korrigieren
  • Mit endgueltigen Tagesendwerten aktualisieren
  • Fehlende Servicezeitraeume hinzufuegen

Prognose-Endpunkte

Prognosen fuer Datumsbereich abrufen

GET /v1/forecast/predictions

Abfrageparameter:

  • date (erforderlich) — Datum oder Startdatum (YYYY-MM-DD)
  • end_date (optional) — Enddatum fuer Bereich (YYYY-MM-DD)
  • items (optional) — Kommagetrennte Artikel-IDs zum Filtern

Beispiele:

# Einzelnes Datum
GET /v1/forecast/predictions?date=2024-01-20

# Datumsbereich (naechste 7 Tage)
GET /v1/forecast/predictions?date=2024-01-20&end_date=2024-01-27

# Nur bestimmte Artikel
GET /v1/forecast/predictions?date=2024-01-20&items=pasta_carbonara,grilled_salmon

Antwort:

{
"kitchen_id": "your_kitchen_id",
"generated_at": "2024-01-20T03:15:42Z",
"predictions": [
{
"date": "2024-01-20",
"day_of_week": "Saturday",
"items": [...]
},
{
"date": "2024-01-21",
"day_of_week": "Sunday",
"items": [...]
}
]
}

Prognose fuer einzelnen Artikel abrufen

GET /v1/forecast/predictions/{item_id}

Abfrageparameter:

  • date (erforderlich) — Prognosedatum
  • days_ahead (optional) — Anzahl Prognosetage (Standard: 7, Max: 14)

Beispiel:

GET /v1/forecast/predictions/pasta_carbonara?date=2024-01-20&days_ahead=7

Antwort:

{
"item_id": "pasta_carbonara",
"name": "Pasta Carbonara",
"predictions": [
{
"date": "2024-01-20",
"predicted_quantity": 52,
"confidence_interval": {
"lower": 48,
"upper": 56
},
"confidence_score": 0.92
}
],
"historical_accuracy": {
"last_7_days": 95.2,
"last_30_days": 94.2,
"all_time": 93.8
}
}

Prognose ueberschreiben

POST /v1/forecast/predictions/override

Prognose fuer bestimmte Umstaende manuell ueberschreiben.

Anfrage-Body:

{
"kitchen_id": "your_kitchen_id",
"date": "2024-01-25",
"item_id": "pasta_carbonara",
"override_quantity": 75,
"reason": "Conference group booking (50 pax confirmed)",
"preserve_ratios": true
}

Parameter:

  • override_quantity (erforderlich) — Neue prognostizierte Menge
  • reason (erforderlich) — Erklaerung fuer Ueberschreibung (fuer Lernen genutzt)
  • preserve_ratios (optional) — Verwandte Artikel proportional anpassen

Antwort:

{
"status": "success",
"original_prediction": 52,
"override_quantity": 75,
"affected_items": [
{
"item_id": "caesar_salad",
"original": 31,
"adjusted": 45
}
]
}

Analytik-Endpunkte

Genauigkeitsbericht abrufen

GET /v1/forecast/analytics/accuracy

Abfrageparameter:

  • start_date (erforderlich) — Berichtsstartdatum
  • end_date (erforderlich) — Berichtsenddatum
  • group_by (optional) — day, week, month oder item

Beispiel:

GET /v1/forecast/analytics/accuracy?start_date=2024-01-01&end_date=2024-01-31&group_by=week

Antwort:

{
"period": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"overall_mape": 12.3,
"by_week": [
{
"week": 1,
"start_date": "2024-01-01",
"mape": 13.5,
"items_within_10_percent": 52,
"total_items": 65
}
],
"top_performers": [
{
"item_id": "pasta_carbonara",
"mape": 8.2
}
],
"needs_attention": [
{
"item_id": "daily_special",
"mape": 22.1,
"reason": "High variance, new items frequently"
}
]
}

Abfallreduzierungsbericht abrufen

GET /v1/forecast/analytics/waste-reduction

Lebensmittelabfalleinsparungen seit Forecast-Nutzung verfolgen.

Abfrageparameter:

  • baseline_start (erforderlich) — Basisperiode Start (vor Forecast)
  • baseline_end (erforderlich) — Basisperiode Ende
  • comparison_start (erforderlich) — Forecast-Nutzungsperiode Start
  • comparison_end (erforderlich) — Forecast-Nutzungsperiode Ende

Antwort:

{
"baseline": {
"period": "2023-10-01 to 2023-12-31",
"waste_rate": 12.8,
"total_waste_portions": 3845,
"estimated_cost": 21148.50
},
"comparison": {
"period": "2024-01-01 to 2024-03-31",
"waste_rate": 7.2,
"total_waste_portions": 2156,
"estimated_cost": 11858.00
},
"improvement": {
"waste_rate_reduction": 43.8,
"portions_saved": 1689,
"cost_savings": 9290.50,
"annualized_savings": 11748.60
}
}

Webhooks

Ueberblick

Webhooks ermoeglichen es Forecast, Benachrichtigungen an Ihr System zu senden, statt Polling zu erfordern.

Anwendungsfaelle:

  • Benachrichtigungen erhalten, wenn neue Prognosen bereit sind
  • Warnungen bei grossen Abweichungen zwischen Prognose und Istwert
  • Datenqualitaetsprobleme ueberwachen
  • Modell-Neutraining-Ereignisse verfolgen

Einrichtung

Webhook-Endpunkt konfigurieren:

POST /v1/forecast/webhooks

{
"kitchen_id": "your_kitchen_id",
"url": "https://your-system.com/webhooks/forecast",
"events": [
"predictions.generated",
"variance.large",
"data.quality_issue",
"model.retrained"
],
"secret": "your_webhook_secret_for_signature_validation"
}

Antwort:

{
"webhook_id": "wh_1234567890",
"status": "active",
"events": ["predictions.generated", "variance.large"],
"created_at": "2024-01-20T10:00:00Z"
}

Webhook-Ereignisse

predictions.generated

Ausgeloest wenn neue Prognosen generiert werden (taeglich um 3:00 Uhr).

Payload:

{
"event": "predictions.generated",
"timestamp": "2024-01-20T03:15:42Z",
"kitchen_id": "your_kitchen_id",
"data": {
"date_range": {
"start": "2024-01-20",
"end": "2024-01-27"
},
"total_items": 65,
"prediction_url": "/v1/forecast/predictions?date=2024-01-20"
}
}

variance.large

Ausgeloest wenn tatsaechliche Verkaeufe deutlich von Prognose abweichen (>20% standardmaessig).

Payload:

{
"event": "variance.large",
"timestamp": "2024-01-19T21:30:00Z",
"kitchen_id": "your_kitchen_id",
"data": {
"date": "2024-01-19",
"item_id": "grilled_salmon",
"predicted": 28,
"actual": 42,
"variance_percent": 50.0,
"possible_causes": ["weather_warmer_than_forecast", "event_nearby"]
}
}

data.quality_issue

Ausgeloest wenn Datenqualitaetsprobleme erkannt werden.

Payload:

{
"event": "data.quality_issue",
"timestamp": "2024-01-20T04:00:00Z",
"kitchen_id": "your_kitchen_id",
"data": {
"issue_type": "missing_data",
"severity": "warning",
"description": "No sales data received for 2024-01-19",
"recommendation": "Submit sales data for 2024-01-19 to maintain prediction accuracy"
}
}

model.retrained

Ausgeloest wenn Modell mit neuen Daten neu trainiert wird (woechentlich).

Payload:

{
"event": "model.retrained",
"timestamp": "2024-01-20T04:30:00Z",
"kitchen_id": "your_kitchen_id",
"data": {
"training_data_range": {
"start": "2023-10-01",
"end": "2024-01-19"
},
"accuracy_improvement": 1.2,
"new_mape": 12.1,
"previous_mape": 13.3
}
}

Webhook-Sicherheit

Signaturvalidierung:

Alle Webhook-Anfragen enthalten X-Forecast-Signature-Header zur Verifizierung.

Verifizierungsbeispiel (Python):

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
expected_signature = hmac.new(
secret.encode('utf-8'),
payload.encode('utf-8'),
hashlib.sha256
).hexdigest()

return hmac.compare_digest(signature, expected_signature)

# In Ihrem Webhook-Handler:
payload = request.body
signature = request.headers['X-Forecast-Signature']
secret = 'your_webhook_secret'

if verify_webhook_signature(payload, signature, secret):
# Webhook verarbeiten
pass
else:
# Anfrage ablehnen (moegliches Sicherheitsproblem)
return 401

Datenformate und Validierung

Artikel-ID-Anforderungen

Format:

  • Nur alphanumerische Zeichen, Unterstriche, Bindestriche
  • Maximum 100 Zeichen
  • Gross-/Kleinschreibung beachten
  • Muss ueber alle Anfragen hinweg konsistent sein

Gute Beispiele:

  • pasta_carbonara
  • grilled-salmon-lemon
  • ITEM_12345

Schlechte Beispiele:

  • Pasta Carbonara (enthaelt Leerzeichen)
  • item#12345 (enthaelt Sonderzeichen)
  • Unterschiedliche Schreibweise: Pasta_Carbonara vs pasta_carbonara (inkonsistent)

Datumsformat

Erforderliches Format: YYYY-MM-DD (ISO 8601)

Gueltig:

  • 2024-01-20
  • 2024-12-31

Ungueltig:

  • 20-01-2024 (falsche Reihenfolge)
  • 2024/01/20 (Schraegstriche statt Bindestriche)
  • 2024-1-20 (nicht nullgefuellt)

Mengenvalidierung

Anforderungen:

  • Nur Ganzzahlwerte
  • Minimum: 0
  • Maximum: 10.000 (Support kontaktieren fuer hoehere Limits)
  • Negative Werte abgelehnt

Preisvalidierung

Anforderungen:

  • Dezimalwerte (2 Nachkommastellen)
  • Minimum: 0,00
  • Maximum: 999,99
  • Waehrung nicht angegeben (konsistente Waehrung ueber alle Daten verwenden)

Fehlerbehandlung

Fehlerantwort-Format

{
"status": "error",
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid date format",
"details": {
"field": "date",
"value": "20-01-2024",
"expected": "YYYY-MM-DD"
}
}
}

Haeufige Fehlercodes

CodeHTTP-StatusBeschreibungLoesung
AUTHENTICATION_FAILED401Ungueltiger API-SchluesselAPI-Schluessel verifizieren
RATE_LIMIT_EXCEEDED429Zu viele AnfragenWarten und wiederholen, oder Limiterhoehanfrage
VALIDATION_ERROR422Ungueltiges DatenformatAnfrageformat gegen Doku pruefen
NOT_FOUND404Ressource nicht gefundenkitchen_id oder item_id verifizieren
INTERNAL_ERROR500ServerfehlerMit exponentiellem Backoff wiederholen

Wiederholungslogik

Empfohlene Wiederholungsstrategie:

import time
import requests

def make_request_with_retry(url, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.get(url)

if response.status_code == 200:
return response.json()
elif response.status_code == 429:
# Ratenlimitiert - warten und wiederholen
retry_after = int(response.headers.get('Retry-After', 60))
time.sleep(retry_after)
elif response.status_code >= 500:
# Serverfehler - exponentieller Backoff
wait_time = 2 ** attempt
time.sleep(wait_time)
else:
# Clientfehler - nicht wiederholen
raise Exception(f"Error {response.status_code}: {response.text}")

except requests.exceptions.RequestException as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)

raise Exception("Max retries exceeded")

SDK und Client-Bibliotheken

Offizielle SDKs

Python SDK (Empfohlen):

pip install eaternity-forecast

Verwendung:

from eaternity_forecast import ForecastClient

client = ForecastClient(api_key='your_api_key')

# Taegliche Verkaeufe einreichen
client.sales.submit(
date='2024-01-19',
items=[
{'item_id': 'pasta_carbonara', 'quantity_sold': 52}
]
)

# Prognosen abrufen
predictions = client.predictions.get(date='2024-01-20')

JavaScript/TypeScript SDK:

npm install @eaternity/forecast-sdk

Verwendung:

import { ForecastClient } from '@eaternity/forecast-sdk';

const client = new ForecastClient({ apiKey: 'your_api_key' });

// Prognosen abrufen
const predictions = await client.predictions.get({ date: '2024-01-20' });

Community-SDKs:

  • Ruby: gem install eaternity-forecast
  • PHP: composer require eaternity/forecast-sdk
  • Go: go get github.com/eaternity/forecast-go

SDK-Dokumentation anzeigen →

Testen

Sandbox-Umgebung

Zweck: Integration testen ohne Produktionsdaten zu beeinflussen

Basis-URL: https://sandbox-api.eaternity.org/v1/forecast

Funktionen:

  • Separate Authentifizierungs-Zugangsdaten
  • Testdaten koennen zurueckgesetzt werden
  • Gleiche API wie Produktion
  • Schnellere Prognosegenerierung (zum Testen)

Einschraenkungen:

  • Prognosen koennen weniger genau sein (synthetische Daten)
  • Keine SLA-Garantien
  • Daten woechentlich zurueckgesetzt

Beispiel-Integrationstest

import unittest
from eaternity_forecast import ForecastClient

class TestForecastIntegration(unittest.TestCase):
def setUp(self):
self.client = ForecastClient(
api_key='sandbox_api_key',
base_url='https://sandbox-api.eaternity.org/v1/forecast'
)

def test_submit_sales_and_get_predictions(self):
# Historische Daten einreichen
response = self.client.sales.submit(
date='2024-01-19',
items=[
{'item_id': 'test_item_1', 'quantity_sold': 50},
{'item_id': 'test_item_2', 'quantity_sold': 30}
]
)
self.assertEqual(response['status'], 'success')

# Auf Verarbeitung warten (Sandbox ist schneller)
time.sleep(10)

# Prognosen abrufen
predictions = self.client.predictions.get(date='2024-01-20')
self.assertIsNotNone(predictions)
self.assertGreater(len(predictions['predictions']), 0)

Produktions-Bereitstellungs-Checkliste

Vor Go-Live

  • Alle Endpunkte in Sandbox-Umgebung getestet
  • Fehlerbehandlung und Wiederholungslogik implementiert
  • Webhook-Endpunkte konfiguriert (falls verwendet)
  • Webhook-Signaturvalidierung verifiziert
  • Monitoring und Logging eingerichtet
  • Integration fuer Team dokumentiert
  • Produktions-API-Zugangsdaten erhalten
  • Historische Daten erfolgreich importiert
  • Datenqualitaetswert >80% verifiziert
  • Modelltraining abgeschlossen

Go-Live

  • Von Sandbox zu Produktions-URLs wechseln
  • API-Zugangsdaten auf Produktion aktualisieren
  • Erste 24 Stunden Prognosen ueberwachen
  • Taegliche Verkaufseinreichung funktioniert verifizieren
  • Prognoseabruf funktioniert bestaetigen
  • Webhook-Zustellung pruefen (falls konfiguriert)

Nach Go-Live

  • Genauigkeitsmetriken woechentlich verfolgen
  • Grosse Abweichungswarnungen pruefen und reagieren
  • Feedback zur Prognosequalitaet geben
  • Zubereitungsworkflows basierend auf Konfidenz optimieren
  • Monatliche Leistungsueberpruefungen planen

Support

Technischer Support

E-Mail: forecast-api@eaternity.org

Antwortzeiten:

  • Kritisch (Produktion ausgefallen): 4 Stunden
  • Hoch (eingeschraenkte Leistung): 24 Stunden
  • Mittel (Fragen, Bugs): 48 Stunden
  • Niedrig (Erweiterungen): 1 Woche

In Support-Anfragen angeben:

  • Kitchen-ID
  • API-Endpunkt und -Methode
  • Anfrage-/Antwortbeispiele
  • Fehlermeldungen
  • Zeitstempel des Problems

Dokumentation

Siehe auch