JSON personnalisé : schéma et configuration des destinations

Introduction

Les destinations JSON personnalisées permettent d'envoyer vos données produits vers des endpoints configurables en utilisant un schéma JSON structuré selon vos besoins. Contrairement aux canaux de distribution prédéfinis, cette approche offre une flexibilité complète : vous définissez la structure des données, les champs inclus, et le format de transmission.

Cet article explique comment configurer une destination JSON personnalisée, valider votre schéma, et optimiser l'intégration de vos flux de produits en temps réel ou par lots.

Principes fondamentaux des destinations JSON personnalisées

Une destination JSON personnalisée repose sur trois éléments clés :

1. Endpoint de destination : l'URL où vos données sont envoyées (protocole HTTPS obligatoire).
2. Schéma JSON : la structure définissant quels champs produits sont transmis et comment ils sont organisés.
3. Validation et authentification : les mécanismes de sécurité et de vérification des données avant envoi.

Chaque destination configurée crée un pipeline de données indépendant. Vous pouvez maintenir plusieurs destinations JSON personnalisées simultanément, chacune avec son propre schéma et son propre endpoint. Cette architecture permet de distribuer vos données produits à plusieurs systèmes backend, plateformes d'analyse, ou services tiers sans modifier votre flux principal.

La transmission peut s'effectuer en temps réel (à chaque mise à jour de produit) ou selon un calendrier défini (quotidien, hebdomadaire). Le stockage des données chez la destination est de votre responsabilité : nous transmettons les données structurées, vous gérez leur archivage et leur récupération.

Configuration d'une destination JSON personnalisée

Étapes de mise en place

Pour créer une destination JSON personnalisée, vous devez :

1. Accéder à la section Destinations dans votre tableau de bord.
2. Sélectionner le type 'JSON personnalisé' et créer une nouvelle destination.
3. Fournir l'endpoint HTTPS où les données seront envoyées.
4. Définir le schéma JSON qui décrit la structure de vos données produits.
5. Configurer les paramètres d'authentification (clés API, tokens, en-têtes personnalisés).
6. Valider le schéma avant de l'activer en production.
7. Tester l'envoi avec un produit d'exemple pour confirmer la connectivité.

Paramètres de configuration essentiels

Structure du schéma JSON

Format de base

Votre schéma JSON définit la structure des données transmises. Voici un exemple simplifié :

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Identifiant unique du produit"
    },
    "title": {
      "type": "string",
      "description": "Titre du produit"
    },
    "price": {
      "type": "number",
      "description": "Prix en GBP"
    },
    "availability": {
      "type": "string",
      "enum": ["in stock", "out of stock", "preorder"]
    },
    "image_link": {
      "type": "string",
      "format": "uri"
    },
    "brand": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "link": {
      "type": "string",
      "format": "uri"
    }
  },
  "required": ["id", "title", "price", "availability", "link"]
}

Champs courants et leurs contraintes

Les champs techniques standard que vous pouvez inclure dans votre schéma :

Validation du schéma

La validation s'effectue en deux étapes :

1. Validation syntaxique : vérification que le JSON est bien formé et conforme à la spécification JSON Schema.
2. Validation sémantique : vérification que vos données produits correspondent aux types et contraintes définis.

Un schéma invalide empêche l'activation de la destination. Les erreurs courantes incluent :

• Types de données incompatibles (nombre fourni pour un champ string).
• Champs obligatoires manquants dans les produits.
• Format d'URL invalide pour image_link ou link.
• Énumération de valeurs non respectée (ex: availability en dehors des valeurs autorisées).

Avant d'activer votre destination, effectuez un test d'envoi avec au moins cinq produits représentatifs. Vérifiez que l'endpoint reçoit les données et que le statut HTTP de réponse est 200 ou 201.

Intégration et gestion des données en temps réel

Envoi en temps réel versus par lots

Mode temps réel : chaque modification de produit (prix, stock, titre) déclenche immédiatement un envoi vers votre endpoint. Ce mode garantit que vos données distantes restent synchronisées avec votre source, mais génère un volume d'appels API plus important.

Mode par lots : les produits sont groupés et envoyés selon un calendrier défini (une fois par jour, une fois par semaine). Ce mode réduit la charge sur votre endpoint et consomme moins de bande passante, mais introduit un délai entre la modification et la transmission.

Choisissez le mode selon vos besoins métier. Les systèmes d'analyse et les entrepôts de données tolèrent généralement les mises à jour quotidiennes. Les systèmes de synchronisation de catalogue en temps réel (comme les marketplaces) exigent souvent le mode temps réel.

Gestion des erreurs et des tentatives

Si votre endpoint retourne une erreur (statut 4xx ou 5xx), la destination applique une stratégie de retry automatique. Vous pouvez configurer :

• Le nombre de tentatives (par défaut 3).
• L'intervalle entre les tentatives (délai exponentiel par défaut).
• Le comportement en cas d'échec final (ignorer, enregistrer en log, alerter).

Un endpoint indisponible ne bloque pas le traitement des autres destinations. Les données sont mises en queue et renvoyées lors des tentatives suivantes.

Authentification et sécurité

Méthodes d'authentification supportées

Clé API (API Key) : transmise en en-tête personnalisé.

X-API-Key: votre_clé_secrète

Bearer Token : format standard OAuth 2.0.

Authorization: Bearer votre_token_jwt

En-têtes personnalisés : vous définissez le nom et la valeur.

X-Custom-Auth: valeur_personnalisée

Authentification basique : encodage base64 de nom d'utilisateur et mot de passe (non recommandé sans HTTPS).

Bonnes pratiques de sécurité

1. Utilisez toujours HTTPS pour votre endpoint. Les connexions non chiffrées sont refusées.
2. Stockez les credentials dans des variables d'environnement, pas en dur dans votre configuration.
3. Changez régulièrement vos clés API et tokens.
4. Validez les en-têtes reçus côté serveur pour vérifier l'authenticité des requêtes.
5. Utilisez des certificats SSL valides et à jour sur votre endpoint.

Cas d'usage pratiques

Synchronisation avec un entrepôt de données

Vous opérez une plateforme d'analyse interne. Configurez une destination JSON personnalisée pour envoyer vos produits vers votre data warehouse chaque nuit. Le schéma inclut id, title, price, availability, brand, et product_type. Votre système backend reçoit le JSON, l'insère dans une table de staging, puis met à jour votre modèle de données analytiques.

Intégration avec un service tiers

Vous utilisez une plateforme de gestion de contenu (CMS) ou un outil de merchandising externe. Créez une destination JSON personnalisée avec un endpoint fourni par le fournisseur. Incluez tous les champs pertinents (image_link, description, price, link) pour que le CMS puisse afficher vos produits sans appels API supplémentaires.

Alimentation d'une application mobile

Votre application mobile a besoin d'un catalogue produit à jour. Configurez une destination JSON personnalisée qui envoie les données vers une API mobile dédiée. Incluez id, title, image_link, price, availability, et une URL de détail. L'application télécharge régulièrement ce flux pour mettre à jour son cache local.

Bonnes pratiques de configuration

Optimisation du schéma

1. Incluez uniquement les champs nécessaires. Chaque champ supplémentaire augmente la taille du payload et le temps de traitement.
2. Définissez des types de données stricts. Évitez les unions de types (string | number) qui compliquent la validation.
3. Utilisez des énumérations pour les champs avec un ensemble de valeurs fixes (availability, condition).
4. Fournissez des descriptions claires pour chaque champ, facilitant la maintenance future.

Optimisation de la performance

1. Ajustez la taille des lots selon la capacité de votre endpoint. Une taille trop grande peut causer des timeouts.
2. Configurez des timeouts appropriés (30 à 60 secondes généralement). Un timeout trop court génère des faux positifs d'erreur.
3. Compressez les payloads volumineux en utilisant gzip si votre endpoint le supporte.
4. Surveillez les logs pour identifier les patterns d'erreur et ajuster votre configuration.

Maintenance et mise à jour

1. Versionnez votre schéma. Si vous modifiez la structure, testez d'abord en environnement de développement.
2. Documentez les changements effectués sur votre schéma pour votre équipe et vos partenaires.
3. Testez les migrations avant de déployer un nouveau schéma en production.
4. Gardez un historique des versions antérieures pour déboguer les problèmes rétroactifs.

Guidance pratique pour les marchands

Mise en place étape par étape

Étape 1 : Définissez votre cas d'usage. Quel système backend doit recevoir vos données ? Quels champs sont essentiels ?

Étape 2 : Documentez votre schéma. Listez chaque champ, son type, sa cardinalité (obligatoire ou optionnel), et ses contraintes.

Étape 3 : Créez le schéma JSON. Utilisez un validateur JSON Schema en ligne pour vérifier la syntaxe.

Étape 4 : Configurez l'endpoint. Assurez-vous que votre serveur backend expose un endpoint HTTPS qui accepte POST ou PUT.

Étape 5 : Testez localement. Envoyez un payload d'exemple à votre endpoint avec curl ou Postman pour vérifier la réception.

Étape 6 : Créez la destination. Dans le tableau de bord, remplissez l'URL endpoint, la méthode HTTP, et le schéma JSON.

Étape 7 : Testez en production. Envoyez quelques produits de test et vérifiez que votre backend les reçoit correctement.

Étape 8 : Activez la destination. Une fois les tests réussis, activez la destination pour commencer la synchronisation réelle.

Dépannage courant

Problème : erreur 401 (non autorisé)
Vérifiez que votre clé API ou token est correct et que l'en-tête d'authentification est bien formé. Testez manuellement votre endpoint avec curl pour isoler le problème.

Problème : erreur 400 (mauvaise requête)
Votre endpoint rejette le format JSON. Vérifiez que votre schéma produit des payloads valides. Comparez un exemple d'envoi avec la documentation de votre endpoint.

Problème : timeout (délai dépassé)
Votre endpoint met trop de temps à répondre. Augmentez le timeout, optimisez votre backend, ou réduisez la taille des lots.

Problème : données incomplètes
Vérifiez que tous les champs obligatoires de votre schéma sont présents dans vos produits source. Un produit manquant un champ obligatoire ne sera pas envoyé.

Conclusion

Les destinations JSON personnalisées offrent une flexibilité complète pour distribuer vos données produits à n'importe quel système backend. En définissant un schéma clair, en configurant l'authentification correctement, et en suivant les bonnes pratiques de validation et de test, vous créez un pipeline de données robuste et maintenable.

La clé du succès réside dans la clarté de votre schéma et la fiabilité de votre endpoint. Investissez du temps dans la documentation et le test initial pour éviter les problèmes en production. Une fois en place, une destination JSON personnalisée synchronise vos données de manière fiable, permettant à vos systèmes backend de rester à jour sans intervention manuelle.