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:
- OAuth 2.0 (empfohlen fuer benutzerorientierte Anwendungen)
- 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
- E-Mail an forecast@eaternity.org
- Firmendetails und Anwendungsfall angeben
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 Verarbeitungprocessing— Wird gerade importiertvalidating— Prueft Datenqualitaetcompleted— Import erfolgreichfailed— 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— Erfolg400— Ungueltige Anfragedaten401— Authentifizierung fehlgeschlagen422— Datenvalidierung fehlgeschlagen429— 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) — Prognosedatumdays_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 Mengereason(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) — Berichtsstartdatumend_date(erforderlich) — Berichtsenddatumgroup_by(optional) —day,week,monthoderitem
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 Endecomparison_start(erforderlich) — Forecast-Nutzungsperiode Startcomparison_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_carbonaragrilled-salmon-lemonITEM_12345
Schlechte Beispiele:
Pasta Carbonara(enthaelt Leerzeichen)item#12345(enthaelt Sonderzeichen)- Unterschiedliche Schreibweise:
Pasta_Carbonaravspasta_carbonara(inkonsistent)
Datumsformat
Erforderliches Format: YYYY-MM-DD (ISO 8601)
Gueltig:
2024-01-202024-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
| Code | HTTP-Status | Beschreibung | Loesung |
|---|---|---|---|
AUTHENTICATION_FAILED | 401 | Ungueltiger API-Schluessel | API-Schluessel verifizieren |
RATE_LIMIT_EXCEEDED | 429 | Zu viele Anfragen | Warten und wiederholen, oder Limiterhoehanfrage |
VALIDATION_ERROR | 422 | Ungueltiges Datenformat | Anfrageformat gegen Doku pruefen |
NOT_FOUND | 404 | Ressource nicht gefunden | kitchen_id oder item_id verifizieren |
INTERNAL_ERROR | 500 | Serverfehler | Mit 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
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
- API-Referenz — Vollstaendige Endpunkt-Dokumentation
- Integrationsueberblick — Alle Integrationsoptionen
- Fehlerbehebung — Haeufige Probleme
Siehe auch
- Integrationsueberblick — Integrationsmethoden vergleichen
- Necta-Integration — Necta-spezifischer Leitfaden
- Fehlerbehebung — Haeufige Probleme
- API-Referenz — Vollstaendige API-Dokumentation