Synchronisation des données de référence via FTP

1. Contexte

Hyperfox conserve une copie des données de base afin de pouvoir faire correspondre les données de commande des clients. Pour ce faire, un processus de synchronisation doit être mis en place pour exporter les données de base concernées.

2. Solution technique

Une procédure d'export dépose des fichiers CSV sur un serveur FTP fourni par Hyperfox. Ces fichiers doivent être déposés sur le FTP chaque jour (ouvré) à une heure convenue, après quoi Hyperfox les récupère à une heure ultérieure également convenue. Les horaires précis sont définis lors de l'implémentation.

2.1 FTP : structure des dossiers et conventions

Le FTP Hyperfox est fourni par défaut avec la structure de dossiers suivante :

• PROD
  • Dropbox — c'est ici que les exports des données de base doivent être déposés.
  • Orders — c'est ici qu'Hyperfox dépose les fichiers de commande.
  • Files — c'est ici qu'Hyperfox dépose les demandes de commande (e-mail, PDF, etc.).
  • Accept — des fichiers confirmant l'acceptation des commandes peuvent être déposés ici.
• QA
  • Dropbox
  • Orders
  • Files
  • Accept

3. Spécifications des fichiers

Tous les fichiers doivent respecter les spécifications suivantes :

• CSV, séparé par des virgules.
• Taille maximale du fichier : 25 Mo.
• Encodage : UTF-8.
• Les en-têtes de colonnes doivent être présents dans le fichier.
• Le contenu des fichiers doit toujours correspondre à l'extraction complète de la base de données, et non au delta par rapport à la livraison précédente.
• Le nom du fichier ne peut pas contenir de variables (par ex. la date d'export). Nous attendons toujours le même nom de fichier.
  • Non : export_items_20251023.csv, où 20251023 change à chaque export.
  • Mais : export_items.csv.

3.1 Noms des colonnes

Les noms des colonnes ne doivent pas nécessairement correspondre aux noms des colonnes dans Hyperfox. Tant que le contenu est présent dans les fichiers, nous pouvons le mapper dans Hyperfox par configuration. Hyperfox dispose d'un outil de mappage visuel permettant de relier les noms des colonnes du fichier aux noms des colonnes dans Hyperfox.

4. Structures de données

Des champs supplémentaires décrivant ou identifiant de manière unique les enregistrements peuvent toujours être ajoutés à n'importe lequel des fichiers ci-dessous.

4.1 Données de tiers (obligatoire)

La structure de données qui décrit un tiers. Un tiers peut être le client qui a envoyé la commande, ou le tiers auquel les marchandises doivent être livrées.

Champ	Description	Obligatoire	Remarque
Account ID	Référence unique de ce tiers	Oui
Name		Oui
Street name		Oui
Additional street name		Non
Number		Oui
City Name		Oui
Postal Zone	Code postal de l'adresse	Oui
Country		Oui	Code pays ISO (par ex. BE, NL)
VAT Number		Non
Contact Name		Non
Contact Telephone		Non
Contact Email		Non

4.2 Données article (obligatoire)

La structure de données qui décrit les produits.

Champ	Description	Obligatoire	Remarque
Name	Nom du produit	Non : s'il y a une description
Description		Non : s'il y a un nom
SKU	Référence unique de cet article	Oui
EAN	Code-barres	Non
Base Unit Code	L'unité de mesure standard dans laquelle l'article est tenu en stock. Utilisée comme unité cible de conversion lorsqu'une commande est passée dans une autre unité de mesure.	Non	Exemples de valeurs : S, PALLET, Carton, Box.
Image URL	URL de l'image du produit	Non	Ratio 1:1. De préférence une taille maximale de 800x800.

4.3 Codes d'unité (recommandé)

La structure de données qui décrit les unités de conditionnement.

Champ	Description	Obligatoire	Remarque
Code	Le code ou l'identifiant de l'unité	Oui	Exemple : PAL
Value	Le nom ou la description de la valeur	Oui	Exemple : PALLET

4.4 Unités de mesure par article (recommandé)

La structure de données qui décrit les unités de mesure par article.

Champ	Description	Obligatoire	Remarque
Item ID	La référence unique de l'article	Oui	Généralement le SKU. Exemple : 030.70.1010CIAO
Unit code ID	La référence unique du code d'unité	Oui	Exemple : KARTON
Base unit quantity	Facteur de conversion	Oui	Exemple : 80

Exemple

• Nous avons l'article suivant : SKU 030.70.1010CIAO, dont l'unité de base (Base Unit) est KARTON.
• Dans une commande, nous recevons : 1 pallet 030.70.1010CIAO.

Hyperfox recalcule toujours vers l'unité de base configurée au niveau de l'article. Dans ce cas : KARTON.

Autrement dit, nous avons besoin de l'information indiquant combien de KARTON sont présents sur une PALLET pour le SKU 030.70.1010CIAO.

En supposant qu'une palette contienne 80 cartons, les données doivent être livrées comme suit :

• Item ID : 030.70.1010CIAO
• Unit Code ID : PALLET
• Base unit quantity : 80

4.5 Articles par tiers (facultatif)

Définit quels produits sont commandables par client. Utilisé pour affiner la correspondance des produits.

Champ	Description	Obligatoire	Remarque
Item ID	La référence unique de l'article	Oui	Généralement le SKU.
Party ID	La référence unique du tiers	Oui	Généralement l'Account ID.

4.6 Données d'historique de commandes (facultatif)

Les informations d'historique de commandes sont prises en compte comme contexte supplémentaire, ce qui nous permet d'améliorer la précision de l'analyse en apprenant des habitudes et des préférences de commande propres au client.

Champ	Description	Obligatoire	Remarque
Item ID	La référence unique de l'article	Oui	Généralement le SKU.
Party ID	La référence unique du tiers	Oui	Généralement l'Account ID.
Timestamp	Date à laquelle cet article a été commandé. La composante horaire est facultative.	Oui	Exemple : 2026-01-19 10:44:06