Aller au contenu principal

Depannage de l'integration

Ce guide vous aide a diagnostiquer et resoudre les problemes courants d'integration avec Eaternity Forecast.

Problemes d'authentification​

La cle d'interface de programmation ne fonctionne pas​

Symptomes :

  • Reponses 401 Non autorise
  • Erreurs « Echec de l'authentification »

Causes courantes et solutions :

1. Format de cle d'interface de programmation incorrect​

Probleme : Espaces ou caracteres supplementaires dans la cle

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 cle bac a sable en production​

Probleme : Tentative d'utiliser une cle d'interface de programmation bac a 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. Cle d'interface de programmation expiree​

Probleme : La cle a ete renouvelee ou a expire

Solution :

  1. Connectez-vous au tableau de bord Forecast
  2. Naviguez vers Parametres → Cles d'interface de programmation
  3. Generez une nouvelle cle d'interface de programmation
  4. Mettez a jour votre integration avec la nouvelle cle

4. En-tete d'autorisation manquant​

Probleme : Oubli d'inclure l'en-tete 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"

Problemes de jeton OAuth​

Symptomes :

  • Erreurs de jeton expire
  • Reponses jeton invalide

Solutions :

Implementer le rafraichissement 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;
}

Problemes de soumission de donnees​

Echec de l'import de donnees historiques​

Symptomes :

  • Import bloque en statut « processing »
  • Import echoue avec des erreurs de validation
  • Certains enregistrements ignores

Causes courantes et solutions :

1. Format de date incorrect​

Probleme : 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​

Probleme : Omission des champs de donnees 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 incoherents​

Probleme : 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 donnees incoherentes :

# 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 donnees en double​

Probleme : Soumettre la meme 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. Donnees trop volumineuses​

Probleme : Depassement des limites de taille de requete

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
  • Donnees de ventes n'apparaissant pas dans le tableau de bord
  • Previsions non mises a jour

Solutions :

Verifier la qualite des donnees​

Point d'acces 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 quantite negativeUtilisez 0 pour les articles non vendus
Item ID contains invalid charactersCaracteres speciaux dans l'IDUtilisez uniquement alphanumeriques, underscore, tiret
Date in futureDate non encore survenueSoumettez uniquement des donnees historiques
Price exceeds maximumPrix superieur a 999,99Contactez le support si legitime

Problemes de recuperation des previsions​

Previsions non disponibles​

Symptomes :

  • 404 Non trouve pour les requetes de prevision
  • Tableau de previsions vide
  • Message « No predictions generated »

Causes courantes et solutions :

1. Donnees d'entrainement insuffisantes​

Probleme : Le modele n'a pas encore fini l'entrainement

Verifier 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 termine (generalement 1-2 semaines)

2. Pas de donnees de ventes recentes​

Probleme : Pas de donnees de ventes soumises recemment

Verifier la derniere soumission de donnees :

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 donnees de ventes manquantes

3. Date future demandee au-dela de la plage​

Probleme : Demande de previsions 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​

Probleme : Demande de previsions pour un article du menu retire

Verifier 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 requetes de prevision

Problemes de precision des previsions​

Symptomes :

  • Previsions constamment trop elevees ou trop basses
  • Intervalles de confiance larges
  • MAPE superieur a 20 %

Etapes de diagnostic :

1. Verifier la note de qualite des donnees​

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 problemes de qualite des donnees identifies

2. Verifier les changements recents​

Probleme : Changements de menu, changements operationnels non refletes

Verifier 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 apres les changements de menu importants
  • Fournissez des modifications manuelles pendant la periode de transition
  • Soumettez des retours sur les raisons des ecarts

3. Identifier les erreurs systematiques​

Analyser les tendances d'ecart :

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 modele apprend avec le temps, ou fournissez des donnees de facteurs externes (meteo, evenements)

Problemes de reseau et de connectivite​

Erreurs de timeout​

Symptomes :

  • Timeout de requete apres 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 operations 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 limite de debit​

Symptomes :

  • 429 Trop de requetes
  • Message « Rate limit exceeded »

Solutions :

1. Respecter l'en-tete 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 requetes​

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 limite de debit​

Pour les integrations a fort volume :

  • E-mail forecast-api@eaternity.org
  • Fournissez le cas d'utilisation et le volume de requetes attendu
  • Limites de debit personnalisees disponibles

Problemes d'integration Necta​

Le module Forecast n'apparait pas​

Symptomes :

  • Pas d'onglet « Previsions » 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. Verifier 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. Verifier les permissions utilisateur​

Probleme : Le role utilisateur n'a pas acces a Forecast

Solution :

  • L'administrateur doit accorder les permissions Forecast
  • Naviguez vers Parametres Necta → Utilisateurs → [Votre utilisateur] → Permissions
  • Activez l'acces au module « Forecast »

Donnees non synchronisees depuis Necta​

Symptomes :

  • Previsions non mises a jour avec les dernieres donnees de ventes Necta
  • Import historique incomplet

Solutions :

1. Verifier la saisie des donnees Necta​

Verifier dans Necta :

  • Naviguez vers Ventes → Rapports quotidiens
  • Verifiez que les donnees de ventes sont saisies pour les dates recentes
  • Assurez-vous que tous les articles du menu sont enregistres

2. Verifier 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'integration​

Via le tableau de bord Necta :

  1. Naviguez vers Integrations → Eaternity Forecast
  2. Cliquez sur « Deconnecter »
  3. Cliquez sur « Reconnecter »
  4. Accordez a nouveau les permissions

Problemes de webhooks​

Webhooks non livres​

Symptomes :

  • Pas de notifications webhook recues
  • Point d'acces webhook jamais appele

Solutions :

1. Verifier 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" : Verifiez les journaux d'erreurs

2. Verifier l'accessibilite du point d'acces​

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

Problemes courants :

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

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

3. Verifier la validation de signature​

Probleme : Rejet des webhooks en raison d'echec de verification 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 apres l'evenement)
  • Temps de livraison incoherents

Causes :

  • Votre point d'acces lent a repondre
  • Congestion reseau
  • Delais de reessai apres echecs

Solutions :

1. Optimiser le temps de reponse du point d'acces​

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

Problemes de performance​

Reponses lentes de l'interface de programmation​

Symptomes :

  • Requetes prenant plus de 5 secondes
  • Temps de reponse incoherents

Etapes de diagnostic :

1. Identifier les points d'acces 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 parametres de requete​

Lent (demande 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 specifiques 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)

Problemes de qualite des donnees​

Note de qualite des donnees faible​

Symptomes :

  • Note de qualite des donnees inferieure a 80 %
  • Avertissements dans le tableau de bord
  • Previsions avec faible confiance

Etapes d'amelioration :

1. Executer le rapport de qualite des donnees​

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 problemes specifiques​

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 problemeContactDelai de reponse
Critique (Production hors service)forecast-api@eaternity.org + Telephone4 heures
Eleve (Integration cassee)forecast-api@eaternity.org24 heures
Moyen (Questions de precision)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'integration (Necta, interface de programmation personnalisee, Manuel)
  • Description du probleme
  • Etapes pour reproduire
  • Messages d'erreur (le cas echeant)
  • Captures d'ecran (si pertinent)
  • Exemple de requete/reponse (pour les problemes d'interface de programmation)

Ressources en libre-service​

Voir aussi​