Risoluzione Problemi Integrazione

Questa guida vi aiuta a diagnosticare e risolvere i problemi di integrazione comuni con Eaternity Forecast.

Problemi di Autenticazione

Chiave API Non Funziona

Sintomi:

• Risposte 401 Unauthorized
• Errori "Authentication failed"

Cause Comuni e Soluzioni:

1. Formato Chiave API Errato

Problema: Spazi extra o caratteri nella chiave API

Soluzione:

# Sbagliato (spazio finale)
API_KEY="sk_live_abc123 "

# Corretto (nessuno spazio extra)
API_KEY="sk_live_abc123"

# Testa autenticazione
curl -X GET "https://api.eaternity.org/v1/forecast/ping" \
  -H "Authorization: Bearer $API_KEY"

2. Uso Chiave Sandbox in Produzione

Problema: Tentativo di usare chiave API sandbox con URL produzione

Soluzione:

# Chiave sandbox (inizia con sk_sandbox_)
sk_sandbox_abc123 → Usare con https://sandbox-api.eaternity.org

# Chiave produzione (inizia con sk_live_)
sk_live_abc123 → Usare con https://api.eaternity.org

3. Chiave API Scaduta

Problema: Chiave API e stata ruotata o e scaduta

Soluzione:

1. Accedete al pannello di controllo Forecast
2. Navigate a Impostazioni → Chiavi API
3. Generate nuova chiave API
4. Aggiornate la vostra integrazione con nuova chiave

4. Header Authorization Mancante

Problema: Dimenticato di includere header di autenticazione

Soluzione:

# Sbagliato (senza auth)
curl -X GET "https://api.eaternity.org/v1/forecast/predictions?date=2024-01-20"

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

Problemi Token OAuth

Sintomi:

• Errori token scaduto
• Risposte token non valido

Soluzioni:

Implementare Refresh Token

async function getValidToken() {
  // Verifica se token esiste ed e ancora valido
  if (accessToken && tokenExpiresAt > Date.now()) {
    return accessToken;
  }

  // Refresh token
  const response = await fetch('https://api.eaternity.org/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: clientId,
      client_secret: clientSecret
    })
  });

  const data = await response.json();
  accessToken = data.access_token;
  tokenExpiresAt = Date.now() + (data.expires_in * 1000);

  return accessToken;
}

Problemi Invio Dati

Importazione Dati Storici Fallisce

Sintomi:

• Importazione bloccata in stato "processing"
• Importazione fallisce con errori validazione
• Alcuni record saltati

Cause Comuni e Soluzioni:

1. Formato Data Errato

Problema: Uso formato data sbagliato

Formati Sbagliati:

{
  "date": "20-01-2024",     // Ordine sbagliato
  "date": "2024/01/20",     // Slash invece di trattini
  "date": "2024-1-20",      // Non zero-padded
  "date": "Jan 20, 2024"    // Formato testo
}

Formato Corretto:

{
  "date": "2024-01-20"      // YYYY-MM-DD
}

2. Campi Obbligatori Mancanti

Problema: Omissione campi dati obbligatori

Soluzione:

{
  "kitchen_id": "your_kitchen_id",  // Obbligatorio
  "date": "2024-01-20",              // Obbligatorio
  "items": [                         // Obbligatorio
    {
      "item_id": "pasta_carbonara",  // Obbligatorio
      "quantity_sold": 52,           // Obbligatorio
      "name": "Pasta Carbonara",     // Consigliato
      "price": 14.50,                // Consigliato
      "category": "Main Course"      // Consigliato
    }
  ]
}

3. ID Articolo Incoerenti

Problema: Gli ID articolo cambiano tra invii

Sbagliato:

// Giorno 1
{"item_id": "pasta_carbonara", "quantity_sold": 52}

// Giorno 2
{"item_id": "Pasta_Carbonara", "quantity_sold": 48}  // Case diverso

// Giorno 3
{"item_id": "pasta-carbonara", "quantity_sold": 55}  // Formato diverso

Corretto:

// Tutti i giorni usano stesso ID
{"item_id": "pasta_carbonara", "quantity_sold": 52}
{"item_id": "pasta_carbonara", "quantity_sold": 48}
{"item_id": "pasta_carbonara", "quantity_sold": 55}

Correggere Dati Incoerenti:

# Richiesta aggiornamento mappatura ID articolo
POST /v1/forecast/items/map
{
  "kitchen_id": "your_kitchen_id",
  "mappings": [
    {
      "variants": ["pasta_carbonara", "Pasta_Carbonara", "pasta-carbonara"],
      "canonical_id": "pasta_carbonara"
    }
  ]
}

4. Invii Dati Duplicati

Problema: Invio stessa data piu volte

Soluzione:

# Primo invio (Giorno 1)
POST /v1/forecast/sales
{"date": "2024-01-20", "items": [...]}

# Correzione necessaria dopo
# Usare PATCH invece di POST
PATCH /v1/forecast/sales/2024-01-20
{"items": [{"item_id": "pasta_carbonara", "quantity_sold": 54}]}

5. Dati Troppo Grandi

Problema: Superamento limiti dimensione richiesta

Soluzione:

# Sbagliato: Tutti i dati in una richiesta
bulk_import(sales_data_90_days)  # Potrebbe superare limite

# Corretto: Dividere in chunk
def chunk_data(data, chunk_size=30):
    for i in range(0, len(data), chunk_size):
        yield data[i:i + chunk_size]

for chunk in chunk_data(sales_data, chunk_size=30):
    bulk_import(chunk)
    time.sleep(1)  # Evitare limiti frequenza

Fallimenti Invio Vendite Giornaliere

Sintomi:

• Errori validazione 422
• Dati vendite non appaiono nel pannello di controllo
• Previsioni non si aggiornano

Soluzioni:

Verificare Qualita Dati

Endpoint Validazione:

POST /v1/forecast/sales/validate
{
  "kitchen_id": "your_kitchen_id",
  "date": "2024-01-20",
  "items": [...]
}

# Risposta mostra problemi validazione
{
  "valid": false,
  "errors": [
    {
      "field": "items[2].quantity_sold",
      "value": -5,
      "issue": "Quantity cannot be negative"
    }
  ]
}

Errori Validazione Comuni

Errore	Causa	Soluzione
Quantity cannot be negative	Valore quantita negativo	Usare 0 per articoli non venduti
Item ID contains invalid characters	Caratteri speciali nell'ID	Usare solo alfanumerici, underscore, trattino
Date in future	Data non ancora trascorsa	Inviare solo dati storici
Price exceeds maximum	Prezzo > 999.99	Contattare supporto se legittimo

Problemi Recupero Previsioni

Previsioni Non Disponibili

Sintomi:

• 404 Not Found per richieste previsioni
• Array previsioni vuoto
• Messaggio "No predictions generated"

Cause Comuni e Soluzioni:

1. Dati Addestramento Insufficienti

Problema: Modello non ha ancora finito addestramento

Verificare Stato Addestramento:

GET /v1/forecast/training/status

# Risposta
{
  "status": "training",
  "progress": 45,
  "expected_completion": "2024-01-25T10:00:00Z"
}

Soluzione: Attendere completamento addestramento (tipicamente 1-2 settimane)

2. Nessun Dato Vendite Recente

Problema: Non avete inviato dati vendite di recente

Verificare Ultimo Invio Dati:

GET /v1/forecast/sales/last

# Risposta
{
  "last_submission": "2024-01-15",
  "days_ago": 5,
  "warning": "Nessun dato inviato da 5 giorni. Precisione previsioni potrebbe calare."
}

Soluzione: Inviate dati vendite mancanti

3. Richiesta Data Futura Oltre Range

Problema: Richiesta previsioni troppo in anticipo

Sbagliato:

# Oggi e 2024-01-20
GET /v1/forecast/predictions?date=2024-02-15  # 26 giorni avanti

Corretto:

# Massimo 14 giorni avanti
GET /v1/forecast/predictions?date=2024-02-03  # 14 giorni avanti

4. Articolo Dismesso

Problema: Richiesta previsioni per articolo menu rimosso

Verificare Stato Articolo:

GET /v1/forecast/items/pasta_carbonara

# Risposta
{
  "item_id": "pasta_carbonara",
  "status": "discontinued",
  "last_sold": "2024-01-10",
  "reason": "Zero vendite per 10 giorni consecutivi"
}

Soluzione: Riattivate articolo o rimuovete dalle richieste previsioni

Problemi Precisione Previsioni

Sintomi:

• Previsioni costantemente troppo alte o basse
• Intervalli confidenza ampi
• MAPE > 20%

Passi Diagnostici:

1. Verificare Punteggio Qualita Dati

GET /v1/forecast/analytics/data-quality

# Risposta
{
  "overall_score": 65,  // Sotto 80%
  "issues": [
    {
      "type": "missing_dates",
      "severity": "high",
      "details": "Dati vendite mancanti per 12 giorni negli ultimi 30"
    },
    {
      "type": "inconsistent_naming",
      "severity": "medium",
      "details": "15 articoli con variazioni nome"
    }
  ],
  "recommendations": [
    "Inviare dati vendite mancanti per: 2024-01-05, 2024-01-08, ..."
  ]
}

Soluzione: Risolvete problemi qualita dati identificati

2. Verificare Cambiamenti Recenti

Problema: Cambi menu, cambi operativi non riflessi

Verificare Log Modifiche:

GET /v1/forecast/changelog

# Risposta
{
  "recent_changes": [
    {
      "date": "2024-01-15",
      "type": "menu_change",
      "details": "5 nuovi articoli aggiunti, 3 articoli rimossi"
    }
  ]
}

Soluzione:

• Attendete 2-3 settimane dopo cambi menu importanti
• Fornite modifiche manuali durante periodo transizione
• Inviate feedback sui motivi scostamenti

3. Identificare Errori Sistematici

Analizzare Pattern Scostamenti:

GET /v1/forecast/analytics/variance-analysis?days=30

# Risposta mostra pattern
{
  "patterns": [
    {
      "pattern": "consistently_over_predicting",
      "items_affected": ["salad_items"],
      "magnitude": "+15%",
      "possible_cause": "Declino stagionale non ancora appreso"
    }
  ]
}

Soluzione: Il modello impara nel tempo, o fornite dati fattori esterni (meteo, eventi)

Problemi Rete e Connettivita

Errori Timeout

Sintomi:

• Timeout richiesta dopo 30 secondi
• Errori 504 Gateway Timeout

Soluzioni:

1. Aumentare Timeout Client

import requests

# Sbagliato: Timeout default troppo breve
response = requests.get(url)

# Corretto: Specificare timeout
response = requests.get(url, timeout=60)  # 60 secondi

2. Usare Async per Operazioni Bulk

// Sbagliato: Richieste sequenziali (lento)
for (const date of dates) {
  await submitSales(date);
}

// Corretto: Richieste parallele (veloce)
await Promise.all(dates.map(date => submitSales(date)));

Errori Limite Frequenza

Sintomi:

• 429 Too Many Requests
• Messaggio "Rate limit exceeded"

Soluzioni:

1. Rispettare Header Retry-After

import time
import requests

def make_request(url):
    response = requests.get(url)

    if response.status_code == 429:
        retry_after = int(response.headers.get('Retry-After', 60))
        print(f"Limite frequenza. Attesa {retry_after} secondi...")
        time.sleep(retry_after)
        return make_request(url)  # Riprova

    return response

2. Implementare Coda Richieste

from time import sleep
from collections import deque

class RateLimitedClient:
    def __init__(self, requests_per_minute=100):
        self.requests_per_minute = requests_per_minute
        self.request_times = deque()

    def make_request(self, url):
        now = time.time()

        # Rimuovi richieste piu vecchie di 1 minuto
        while self.request_times and self.request_times[0] < now - 60:
            self.request_times.popleft()

        # Verifica se al limite
        if len(self.request_times) >= self.requests_per_minute:
            sleep_time = 60 - (now - self.request_times[0])
            sleep(sleep_time)

        # Effettua richiesta
        response = requests.get(url)
        self.request_times.append(time.time())
        return response

3. Richiedere Aumento Limite Frequenza

Per integrazioni ad alto volume:

• Email forecast-api@eaternity.org
• Fornite caso d'uso e volume richieste previsto
• Limiti personalizzati disponibili

Problemi Integrazione Necta

Modulo Forecast Non Appare

Sintomi:

• Nessuna tab "Forecast" nel modulo Pianificazione Necta
• Attivazione confermata ma interfaccia invariata

Soluzioni:

1. Svuotare Cache Browser

1. Chiudete Necta completamente
2. Svuotate cache browser:
   - Chrome: Impostazioni → Privacy → Cancella dati navigazione
   - Firefox: Opzioni → Privacy → Cancella dati
3. Riavviate browser
4. Accedete nuovamente a Necta

2. Verificare Stato Attivazione

Contattate supporto Necta:

Oggetto: Stato Attivazione Modulo Forecast

ID Account: [Vostro ID Account Necta]
Problema: Modulo Forecast non visibile dopo attivazione
Data Attivazione: [Data in cui vi e stato detto era attivato]

3. Verificare Permessi Utente

Problema: Ruolo utente non ha accesso Forecast

Soluzione:

• Admin deve concedere permessi Forecast
• Navigate a Impostazioni Necta → Utenti → [Vostro Utente] → Permessi
• Abilitate accesso modulo "Forecast"

Dati Non Si Sincronizzano da Necta

Sintomi:

• Previsioni non si aggiornano con ultimi dati vendite Necta
• Importazione storica incompleta

Soluzioni:

1. Verificare Inserimento Dati Necta

Controllare in Necta:

• Navigate a Vendite → Report Giornalieri
• Verificate che dati vendite siano inseriti per date recenti
• Assicuratevi che tutti gli articoli menu siano registrati

2. Verificare Stato Sincronizzazione

Contattate supporto Eaternity:

Oggetto: Problema Sincronizzazione Dati Necta

Kitchen ID: [Vostro Kitchen ID]
ID Account Necta: [Vostro ID Account Necta]
Ultima Sincronizzazione Riuscita: [Controllare nel pannello Forecast]
Date Mancanti: [Elencare date senza sincronizzazione]

3. Riconnettere Integrazione

Via Pannello Necta:

1. Navigate a Integrazioni → Eaternity Forecast
2. Cliccate "Disconnetti"
3. Cliccate "Riconnetti"
4. Concedete nuovamente permessi

Problemi Webhook

Webhook Non Consegnati

Sintomi:

• Nessuna notifica webhook ricevuta
• Endpoint webhook mai chiamato

Soluzioni:

1. Verificare Configurazione Webhook

GET /v1/forecast/webhooks

# Verificare configurazione
{
  "webhooks": [
    {
      "webhook_id": "wh_123",
      "url": "https://your-system.com/webhooks/forecast",
      "events": ["predictions.generated"],
      "status": "active",
      "last_delivery": "2024-01-20T03:16:00Z"
    }
  ]
}

Se status: "failed": Controllate log errori

2. Verificare Accessibilita Endpoint

Testare da Servizio Esterno:

# Usare webhook.site o simile per test
curl -X POST "https://your-system.com/webhooks/forecast" \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

Problemi Comuni:

• Firewall blocca IP Forecast
• Certificato HTTPS non valido
• Endpoint restituisce codice stato non-2xx

Soluzione: Whitelisting IP Forecast (contattare supporto per lista)

3. Verificare Validazione Firma

Problema: Rifiuto webhook per fallimento verifica firma

Debug Validazione Firma:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    # Calcola firma attesa
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Output debug
    print(f"Firma ricevuta: {signature}")
    print(f"Firma attesa: {expected}")
    print(f"Match: {hmac.compare_digest(signature, expected)}")

    return hmac.compare_digest(signature, expected)

Ritardi Consegna Webhook

Sintomi:

• Webhook arrivano in ritardo (>5 minuti dopo evento)
• Tempi consegna incoerenti

Cause:

• Vostro endpoint lento a rispondere
• Congestione rete
• Ritardi retry dopo fallimenti

Soluzioni:

1. Ottimizzare Tempo Risposta Endpoint

// Sbagliato: Elaborazione lenta blocca risposta
app.post('/webhooks/forecast', async (req, res) => {
  await processWebhook(req.body);  // Operazione lenta
  res.status(200).send('OK');
});

// Corretto: Rispondere immediatamente, elaborare async
app.post('/webhooks/forecast', async (req, res) => {
  res.status(200).send('OK');  // Rispondi subito

  // Elabora in modo asincrono
  processWebhookAsync(req.body).catch(err => {
    console.error('Errore elaborazione webhook:', err);
  });
});

2. Monitorare Consegna Webhook

GET /v1/forecast/webhooks/wh_123/deliveries?limit=50

# Controllare consegne recenti
{
  "deliveries": [
    {
      "delivery_id": "del_abc123",
      "event": "predictions.generated",
      "timestamp": "2024-01-20T03:15:42Z",
      "response_code": 200,
      "response_time_ms": 350,
      "status": "success"
    }
  ]
}

Problemi di Prestazioni

Risposte API Lente

Sintomi:

• Richieste che impiegano >5 secondi
• Tempi risposta incoerenti

Passi Diagnostici:

1. Identificare Endpoint Lenti

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

2. Ottimizzare Parametri Richiesta

Lento (richiesta tutti articoli):

GET /v1/forecast/predictions?date=2024-01-20&end_date=2024-01-27
# Restituisce 65 articoli x 7 giorni = 455 previsioni

Veloce (solo articoli specifici):

GET /v1/forecast/predictions?date=2024-01-20&items=pasta_carbonara,grilled_salmon
# Restituisce 2 articoli x 1 giorno = 2 previsioni

3. Usare Caching

import time
from functools import lru_cache

@lru_cache(maxsize=100)
def get_predictions_cached(date):
    return get_predictions(date)

# Cache scade dopo 1 ora
def get_predictions_with_expiry(date):
    cache_key = f"{date}_{int(time.time() // 3600)}"
    return get_predictions_cached(cache_key)

Problemi Qualita Dati

Punteggio Qualita Dati Basso

Sintomi:

• Punteggio qualita dati inferiore all'80%
• Avvisi nel pannello di controllo
• Previsioni con bassa confidenza

Passi Miglioramento:

1. Eseguire Report Qualita Dati

GET /v1/forecast/analytics/data-quality

# Report dettagliato
{
  "overall_score": 72,
  "components": {
    "completeness": 85,    # Alcune date mancanti
    "consistency": 65,     # Problemi naming
    "accuracy": 80,        # Alcuni outlier
    "timeliness": 70       # Invii ritardati
  },
  "issues": [...]
}

2. Correggere Problemi Specifici

Date Mancanti:

# Inviare dati mancanti
POST /v1/forecast/sales
{
  "date": "2024-01-15",
  "items": [...]
}

Naming Incoerente:

# Standardizzare nomi articoli
POST /v1/forecast/items/standardize
{
  "standardizations": [
    {
      "variants": ["pasta carbonara", "Pasta Carbonara", "PASTA_CARBONARA"],
      "standard": "pasta_carbonara"
    }
  ]
}

Outlier:

# Segnalare e spiegare outlier
POST /v1/forecast/sales/2024-01-15/annotate
{
  "item_id": "grilled_salmon",
  "note": "Evento festivita, volume 2x normale atteso",
  "type": "special_event"
}

Ottenere Assistenza

Canali Supporto

Tipo Problema	Contatto	Tempo Risposta
Critico (Produzione non funzionante)	forecast-api@eaternity.org + Telefono	4 ore
Alto (Integrazione non funziona)	forecast-api@eaternity.org	24 ore
Medio (Domande precisione)	forecast@eaternity.org	48 ore
Basso (Domande generali)	Documentazione o email	1 settimana

Informazioni da Includere

In tutte le richieste di supporto:

• Kitchen ID
• Tipo integrazione (Necta, API Personalizzata, Manuale)
• Descrizione problema
• Passi per riprodurre
• Messaggi di errore (se presenti)
• Screenshot (se rilevanti)
• Esempio richiesta/risposta (per problemi API)

Risorse Self-Service

• Riferimento API - Documentazione API completa
• Panoramica Integrazioni - Tutte le opzioni integrazione
• Integrazione Necta - Guida specifica Necta
• Integrazione API Personalizzata - Guida API REST
• Guida all'Implementazione - Migliori pratiche flusso lavoro quotidiano

Vedi Anche

• Panoramica Integrazioni - Tutte le opzioni integrazione
• Integrazione Necta - Configurazione specifica Necta
• Integrazione API Personalizzata - Guida API REST
• Riferimento API - Documentazione API completa