Reference Data Synchronisation via FTP

1. Context

Hyperfox stores a copy of the master data so that we can match customers' order data. To facilitate this, a synchronisation process must be set up that exports the relevant master data.

2. Technical Solution

Via an export procedure, CSV files are placed on an FTP server provided by Hyperfox. These files must be placed on the FTP every (working) day at an agreed time, after which Hyperfox picks them up at a later agreed time. Concrete times are agreed during implementation.

2.1 FTP: Folder Structure and Conventions

The Hyperfox FTP is provided by default with the following folder structure:

• PROD
  • Dropbox — this is where the exports of the master data must be placed.
  • Orders — this is where Hyperfox places order files.
  • Files — this is where Hyperfox places the order requests (email, PDF, etc.).
  • Accept — files can be placed here that confirm the acceptance of orders.
• QA
  • Dropbox
  • Orders
  • Files
  • Accept

3. File Specifications

All files must meet the following specifications:

• CSV, comma-separated.
• Maximum file size: 25 MB.
• Encoding: UTF-8.
• Column headers must be present in the file.
• The contents of the files must always be the complete extraction from the database, not the delta compared to the previous delivery.
• The file name may not contain variables (e.g. export date). We always expect the same file name.
  • Not: export_items_20251023.csv, where 20251023 changes with each export.
  • But: export_items.csv.

3.1 Column Names

The column names do not need to match the column names in Hyperfox. As long as the content is present in the files, we can map this in Hyperfox through configuration. Hyperfox has a visual mapper where the column names in the file can be linked to the column names in Hyperfox.

4. Data Structures

Additional fields that describe or uniquely identify the records may always be added to any of the files below.

4.1 Party Data (required)

The data structure that describes a party. A party can be the customer who sent the order, or the party where the goods need to be delivered.

Field	Description	Required	Remark
Account ID	Unique reference for this party	Yes
Name		Yes
Street name		Yes
Additional street name		No
Number		Yes
City Name		Yes
Postal Zone	Postal code of the address	Yes
Country		Yes	ISO country code (e.g. BE, NL)
VAT Number		No
Contact Name		No
Contact Telephone		No
Contact Email		No

4.2 Item Data (required)

The data structure that describes the products.

Field	Description	Required	Remark
Name	Product name	No: if there is a description
Description		No: if there is a name
SKU	Unique reference for this item	Yes
EAN	Barcode	No
Base Unit Code	The standard unit of measure in which the article is kept in stock. Used as the target unit to convert to when an order is placed in a different unit of measure.	No	Example values: S, PALLET, Carton, Box.
Image URL	URL to the image of the product	No	1:1 ratio. Preferably a max size of 800x800.

4.3 Unit Codes (recommended)

The data structure that describes the packaging units.

Field	Description	Required	Remark
Code	The code or ID of the unit	Yes	Example: PAL
Value	The name or description of the value	Yes	Example: PALLET

4.4 Item Units of Measure (recommended)

The data structure that describes the units of measure per item.

Field	Description	Required	Remark
Item ID	The unique reference to the item	Yes	Usually the SKU. Example: 030.70.1010CIAO
Unit code ID	The unique reference to the unit code	Yes	Example: KARTON
Base unit quantity	Conversion factor	Yes	Example: 80

Example

• We have the following item: SKU 030.70.1010CIAO, where the Base Unit = KARTON.
• In an order we receive: 1 pallet 030.70.1010CIAO.

Hyperfox will always recalculate towards the base unit, which is configured on the item level. In this case: KARTON.

In other words, we need the information which tells us how many KARTON are present on a PALLET for SKU 030.70.1010CIAO.

Assuming a pallet holds 80 cartons, the data should be delivered as follows:

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

4.5 Party Items (optional)

Defines which products are orderable per customer. Used to narrow down product matching.

Field	Description	Required	Remark
Item ID	The unique reference to the item	Yes	Usually the SKU.
Party ID	The unique reference to the party	Yes	Usually the Account ID.

4.6 Order History Data (optional)

Order history information is taken into account as additional context so that we can improve parsing accuracy by learning from the customer's typical ordering patterns and preferences.

Field	Description	Required	Remark
Item ID	The unique reference to the item	Yes	Usually the SKU.
Party ID	The unique reference to the party	Yes	Usually the Account ID.
Timestamp	Date on which this was ordered. The time component is optional.	Yes	Example: 2026-01-19 10:44:06