Integrazione API Personalizzata

Questa guida fornisce i dettagli tecnici per integrare Eaternity Forecast con il vostro sistema POS, ERP o di gestione cucina personalizzato tramite la nostra API REST.

Panoramica API

URL Base

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

Consiglio: Sviluppate e testate in ambiente sandbox prima del deploy in produzione.

Autenticazione

Metodi Supportati:

OAuth 2.0 (consigliato per applicazioni con interfaccia utente)
Chiavi API (consigliato per integrazione server-to-server)

Requisiti Sicurezza:

Tutte le richieste devono usare HTTPS
TLS 1.2 o superiore richiesto
Le chiavi API devono essere conservate in modo sicuro (variabili ambiente, secret manager)

Vedi Documentazione API Eaternity

Limiti di Frequenza

Limiti Standard:

100 richieste al minuto
10.000 richieste al giorno
Burst permesso: 150 richieste in 60 secondi

Limiti Personalizzati:

Disponibili per integrazioni ad alto volume
Contattate il supporto per richieste aumento limiti

Header Limite Frequenza:

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

Avvio Rapido

1. Ottenere Credenziali API

Passo 1: Contattate Eaternity per accesso API

Email forecast@eaternity.org
Fornite dettagli azienda e caso d'uso

Passo 2: Ricevete credenziali API

Chiave API per autenticazione
Kitchen ID per la vostra location
Accesso ambiente sandbox

Passo 3: Testate autenticazione

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

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

2. Inviare Dati Storici

Endpoint: POST /v1/forecast/sales/bulk

Esempio Richiesta:

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"
          }
        ]
      }
    ]
  }'

Risposta:

{
  "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. Verificare Stato Importazione

Endpoint: 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"

Risposta:

{
  "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"
}

Valori Stato:

queued - In attesa di elaborazione
processing - Importazione in corso
validating - Controllo qualita dati
completed - Importazione riuscita
failed - Importazione con errori

4. Recuperare Previsioni

Endpoint: GET /v1/forecast/predictions

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

Risposta:

{
  "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"
          }
        }
      ]
    }
  ]
}

Endpoint API

Endpoint Dati Vendite

Inviare Vendite Giornaliere

POST /v1/forecast/sales

Invia dati vendite per un singolo giorno.

Corpo Richiesta:

{
  "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"
        }
      ]
    }
  ]
}

Risposta:

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

Codici Stato:

200 - Successo
400 - Dati richiesta non validi
401 - Autenticazione fallita
422 - Validazione dati fallita
429 - Limite frequenza superato

Importazione Massiva Storica

POST /v1/forecast/sales/bulk

Importa grandi volumi di dati storici.

Corpo Richiesta:

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

Risposta:

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

Migliori Pratiche:

Massimo 365 giorni per importazione massiva
Massimo 10.000 record per richiesta
Per dataset piu grandi, suddividere in piu richieste
Monitorare stato importazione via endpoint status

Aggiornare Dati Vendite

PATCH /v1/forecast/sales/{date}

Correggere dati vendite precedentemente inviati.

Corpo Richiesta:

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

Casi d'Uso:

Correggere errori inserimento dati
Aggiornare con conteggi finali fine giornata
Aggiungere periodi servizio mancanti

Endpoint Previsioni

Ottenere Previsioni per Intervallo Date

GET /v1/forecast/predictions

Parametri Query:

date (obbligatorio) - Data o data inizio (YYYY-MM-DD)
end_date (opzionale) - Data fine per intervallo (YYYY-MM-DD)
items (opzionale) - ID articoli separati da virgola da filtrare

Esempi:

# Singola data
GET /v1/forecast/predictions?date=2024-01-20

# Intervallo date (prossimi 7 giorni)
GET /v1/forecast/predictions?date=2024-01-20&end_date=2024-01-27

# Solo articoli specifici
GET /v1/forecast/predictions?date=2024-01-20&items=pasta_carbonara,grilled_salmon

Risposta:

{
  "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": [...]
    }
  ]
}

Ottenere Previsione per Singolo Articolo

GET /v1/forecast/predictions/{item_id}

Parametri Query:

date (obbligatorio) - Data previsione
days_ahead (opzionale) - Numero giorni da prevedere (default: 7, max: 14)

Esempio:

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

Risposta:

{
  "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
  }
}

Modificare Previsione

POST /v1/forecast/predictions/override

Modifica manualmente una previsione per circostanze specifiche.

Corpo Richiesta:

{
  "kitchen_id": "your_kitchen_id",
  "date": "2024-01-25",
  "item_id": "pasta_carbonara",
  "override_quantity": 75,
  "reason": "Prenotazione gruppo conferenza (50 pax confermati)",
  "preserve_ratios": true
}

Parametri:

override_quantity (obbligatorio) - Nuova quantita prevista
reason (obbligatorio) - Spiegazione per modifica (usata per apprendimento)
preserve_ratios (opzionale) - Aggiusta articoli correlati proporzionalmente

Risposta:

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

Endpoint Analisi

Ottenere Report Precisione

GET /v1/forecast/analytics/accuracy

Parametri Query:

start_date (obbligatorio) - Data inizio report
end_date (obbligatorio) - Data fine report
group_by (opzionale) - day, week, month o item

Esempio:

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

Risposta:

{
  "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": "Alta varianza, articoli nuovi frequentemente"
    }
  ]
}

Ottenere Report Riduzione Sprechi

GET /v1/forecast/analytics/waste-reduction

Traccia i risparmi sugli sprechi alimentari dall'uso di Forecast.

Parametri Query:

baseline_start (obbligatorio) - Inizio periodo baseline (pre-Forecast)
baseline_end (obbligatorio) - Fine periodo baseline
comparison_start (obbligatorio) - Inizio periodo uso Forecast
comparison_end (obbligatorio) - Fine periodo uso Forecast

Risposta:

{
  "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
  }
}

Webhook

Panoramica

I webhook permettono a Forecast di inviare notifiche push al vostro sistema invece di richiedere polling.

Casi d'Uso:

Ricevere notifiche quando nuove previsioni sono pronte
Ricevere avvisi per grandi scostamenti tra previsione ed effettivo
Monitorare problemi qualita dati
Tracciare eventi riaddestramento modello

Configurazione

Configurare Endpoint Webhook:

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"
}

Risposta:

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

Eventi Webhook

predictions.generated

Attivato quando vengono generate nuove previsioni (giornalmente alle 3:00).

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

Attivato quando vendite effettive differiscono significativamente dalla previsione (>20% default).

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

Attivato quando vengono rilevati problemi qualita dati.

Payload:

{
  "event": "data.quality_issue",
  "timestamp": "2024-01-20T04:00:00Z",
  "kitchen_id": "your_kitchen_id",
  "data": {
    "issue_type": "missing_data",
    "severity": "warning",
    "description": "Nessun dato vendite ricevuto per 2024-01-19",
    "recommendation": "Inviare dati vendite per 2024-01-19 per mantenere precisione previsioni"
  }
}

model.retrained

Attivato quando il modello viene riaddestrato con nuovi dati (settimanalmente).

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
  }
}

Sicurezza Webhook

Validazione Firma:

Tutte le richieste webhook includono header X-Forecast-Signature per verifica.

Esempio Verifica (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)

# Nel vostro handler webhook:
payload = request.body
signature = request.headers['X-Forecast-Signature']
secret = 'your_webhook_secret'

if verify_webhook_signature(payload, signature, secret):
    # Elabora webhook
    pass
else:
    # Rifiuta richiesta (potenziale problema sicurezza)
    return 401

Formati Dati e Validazione

Requisiti ID Articolo

Formato:

Solo caratteri alfanumerici, underscore, trattini
Massimo 100 caratteri
Case-sensitive
Deve essere coerente in tutte le richieste

Esempi Validi:

pasta_carbonara
grilled-salmon-lemon
ITEM_12345

Esempi Non Validi:

Pasta Carbonara (contiene spazi)
item#12345 (contiene carattere speciale)
Case diverso: Pasta_Carbonara vs pasta_carbonara (incoerente)

Formato Data

Formato Richiesto: YYYY-MM-DD (ISO 8601)

Validi:

2024-01-20
2024-12-31

Non Validi:

20-01-2024 (ordine sbagliato)
2024/01/20 (slash invece di trattini)
2024-1-20 (non zero-padded)

Validazione Quantita

Requisiti:

Solo valori interi
Minimo: 0
Massimo: 10.000 (contattare supporto per limiti superiori)
Valori negativi rifiutati

Validazione Prezzo

Requisiti:

Valori decimali (2 decimali)
Minimo: 0.00
Massimo: 999.99
Valuta non specificata (usare valuta coerente in tutti i dati)

Gestione Errori

Formato Risposta Errore

{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Formato data non valido",
    "details": {
      "field": "date",
      "value": "20-01-2024",
      "expected": "YYYY-MM-DD"
    }
  }
}

Codici Errore Comuni

Codice	Stato HTTP	Descrizione	Soluzione
`AUTHENTICATION_FAILED`	401	Chiave API non valida	Verificare che chiave API sia corretta
`RATE_LIMIT_EXCEEDED`	429	Troppe richieste	Attendere e riprovare, o richiedere aumento limiti
`VALIDATION_ERROR`	422	Formato dati non valido	Controllare formato richiesta contro documentazione
`NOT_FOUND`	404	Risorsa non trovata	Verificare kitchen_id o item_id
`INTERNAL_ERROR`	500	Errore server	Riprovare con backoff esponenziale

Logica Retry

Strategia Retry Consigliata:

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:
                # Limite frequenza - attendere e riprovare
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
            elif response.status_code >= 500:
                # Errore server - backoff esponenziale
                wait_time = 2 ** attempt
                time.sleep(wait_time)
            else:
                # Errore client - non riprovare
                raise Exception(f"Errore {response.status_code}: {response.text}")

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

    raise Exception("Numero massimo retry superato")

SDK e Librerie Client

SDK Ufficiali

SDK Python (Consigliato):

pip install eaternity-forecast

Utilizzo:

from eaternity_forecast import ForecastClient

client = ForecastClient(api_key='your_api_key')

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

# Ottenere previsioni
predictions = client.predictions.get(date='2024-01-20')

SDK JavaScript/TypeScript:

npm install @eaternity/forecast-sdk

Utilizzo:

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

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

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

SDK Community:

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

Vedi Documentazione SDK

Test

Ambiente Sandbox

Scopo: Testare integrazione senza influenzare dati produzione

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

Caratteristiche:

Credenziali autenticazione separate
Dati test possono essere resettati
Stessa API della produzione
Generazione previsioni piu veloce (per test)

Limitazioni:

Previsioni potrebbero essere meno precise (usando dati sintetici)
Nessuna garanzia SLA
Dati resettati settimanalmente

Esempio Test Integrazione

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):
        # Inviare dati storici
        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')

        # Attendere elaborazione (sandbox piu veloce)
        time.sleep(10)

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

Checklist Deploy Produzione

Pre-Lancio

Go-Live

Passaggio da sandbox a URL produzione
Aggiornate credenziali API a produzione
Monitoraggio prime 24 ore di previsioni
Verificato invio vendite giornaliero funzionante
Confermato recupero previsioni funzionante
Controllata consegna webhook (se configurati)

Post-Lancio

Tracciamento metriche precisione settimanale
Revisione e risposta ad avvisi grandi scostamenti
Fornire feedback su qualita previsioni
Ottimizzare flussi lavoro preparazione basati su confidenza
Programmate revisioni prestazioni mensili

Supporto

Supporto Tecnico

Email: forecast-api@eaternity.org

Tempi di Risposta:

Critico (produzione non funzionante): 4 ore
Alto (prestazioni degradate): 24 ore
Medio (domande, bug): 48 ore
Basso (miglioramenti): 1 settimana

Includere nelle Richieste di Supporto:

Kitchen ID
Endpoint e metodo API
Esempi richiesta/risposta
Messaggi di errore
Timestamp del problema

Documentazione

Riferimento API - Documentazione completa endpoint
Panoramica Integrazioni - Tutte le opzioni integrazione
Risoluzione Problemi - Problemi comuni

Vedi Anche

Panoramica Integrazioni - Confronto metodi integrazione
Integrazione Necta - Guida specifica Necta
Risoluzione Problemi - Problemi comuni
Riferimento API - Documentazione API completa

Panoramica API​

URL Base​

Autenticazione​

Limiti di Frequenza​

Avvio Rapido​

1. Ottenere Credenziali API​

2. Inviare Dati Storici​

3. Verificare Stato Importazione​

4. Recuperare Previsioni​

Endpoint API​

Endpoint Dati Vendite​

Inviare Vendite Giornaliere​

Importazione Massiva Storica​

Aggiornare Dati Vendite​

Endpoint Previsioni​

Ottenere Previsioni per Intervallo Date​

Ottenere Previsione per Singolo Articolo​

Modificare Previsione​

Endpoint Analisi​

Ottenere Report Precisione​

Ottenere Report Riduzione Sprechi​

Webhook​

Panoramica​

Configurazione​

Eventi Webhook​

predictions.generated​

variance.large​

data.quality_issue​

model.retrained​

Sicurezza Webhook​

Formati Dati e Validazione​

Requisiti ID Articolo​

Formato Data​

Validazione Quantita​

Validazione Prezzo​

Gestione Errori​

Formato Risposta Errore​

Codici Errore Comuni​

Logica Retry​

SDK e Librerie Client​

SDK Ufficiali​

Test​

Ambiente Sandbox​

Esempio Test Integrazione​

Checklist Deploy Produzione​

Pre-Lancio​

Go-Live​

Post-Lancio​

Supporto​

Supporto Tecnico​

Documentazione​

Vedi Anche​

Panoramica API

URL Base

Autenticazione

Limiti di Frequenza

Avvio Rapido

1. Ottenere Credenziali API

2. Inviare Dati Storici

3. Verificare Stato Importazione

4. Recuperare Previsioni

Endpoint API

Endpoint Dati Vendite

Inviare Vendite Giornaliere

Importazione Massiva Storica

Aggiornare Dati Vendite

Endpoint Previsioni

Ottenere Previsioni per Intervallo Date

Ottenere Previsione per Singolo Articolo

Modificare Previsione

Endpoint Analisi

Ottenere Report Precisione

Ottenere Report Riduzione Sprechi

Webhook

Panoramica

Configurazione

Eventi Webhook

predictions.generated

variance.large

data.quality_issue

model.retrained

Sicurezza Webhook

Formati Dati e Validazione

Requisiti ID Articolo

Formato Data

Validazione Quantita

Validazione Prezzo

Gestione Errori

Formato Risposta Errore

Codici Errore Comuni

Logica Retry

SDK e Librerie Client

SDK Ufficiali

Test

Ambiente Sandbox

Esempio Test Integrazione

Checklist Deploy Produzione

Pre-Lancio

Go-Live

Post-Lancio

Supporto

Supporto Tecnico

Documentazione

Vedi Anche