Aller au contenu principal

Dépannage de l'intégration

Ce guide vous aide à diagnostiquer et résoudre les problèmes courants d'intégration avec Eaternity Forecast.

Problèmes d'authentification​

La clé d'interface de programmation ne fonctionne pas​

Symptomes :

  • Réponses 401 Non autorise
  • Erreurs « Échec de l'authentification »

Causes courantes et solutions :

1. Format de clé d'interface de programmation incorrect​

Problème : Espaces ou caractères supplémentaires dans la clé

Solution :

# Faux (espace final)
API_KEY="sk_live_abc123 "

# Correct (pas d'espaces supplementaires)
API_KEY="sk_live_abc123"

# Tester l'authentification
curl -X GET "https://api.eaternity.org/v1/forecast/ping" \
  -H "Authorization: Bearer $API_KEY"

2. Utilisation d'une clé bac à sable en production​

Problème : Tentative d'utiliser une clé d'interface de programmation bac à sable avec l'URL de production

Solution :

# Cle bac a sable (commence par sk_sandbox_)
sk_sandbox_abc123 → Utiliser avec https://sandbox-api.eaternity.org

# Cle de production (commence par sk_live_)
sk_live_abc123 → Utiliser avec https://api.eaternity.org

3. Clé d'interface de programmation expiree​

Problème : La clé a été renouvelee ou à expire

Solution :

  1. Connectez-vous au tableau de bord Forecast
  2. Naviguez vers Paramètres → Clés d'interface de programmation
  3. Generez une nouvelle clé d'interface de programmation
  4. Mettez à jour votre intégration avec la nouvelle clé

4. En-tête d'autorisation manquant​

Problème : Oubli d'inclure l'en-tête d'authentification

Solution :

# Faux (pas d'authentification)
curl -X GET "https://api.eaternity.org/v1/forecast/predictions?date=2024-01-20"

# Correct (avec authentification)
curl -X GET "https://api.eaternity.org/v1/forecast/predictions?date=2024-01-20" \
  -H "Authorization: Bearer votre_cle_api"

Problèmes de jeton OAuth​

Symptomes :

  • Erreurs de jeton expire
  • Réponses jeton invalide

Solutions :

Implementer le rafraîchissement de jeton​

async function getValidToken() {
  // Verifier si le jeton existe et est encore valide
  if (accessToken && tokenExpiresAt > Date.now()) {
    return accessToken;
  }

  // Rafraichir le jeton
  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;
}

Problèmes de soumission de données​

Échec de l'import de données historiques​

Symptomes :

  • Import bloque en statut « processing »
  • Import échoue avec des erreurs de validation
  • Certains enregistrements ignorés

Causes courantes et solutions :

1. Format de date incorrect​

Problème : Utilisation d'un mauvais format de date

Formats incorrects :

{
  "date": "20-01-2024",     // Mauvais ordre
  "date": "2024/01/20",     // Barres obliques au lieu de tirets
  "date": "2024-1-20",      // Pas de zero initial
  "date": "Jan 20, 2024"    // Format texte
}

Format correct :

{
  "date": "2024-01-20"      // AAAA-MM-JJ
}

2. Champs obligatoires manquants​

Problème : Omission des champs de données obligatoires

Solution :

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

3. IDs d'articles incohérents​

Problème : Les IDs d'articles changent entre les soumissions

Incorrect :

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

// Jour 2
{"item_id": "Pasta_Carbonara", "quantity_sold": 48}  // Casse differente

// Jour 3
{"item_id": "pasta-carbonara", "quantity_sold": 55}  // Format different

Correct :

// Tous les jours utilisent le meme ID
{"item_id": "pasta_carbonara", "quantity_sold": 52}
{"item_id": "pasta_carbonara", "quantity_sold": 48}
{"item_id": "pasta_carbonara", "quantity_sold": 55}

Corriger les données incohérentes :

# Demander une mise a jour du mappage d'ID d'article
POST /v1/forecast/items/map
{
  "kitchen_id": "votre_id_cuisine",
  "mappings": [
    {
      "variants": ["pasta_carbonara", "Pasta_Carbonara", "pasta-carbonara"],
      "canonical_id": "pasta_carbonara"
    }
  ]
}

4. Soumissions de données en double​

Problème : Soumettre la même date plusieurs fois

Solution :

# Premiere soumission (Jour 1)
POST /v1/forecast/sales
{"date": "2024-01-20", "items": [...]}

# Correction necessaire plus tard
# Utilisez PATCH au lieu de POST
PATCH /v1/forecast/sales/2024-01-20
{"items": [{"item_id": "pasta_carbonara", "quantity_sold": 54}]}

5. Données trop volumineuses​

Problème : Dépassement des limites de taille de requête

Solution :

# Incorrect : Toutes les donnees en une requete
bulk_import(sales_data_90_days)  # Peut depasser la limite

# Correct : Diviser en lots
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)  # Eviter les limites de debit

Echecs de soumission des ventes quotidiennes​

Symptomes :

  • Erreurs de validation 422
  • Données de ventes n'apparaissant pas dans le tableau de bord
  • Prévisions non mises à jour

Solutions :

Vérifier la qualité des données​

Point d'accès de validation :

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

# La reponse montre les problemes de validation
{
  "valid": false,
  "errors": [
    {
      "field": "items[2].quantity_sold",
      "value": -5,
      "issue": "Quantity cannot be negative"
    }
  ]
}

Erreurs de validation courantes​

ErreurCauseSolution
Quantity cannot be negativeValeur de quantité négativeUtilisez 0 pour les articles non vendus
Item ID contains invalid charactersCaractères spéciaux dans l'IDUtilisez uniquement alphanumériques, underscore, tiret
Date in futureDate non encore survenueSoumettez uniquement des données historiques
Price exceeds maximumPrix supérieur à 999,99Contactez le support si legitime

Problèmes de récupération des prévisions​

Prévisions non disponibles​

Symptomes :

  • 404 Non trouvé pour les requêtes de prévision
  • Tableau de prévisions vide
  • Message « No predictions generated »

Causes courantes et solutions :

1. Données d'entrainement insuffisantes​

Problème : Le modèle n'a pas encore fini l'entrainement

Vérifier le statut de l'entrainement :

GET /v1/forecast/training/status

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

Solution : Attendez que l'entrainement soit terminé (généralement 1-2 semaines)

2. Pas de données de ventes récentes​

Problème : Pas de données de ventes soumises récemment

Vérifier la dernière soumission de données :

GET /v1/forecast/sales/last

# Reponse
{
  "last_submission": "2024-01-15",
  "days_ago": 5,
  "warning": "No data submitted in 5 days. Prediction accuracy may decline."
}

Solution : Soumettez les données de ventes manquantes

3. Date future demandee au-delà de la plage​

Problème : Demande de prévisions trop loin dans le futur

Incorrect :

# Aujourd'hui est le 2024-01-20
GET /v1/forecast/predictions?date=2024-02-15  # 26 jours a l'avance

Correct :

# Maximum 14 jours a l'avance
GET /v1/forecast/predictions?date=2024-02-03  # 14 jours a l'avance

4. Article retire​

Problème : Demande de prévisions pour un article du menu retire

Vérifier le statut de l'article :

GET /v1/forecast/items/pasta_carbonara

# Reponse
{
  "item_id": "pasta_carbonara",
  "status": "discontinued",
  "last_sold": "2024-01-10",
  "reason": "Zero sales for 10 consecutive days"
}

Solution : Reactiver l'article ou le retirer des requêtes de prévision

Problèmes de précision des prévisions​

Symptomes :

  • Prévisions constamment trop élevées ou trop basses
  • Intervalles de confiance larges
  • MAPE supérieur à 20 %

Étapes de diagnostic :

1. Vérifier la note de qualité des données​

GET /v1/forecast/analytics/data-quality

# Reponse
{
  "overall_score": 65,  // En dessous de 80 %
  "issues": [
    {
      "type": "missing_dates",
      "severity": "high",
      "details": "Missing sales data for 12 days in last 30 days"
    },
    {
      "type": "inconsistent_naming",
      "severity": "medium",
      "details": "15 items with name variations"
    }
  ],
  "recommendations": [
    "Submit missing sales data for: 2024-01-05, 2024-01-08, ..."
  ]
}

Solution : Traitez les problèmes de qualité des données identifiés

2. Vérifier les changements récents​

Problème : Changements de menu, changements opérationnels non reflétés

Vérifier le journal des changements :

GET /v1/forecast/changelog

# Reponse
{
  "recent_changes": [
    {
      "date": "2024-01-15",
      "type": "menu_change",
      "details": "5 new items added, 3 items removed"
    }
  ]
}

Solution :

  • Attendez 2-3 semaines après les changements de menu importants
  • Fournissez des modifications manuelles pendant la période de transition
  • Soumettez des retours sur les raisons des écarts

3. Identifier les erreurs systematiques​

Analyser les tendances d'écart :

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

# La reponse montre les tendances
{
  "patterns": [
    {
      "pattern": "consistently_over_predicting",
      "items_affected": ["salad_items"],
      "magnitude": "+15%",
      "possible_cause": "Seasonal decline not yet learned"
    }
  ]
}

Solution : Le modèle apprend avec le temps, ou fournissez des données de facteurs externes (météo, événements)

Problèmes de réseau et de connectivite​

Erreurs de timeout​

Symptomes :

  • Timeout de requête après 30 secondes
  • Erreurs 504 Gateway Timeout

Solutions :

1. Augmenter le timeout client​

import requests

# Incorrect : Timeout par defaut trop court
response = requests.get(url)

# Correct : Specifier le timeout
response = requests.get(url, timeout=60)  # 60 secondes

2. Utiliser l'asynchrone pour les opérations en masse​

// Incorrect : Requetes sequentielles (lent)
for (const date of dates) {
  await submitSales(date);
}

// Correct : Requetes paralleles (rapide)
await Promise.all(dates.map(date => submitSales(date)));

Erreurs de limité de débit​

Symptomes :

  • 429 Trop de requêtes
  • Message « Rate limit exceeded »

Solutions :

1. Respecter l'en-tête 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"Rate limited. Waiting {retry_after} seconds...")
        time.sleep(retry_after)
        return make_request(url)  # Reessayer

    return response

2. Implementer une file d'attente de requêtes​

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

        # Supprimer les requetes de plus d'une minute
        while self.request_times and self.request_times[0] < now - 60:
            self.request_times.popleft()

        # Verifier si a la limite
        if len(self.request_times) >= self.requests_per_minute:
            sleep_time = 60 - (now - self.request_times[0])
            sleep(sleep_time)

        # Faire la requete
        response = requests.get(url)
        self.request_times.append(time.time())
        return response

3. Demander une augmentation de limité de débit​

Pour les intégrations à fort volume :

  • E-mail forecast-api@eaternity.org
  • Fournissez le cas d'utilisation et le volume de requêtes attendu
  • Limites de débit personnalisées disponibles

Problèmes d'intégration Necta​

Le module Forecast n'apparaît pas​

Symptomes :

  • Pas d'onglet « Prévisions » dans le module Planification Necta
  • Activation confirmee mais interface inchangee

Solutions :

1. Vider le cache du navigateur​

1. Fermez completement Necta
2. Videz le cache du navigateur :
   - Chrome : Parametres → Confidentialite → Effacer les donnees de navigation
   - Firefox : Options → Vie privee → Effacer les donnees
3. Redemarrez le navigateur
4. Reconnectez-vous a Necta

2. Vérifier le statut d'activation​

Contactez le support Necta :

Objet : Statut d'activation du module Forecast

ID de compte : [Votre ID de compte Necta]
Probleme : Module Forecast non visible apres activation
Date d'activation : [Date a laquelle on vous a dit qu'il etait active]

3. Vérifier les permissions utilisateur​

Problème : Le role utilisateur n'a pas accès à Forecast

Solution :

  • L'administrateur doit accorder les permissions Forecast
  • Naviguez vers Paramètres Necta → Utilisateurs → [Votre utilisateur] → Permissions
  • Activez l'accès au module « Forecast »

Données non synchronisees depuis Necta​

Symptomes :

  • Prévisions non mises à jour avec les dernières données de ventes Necta
  • Import historique incomplet

Solutions :

1. Vérifier la saisie des données Necta​

Vérifier dans Necta :

  • Naviguez vers Ventes → Rapports quotidiens
  • Vérifiez que les données de ventes sont saisies pour les dates récentes
  • Assurez-vous que tous les articles du menu sont enregistres

2. Vérifier le statut de synchronisation​

Contactez le support Eaternity :

Objet : Probleme de synchronisation des donnees Necta

ID cuisine : [Votre ID cuisine]
ID compte Necta : [Votre ID compte Necta]
Derniere synchronisation reussie : [Verifier dans le tableau de bord Forecast]
Dates manquantes : [Lister les dates sans synchronisation]

3. Reconnecter l'intégration​

Via le tableau de bord Necta :

  1. Naviguez vers Intégrations → Eaternity Forecast
  2. Cliquez sur « Deconnecter »
  3. Cliquez sur « Reconnecter »
  4. Accordez à nouveau les permissions

Problèmes de webhooks​

Webhooks non livres​

Symptomes :

  • Pas de notifications webhook reçues
  • Point d'accès webhook jamais appele

Solutions :

1. Vérifier la configuration webhook​

GET /v1/forecast/webhooks

# Verifier la configuration
{
  "webhooks": [
    {
      "webhook_id": "wh_123",
      "url": "https://votre-systeme.com/webhooks/forecast",
      "events": ["predictions.generated"],
      "status": "active",
      "last_delivery": "2024-01-20T03:16:00Z"
    }
  ]
}

Si status: "failed" : Vérifiez les journaux d'erreurs

2. Vérifier l'accessibilite du point d'accès​

Tester depuis un service externe :

# Utilisez webhook.site ou similaire pour tester
curl -X POST "https://votre-systeme.com/webhooks/forecast" \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

Problèmes courants :

  • Pare-feu bloquant les IP Forecast
  • Certificat HTTPS invalide
  • Point d'accès retournant un code de statut non-2xx

Solution : Mettez en liste blanche les IP Forecast (contactez le support pour la liste)

3. Vérifier la validation de signature​

Problème : Rejet des webhooks en raison d'échec de vérification de signature

Deboguer la validation de signature :

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    # Calculer la signature attendue
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    # Sortie de debogage
    print(f"Received signature: {signature}")
    print(f"Expected signature: {expected}")
    print(f"Match: {hmac.compare_digest(signature, expected)}")

    return hmac.compare_digest(signature, expected)

Delais de livraison des webhooks​

Symptomes :

  • Webhooks arrivent en retard (plus de 5 minutes après l'événement)
  • Temps de livraison incohérents

Causes :

  • Votre point d'accès lent à répondre
  • Congestion réseau
  • Delais de reessai après echecs

Solutions :

1. Optimiser le temps de réponse du point d'accès​

// Incorrect : Traitement lent bloque la reponse
app.post('/webhooks/forecast', async (req, res) => {
  await processWebhook(req.body);  // Operation lente
  res.status(200).send('OK');
});

// Correct : Accuser reception immediatement, traiter de maniere asynchrone
app.post('/webhooks/forecast', async (req, res) => {
  res.status(200).send('OK');  // Repondre immediatement

  // Traiter de maniere asynchrone
  processWebhookAsync(req.body).catch(err => {
    console.error('Webhook processing error:', err);
  });
});

2. Surveiller la livraison des webhooks​

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

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

Problèmes de performance​

Réponses lentes de l'interface de programmation​

Symptomes :

  • Requêtes prenant plus de 5 secondes
  • Temps de réponse incohérents

Étapes de diagnostic :

1. Identifier les points d'accès lents​

# Ajouter un chronometre aux requetes
time curl -X GET "https://api.eaternity.org/v1/forecast/predictions?date=2024-01-20" \
  -H "Authorization: Bearer votre_cle_api"

2. Optimiser les paramètres de requête​

Lent (demandé tous les articles) :

GET /v1/forecast/predictions?date=2024-01-20&end_date=2024-01-27
# Retourne 65 articles × 7 jours = 455 previsions

Rapide (articles spécifiques uniquement) :

GET /v1/forecast/predictions?date=2024-01-20&items=pasta_carbonara,grilled_salmon
# Retourne 2 articles × 1 jour = 2 previsions

3. Utiliser le cache​

import time
from functools import lru_cache

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

# Le cache expire apres 1 heure
def get_predictions_with_expiry(date):
    cache_key = f"{date}_{int(time.time() // 3600)}"
    return get_predictions_cached(cache_key)

Problèmes de qualité des données​

Note de qualité des données faible​

Symptomes :

  • Note de qualité des données inférieure à 80 %
  • Avertissements dans le tableau de bord
  • Prévisions avec faible confiance

Étapes d'amélioration :

1. Exécuter le rapport de qualité des données​

GET /v1/forecast/analytics/data-quality

# Rapport detaille
{
  "overall_score": 72,
  "components": {
    "completeness": 85,    # Certaines dates manquantes
    "consistency": 65,     # Problemes de denomination
    "accuracy": 80,        # Quelques valeurs aberrantes
    "timeliness": 70       # Soumissions en retard
  },
  "issues": [...]
}

2. Corriger les problèmes spécifiques​

Dates manquantes :

# Soumettre les donnees manquantes
POST /v1/forecast/sales
{
  "date": "2024-01-15",
  "items": [...]
}

Denomination incoherente :

# Standardiser les noms d'articles
POST /v1/forecast/items/standardize
{
  "standardizations": [
    {
      "variants": ["pasta carbonara", "Pasta Carbonara", "PASTA_CARBONARA"],
      "standard": "pasta_carbonara"
    }
  ]
}

Valeurs aberrantes :

# Signaler et expliquer les valeurs aberrantes
POST /v1/forecast/sales/2024-01-15/annotate
{
  "item_id": "grilled_salmon",
  "note": "Holiday event, 2x normal volume expected",
  "type": "special_event"
}

Obtenir de l'aide​

Canaux de support​

Type de problèmeContactDélai de réponse
Critique (Production hors service)forecast-api@eaternity.org + Telephone4 heures
Eleve (Intégration cassee)forecast-api@eaternity.org24 heures
Moyen (Questions de précision)forecast@eaternity.org48 heures
Faible (Questions generales)Documentation ou e-mail1 semaine

Informations a inclure​

Dans toutes les demandes de support :

  • ID cuisine
  • Type d'intégration (Necta, interface de programmation personnalisée, Manuel)
  • Description du problème
  • Étapes pour reproduire
  • Messages d'erreur (le cas échéant)
  • Capturés d'écran (si pertinent)
  • Exemple de requête/réponse (pour les problèmes d'interface de programmation)

Ressources en libre-service​

Voir aussi​